menu/docs/plan.md

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-app.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 navigation is made of the restaurant's own paper: the landing is a row of cards, each one the first page of a menu with the category name over it and the page count on a strip beneath, scrolling sideways and snapping (wrapping into a grid on a wide screen). The bar links every menu as a filled segment, the current one the only teal thing on screen, and a 2px brass line under it tracks how far through the pages you are.

┌────────────────────────────┐   ┌────────────────────────────┐
│ 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 Site's brand and theme live in config/<site>.site.json, baked into the image and selected with MENU_SITE_CONFIG; its Section list only seeds data/sections.json the first time. Categories are edited in the admin from then on (ADR 0007), so adding one does not need a redeploy.
• 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-app.<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-app.<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. Commit nginx-menu/ to git so the current state is reproducible and revertible; create the menu-admin repo and move CONTEXT.md, docs/, and the ADRs into it.
2. Storage layer: config, manifest read/write, atomic writes, boot validation, tests.
3. Image pipeline: sharp variants, content-hashed filenames, tests.
4. Public renderer: landing, Section and archive routes, design tokens and CSS.
5. Admin: login, upload with browser pre-shrink, ordering, preview, publish/restore/delete.
6. Container, compose dev fixtures, Ansible role, deploy to menu-new.hopsngrains.com, verify from a phone on restaurant wifi.
7. Cutover: re-upload the current Food, Bar and Delivery menus, create What's On from the posters, switch menu.hopsngrains.com to the app, stop the old nginx container.
8. After a week: remove the old container and /var/lib/menu.hopsngrains.com, delete the dated folders, drop the dead Caddyfile, and reduce this folder to dev fixtures.

Deleting the old 319MB directory is the only irreversible step, so it is last.

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.