# Menu app — agreed plan

Replaces the `scp`-a-JPG workflow for `menu.hopsngrains.com` with a small self-hosted app that uploads, orders, previews and publishes Menu Sets. Verified against the current environment by read-only reconnaissance of `monoco`.

## What exists today

- Caddy (80/443, TLS) → `reverse_proxy nginx-menu.hopsngrains.com:80` → `nginx:alpine` with `-v /var/lib/menu.hopsngrains.com:/usr/share/nginx/html:ro`.
- Each Section is a hand-written `index.html` listing one `<img>` per JPG, with a vendored copy of Materialize CSS/JS in every Section folder.
- The read-only mount is why content can only be changed over SSH. `static-menu/Caddyfile` is dead config from the retired `caddy-menu` playbook and is read by nothing.
- The same playbook serves three Sites: `menu.hopsngrains.com` (319M, this folder), `menu.hngmohali.com` (208M), `menu.greatbear.in` (405M). Remote disk: 15G free, 82% used.
- `nginx-menu/` is untracked in the `ansible-playbooks` repo (`git.tanshu.com:tanshu/playbooks`). Sibling projects build an image locally, push to `registry.tanshu.com`, then run `ansible-playbook -e tag=`.

## Decisions

| Question | Decision |
| --- | --- |
| Upload path | Small self-hosted app on the same host, replacing `scp` |
| Serving | The app serves HTML **and** images; nginx is retired per Site (ADR 0001) |
| Rendering | Per request, server-rendered HTML (ADR 0003) |
| Stack | Node + Fastify + `sharp`, one container |
| Metadata | JSON manifests, state encoded in the directory layout (ADR 0002) |
| Scope | One app instance per Site (ADR 0004); other two Sites migrate later |
| Categories | Content, not configuration: added, renamed, reordered and removed in the admin (ADR 0007, superseding ADR 0005) |
| Lifecycle | Draft → Current → Archive; publishing auto-archives the previous set; archives unlisted but reachable. A published set's Pages are fixed, but the Current set's order can be corrected (ADR 0006) |
| Auth | Single shared password per Site; app login; hash + session secret in an untracked `.env` on the server |
| Images | 1600px viewing WebP + JPEG fallback, 480px admin-only thumbnails, Originals kept and never served |
| Logging | JSON to stdout only; no Prometheus, no Promtail |
| Backups | Owner's existing backups; out of scope |

## Domain

`CONTEXT.md` is the glossary. This Site starts with Food, Bar, Wine, Straight Drinks, Delivery and What's On; the owner adds and renames categories from the admin. One Current Menu Set per Section, and a Section with no Current set does not appear on the landing page.

## Architecture

### Topology

```
caddy (80/443, TLS) ──reverse_proxy──▶ menu-app.hopsngrains.com:3000
                                          ├── renders landing, Section, archive pages
                                          └── serves viewing images
                        (nginx-menu.hopsngrains.com retired after cutover)
```

### Storage

```
/var/lib/menu.hopsngrains.com/
├── site.env                        # ADMIN_PASSWORD_HASH, SESSION_SECRET (mode 600, untracked)
└── data/
    ├── originals/<section>/<set-id>/<page-id>.<hash>.<ext>   # never served
    ├── drafts/<section>/<set-id>/                  # manifest.json + variants
    └── published/<section>/<slug>/                 # manifest.json + variants
```

- `<slug>` is the valid-until date when set, else the publication date (`YYYY-MM-DD`), suffixed `-2` on collision.
- Directory encodes state: `drafts/` is invisible to customers, `published/` is reachable.
- Editing rules: a Draft accepts anything; the Current set accepts reordering only (order is presentation, ADR 0006); an Archive is frozen.
- `manifest.json` holds `id`, `section`, `label`, `validUntil`, `createdAt`, `publishedAt` and the ordered Page list; each Page carries its own `id`, content hash, source extension, the Viewing image's dimensions and the uploaded filename.
- **Current** is the published set for a Section with the newest `publishedAt`; everything else published is an Archive. No separate current pointer exists to drift.
- Writes are temp file + `fsync` + rename, and publishing is a directory rename, so a crash leaves either a Draft or a published set. `publish`/`archive` serialize behind one in-process lock. Boot validation checks that every manifest matches its directory and that Page files exist.

### Routes

| Route | Purpose |
| --- | --- |
| `GET /` | Landing page: the shelves, one per Section with a Current set |
| `GET /<section>/` | Current Menu Set |
| `GET /<section>/<slug>/` | Archived Menu Set (unlisted, still reachable) |
| `GET /<section>/#page-N` | Deep link to one Page |
| `GET /media/<page-id>.<hash>.webp\|.jpg` | Viewing image, `immutable` cache; keyed by Page id so the URL survives publish |
| `GET /admin/*` | Admin, session required, `noindex` |
| `GET /admin/sets/<id>/preview` | Draft rendered exactly as customers would see it |

Unknown Sections and Sections without a Current set 404 rather than redirect, so a stale printed link fails loudly instead of showing the wrong menu. Media for a Draft is served only to a session holder, which is what keeps Drafts unreachable in practice.

### Image pipeline

- Accept JPEG/PNG/WebP up to 30MB, up to 40 Pages per set; anything else is rejected with a message naming the file.
- The browser pre-shrinks to 3000px on the long edge before upload (fast over restaurant wifi); if the browser cannot decode the file, the file is uploaded untouched.
- Server: apply EXIF orientation, strip all other metadata, write the Original, generate a 1600px WebP (q80) + JPEG (q82) Viewing image and a 480px WebP Thumbnail.
- Variant filenames carry a short content hash and are keyed by Page id, so a replaced Page cannot be served from a stale cache and a published URL keeps working across a re-publish.

### Admin

Log in; see each Section with its Current set and state; create a Menu Set (choose Section, add Pages, drag to reorder, set label and optional valid-until, thumbnail grid); preview; publish (archives the previous set); restore an Archive as Current; delete a Draft or Archive. No user management, no scheduling, no Section editing, no password-change flow (edit `site.env` and restart).

Protection: a `scrypt` hash (from `node:crypto`, so no native build dependency) in `site.env`, httpOnly + Secure + SameSite=Lax session cookie, login throttled per IP, `noindex` on all admin routes. Originals and Drafts have no public route at all.

### Customer design

The look is the Atelier Dining & Hospitality system from Stitch (`docs/design/stitch/`): warm ivory linen and espresso for the guest surfaces, burnished gold for the one active thing, Playfair Display carrying the restaurant's voice, Plus Jakarta Sans carrying everything transactional. The landing is an editorial directory — each category a hairline row with a small plate of that menu's paper, its name in Playfair, a dot leader and a tabular page count. The bar names the restaurant, links every menu as a pill (the current one espresso-filled), and a gold hairline under it tracks progress through the pages. The administrative side is the same system in its dark mode: espresso workspace, obsidian pods, gold actions.

```
┌────────────────────────────┐   ┌────────────────────────────┐
│ HOPS N GRAINS              │   │ HOPS N GRAINS         ⌂    │
│ Food              12 pages │   │ Bar  Food  Wine  Drinks    │
│ ────────────────────────── │   │ ▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░ │
│ Bar               20 pages │   ├────────────────────────────┤
│ ────────────────────────── │   │  ┌──────────────────────┐  │
│ Wine                       │   │  │  menu page photo     │  │
└────────────────────────────┘   │  └──────────────────────┘  │
                                 │                    3 / 12  │
                                 └────────────────────────────┘
```

- Colour: `#14181b` steel, `#1f262b` rail, `#f2efe9` paper, `#0088aa` logo teal, `#b2703b` copper.
- Type: self-hosted variable **Archivo** — expanded 600 for the brand and Section names, normal width for body and UI, tabular numerals for the counter.
- The one memorable element: a copper "pour" line in the sticky Section rail that fills as you scroll, doubling as position in a 20-page menu.
- Tapping the page counter opens a text page index for jumping; a quiet "Older menus" line at the foot of a Section page lists Archives.
- Roughly 2KB of progressive-enhancement JS for the lightbox and counter. Visible focus, `alt` text ("Bar menu, page 3 of 12"), `prefers-reduced-motion` respected, self-hosted fonts so it works on restaurant wifi.

## Repos, build and deploy

- New repo `menu-admin` on `git.tanshu.com`: app source, `Dockerfile`, `compose.yaml` for local dev, `docs/` (this plan, `CONTEXT.md`, the ADRs), `node --test` tests, and `deploy.sh` (tests, build, push).
- The container is `node:24-alpine` running TypeScript directly, so there is no build step; sharp's musl binaries come from `npm ci` on the image's own platform. It writes only under `MENU_ROOT` and healthchecks its own `/healthz`.
- The design system is documented in `docs/design/stitch/atelier-dining-hospitality.md`, with the four screens Stitch produced beside it. `config/<site>.site.json` holds the theme and the seed for everything the owner can change: it seeds `data/sections.json` (ADR 0007) and `data/site.json`, which holds the name, tagline, icon and date switch (ADR 0008). Colours stay in the config, so changing them is a rebuild; nothing else does.
- Build locally and push `registry.tanshu.com/menu-admin:<tag>`, matching the sibling `deploy.sh` / `make build-production TAG=` convention.
- New `menu-admin` playbook in `ansible-playbooks` with per-Site vars (`vars/hopsngrains.yml` first, the other two stubbed): roles `network`, `menu-app` (pull image, create `/var/lib/menu.<site>`, start container, health check, then `verify` the data directory) and `caddy` (snippet upsert).
- The existing `roles/caddy` only *adds* a snippet when its exact text is missing, which cannot change a proxy target; the new playbook's role uses a stable marker so `blockinfile` updates in place, and removes the old role's per-hostname marker at cutover so Caddy never holds two blocks for one hostname.
- One-time human step on the server: a `scripts/provision-site-env.sh` prompts for the admin password, hashes it with the image's own hasher, and writes `/var/lib/menu.<site>/site.env` (mode 600, never in git). Until it exists the admin is disabled and the public menu still serves.
- A small CLI: `verify` reports integrity problems in the data directory, `repair` regenerates missing variants from the Originals.

## Sequence

1. Storage layer: config, manifest read/write, atomic writes, boot validation, tests.
2. Image pipeline: sharp variants, content-hashed filenames, tests.
3. Public renderer: landing, Section and archive routes, design tokens and CSS.
4. Admin: login, upload with browser pre-shrink, ordering, preview, publish/restore/delete.
5. Container, compose dev fixtures, Ansible role.
6. Deploy: `make build-production TAG=<tag>` builds a multi-arch podman manifest and
   pushes it; the playbook in `ansible/` runs one Site to completion — it starts the
   container and points the Site's web address at it. There is no older system kept
   serving and nothing to retire, so there is no staged rollout; deploying an earlier
   tag is the rollback.
7. Create the admin password once per Site (`scripts/provision-site-env.sh`), then
   `npm run check-site` and a phone.

## Out of scope

Backups (owner already runs them), Prometheus metrics, Promtail/Loki integration, multi-user accounts, scheduled publishing, per-Section theming, migrating `menu.hngmohali.com` and `menu.greatbear.in`, and git history for the image content.