Restaurant QR Menu Program Implementation Plan

For Codex: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Deliver a multi-tenant DailyMark module that imports, enriches, publishes, serves, and analyzes static restaurant menus on QR-friendly DailyMark subdomains or verified custom domains.

Architecture: The authenticated DailyMark app manages mutable drafts and asynchronous jobs. Publication produces immutable static bundles in S3-compatible storage; a separate read-only gateway serves the active bundle by host. OCR, text/image generation, video/3D, domains/QR, and analytics are separate workstreams behind stable contracts.

Tech Stack: TypeScript, Bun, NestJS 11, TypeORM/PostgreSQL FORCE RLS, Redis/BullMQ, Next.js 16, React 19, Ant Design 6, Caddy 2, S3-compatible object storage, Vitest/Bun test, Playwright.

Global Constraints

• Reuse existing DailyMark tenants, memberships, locations, roles, billing, authentication, CSRF, impersonation, audit, and observability conventions.
• Preserve Role.Owner > Role.Admin > Role.Member; do not invent a fourth persisted role. Product labels map owner → owner, admin → manager, member → editor.
• New tenant business tables require explicit TypeORM migrations, entity registration in apps/api/src/db/data-source.ts, runtime RLSModule.forFeature, ENABLE ROW LEVEL SECURITY, and FORCE ROW LEVEL SECURITY.
• Write a failing test before each implementation change; run the narrow test before the relevant suite.
• Store timestamps as timestamptz and serialize UTC.
• OCR and AI results are review candidates; they never auto-publish or silently change price, ingredients, or allergens.
• Published bundles are immutable; failed builds never replace the active publication.
• Critical JavaScript ≤50 KB gzip; HTML + CSS + critical JavaScript ≤150 KB gzip excluding media; video and 3D never enter initial load.
• Public analytics is cookieless by default and never trusts a client-supplied tenant ID.
• Do not run heavy OCR, image, video, or 3D model computation on the production VPS; use provider adapters and bounded workers.
• Before dependency installation, migration execution, CI/CD edits, or infrastructure changes, obtain the approval required by .agent/protocols/permissions.md.
• Preserve the user's existing AGENTS.md change and do not stage .agent/memory/working/.

---

Plan Set and Dependency Graph

Order	Workstream	Detailed plan	Depends on	Independently testable result
1	Core menu + static publishing	2026-08-09-restaurant-menu-core-publishing-plan.md	Existing auth/RLS/location stack	Tenant can CRUD, preview, publish, serve, and roll back a static menu
2	Domains + QR	2026-08-09-restaurant-menu-domains-qr-plan.md	Core publication manifest/gateway	Stable QR works on wildcard subdomain and verified custom domain
3	PDF/image import	2026-08-09-restaurant-menu-document-import-plan.md	Core draft API, private object storage	PDF/scan becomes a reviewed draft merge proposal
4	AI text + images	2026-08-09-restaurant-menu-ai-content-plan.md	Core items/media/storage; billing status	Reviewed descriptions, translations, and images attach to items
5	Video + 3D	2026-08-09-restaurant-menu-rich-media-plan.md	AI job/media lifecycle and public renderer	Reviewed video/GLB is lazy-loaded with an image fallback
6	Tenant analytics	2026-08-09-restaurant-menu-analytics-plan.md	Core publication manifest and renderer extension points	Tenant dashboard reports privacy-oriented menu engagement

Workstreams 3 and 4 may begin in parallel only after the core entity, object-store, media, and draft-service contracts are merged. Workstream 6 begins by adding its signed publication-token contract after the core manifest and renderer extension points are stable. Workstream 5 starts after Workstream 4 because it reuses the job, cost, review, and media lifecycle.

Program Milestones

Milestone A — Foundations accepted

• [ ] Product owner approves the design spec and this plan set.
• [ ] Engineering confirms ownership for API, web, gateway, infrastructure, privacy, and provider operations.
• [ ] Security reviews the RLS strategy, exact-host TLS authorization, upload quarantine, signed analytics token, and public gateway boundary.
• [ ] Finance/product approves storage, OCR, AI image, video, and 3D monthly cost ceilings.
• [ ] Operations chooses an S3-compatible production store and creates dev/staging/prod buckets with private-by-default policies.
• [ ] DNS owner confirms wildcard record and a DNS-challenge automation method for *.dailymark.me.
• [ ] Required dependency, migration, and CI/CD approvals are recorded before execution.

Exit evidence: decision log, owners, budgets, storage/DNS runbooks, and approval references are linked from the implementation issue.

Milestone B — Static-menu MVP

• [ ] Workstream 1 acceptance suite is green.
• [ ] Workstream 2 subdomain and QR acceptance suite is green.
• [ ] A staging tenant publishes and rolls back a three-section RU/EN/SR menu.
• [ ] The stable QR URL survives two publications and one rollback.
• [ ] The menu remains available during an intentional management API outage.
• [ ] Bundle and accessibility budgets pass on mobile.

Exit evidence: staging URLs, build manifest/checksums, Playwright report, RLS report, outage drill, and rollback log.

Milestone C — Assisted content

• [ ] Workstream 3 imports the approved PDF and scan fixture corpus.
• [ ] Workstream 4 produces reviewed text, translations, and images with provenance and cost.
• [ ] No fixture can auto-apply an uncertain price or allergen.
• [ ] Tenant generation quotas and owner-visible usage are verified.

Exit evidence: fixture report, review audit records, cost ledger, and cross-tenant tests.

Milestone D — Rich media and analytics

• [ ] Workstream 5 produces validated video and GLB with fallbacks and lazy loading.
• [ ] Workstream 6 ingests, aggregates, displays, exports, and deletes tenant analytics.
• [ ] Analytics/privacy review approves the default event schema and retention.
• [ ] Gateway and collector load tests meet the approved traffic model.

Exit evidence: media validation report, mobile performance trace, analytics retention/export/deletion audit, privacy sign-off, and load-test result.

Milestone E — Production readiness

• [ ] All workstream launch gates are complete.
• [ ] Backup/restore and publication rollback drills pass in staging.
• [ ] Custom-domain verification and Caddy denial tests pass with known-good and unknown hosts.
• [ ] Alerts exist for public availability, queue age, publication failure, TLS failures, storage thresholds, analytics reject rate, and generation cost.
• [ ] Tenant documentation, support scripts, incident runbooks, and legal copy are published.
• [ ] Production deployment has explicit human approval.

Management Checklists

Product backlog readiness

• [ ] Every ticket names one workstream and one plan task.
• [ ] Ticket lists exact user role, tenant boundary, happy path, failure path, and acceptance evidence.
• [ ] UI tickets include RU/EN/SR copy and empty/loading/error/review states.
• [ ] AI tickets identify authoritative facts, prohibited invention, review actor, provider cost, and retention.
• [ ] Public-delivery tickets state cache behavior, fallback behavior, and performance budget.
• [ ] Analytics tickets state event schema version, authoritative server dimensions, retention, and tenant query.
• [ ] Infrastructure tickets name environment, rollback, observability, and approval owner.

Sprint planning

• [ ] Pull only tasks whose consumed interfaces already exist or are in the same reviewed batch.
• [ ] Pair every migration with entity registration, RLS policy, revert path, and e2e test.
• [ ] Pair every job with idempotency key, timeout, retry class, terminal state, and cost accounting.
• [ ] Pair every provider adapter with deterministic fake and signed callback fixture.
• [ ] Reserve capacity for accessibility, performance, security, docs, and runbook work; these are not post-MVP cleanup.
• [ ] Do not schedule production provider work before commercial/data-processing approval.

Pull-request review

• [ ] Diff touches only the intended task and specific files.
• [ ] Failing test is visible in commit history or task evidence before implementation.
• [ ] Cross-tenant negative tests exist for every new tenant resource.
• [ ] Public endpoints do not accept authoritative tenant identity from the client.
• [ ] Logs and errors exclude documents, private prompts, raw provider output, credentials, and visitor IP.
• [ ] Queue processors are retry-safe and duplicate webhook/event delivery is harmless.
• [ ] Publication failure preserves the active manifest.
• [ ] UI includes keyboard, focus, reduced-motion, and fallback states.
• [ ] New copy exists in all three message catalogs.
• [ ] Documentation and operational changes accompany new external dependencies.

Provider onboarding

• [ ] Legal entity, billing account, data region, DPA, content rights, and retention are approved.
• [ ] Staging and production credentials are separate and delivered only through environment secrets.
• [ ] Webhook origin, signature algorithm, timestamp tolerance, replay behavior, retry policy, and rate limits are documented.
• [ ] Model/provider identifiers are configuration, not hard-coded business logic.
• [ ] Cost units map to the DailyMark cost ledger and tenant quotas.
• [ ] Provider outage and malformed-output drills pass with the deterministic adapter contract.
• [ ] A provider can be disabled without breaking existing published menus.

Domain and QR onboarding

• [ ] Requested subdomain is normalized, unreserved, and globally unique.
• [ ] Custom domain ownership and DNS routing are both verified.
• [ ] Caddy ask returns allow only for the exact active hostname.
• [ ] Unknown, disabled, Unicode-confusable, IP-literal, and reserved hosts are denied.
• [ ] TLS certificate state and renewal health are visible to operations.
• [ ] Printed QR is scanned on iOS and Android at the intended physical size.
• [ ] Campaign label/location is recorded before printing.

Tenant launch

• [ ] Owner and manager roles are assigned and editor publication denial is tested.
• [ ] Primary currency, locale, locations, branding, and factual-responsibility copy are confirmed.
• [ ] Imported prices, ingredients, allergens, translations, and media candidates are reviewed.
• [ ] Draft preview passes mobile, language, image, video/3D fallback, and accessibility review.
• [ ] Initial publication and rollback point are verified.
• [ ] Subdomain/custom domain and QR campaigns open the same active publication.
• [ ] Analytics events appear only in the launching tenant dashboard.
• [ ] AI/media budgets and alerts are enabled.

Release and deployment

• [ ] Relevant unit, integration, e2e, RLS, provider contract, accessibility, and performance suites are green.
• [ ] No unresolved placeholder or disabled security check exists in the release diff.
• [ ] Migration was tested up/down/up against the test database and backup/restore impact was reviewed.
• [ ] Staging publication, domain verification, TLS, QR, provider callbacks, analytics, and rollback are exercised.
• [ ] Object lifecycle rules protect active and rollback publications.
• [ ] Monitoring dashboards and alerts are active before traffic.
• [ ] Human approval is recorded before production migration or deployment.

Weekly operations

• [ ] Review public-menu availability and p95 gateway latency.
• [ ] Review queue age, failed/dead-letter jobs, provider error classes, and webhook rejection.
• [ ] Review generation spend by tenant and provider against budgets.
• [ ] Review storage growth, orphan cleanup, active/rollback protection, and lifecycle failures.
• [ ] Review custom-domain verification/TLS failures and certificates approaching renewal risk.
• [ ] Review analytics reject/drop/bot rates and retention-run completion.
• [ ] Sample a published bundle for CSP, accessibility, cache headers, and fallback integrity.

Incident response

• [ ] Classify impact: management-only, publication, public delivery, TLS/domain, provider, media, or analytics.
• [ ] Preserve active publication; stop new jobs or publication before changing public artifacts.
• [ ] Disable affected provider/collector feature flag when public menu delivery can remain healthy.
• [ ] Use correlation IDs and immutable publication IDs; do not inspect unrelated tenant content.
• [ ] Roll back manifest or application version using the documented path.
• [ ] Confirm tenant isolation and data integrity after recovery.
• [ ] Record timeline, cost/data exposure, affected tenants, remediation, and a regression test.

Definition of Done for Each Workstream

• [ ] Every task in its detailed plan is complete with narrow and suite-level test evidence.
• [ ] File/interface ledger matches implemented names and signatures.
• [ ] RLS and cross-tenant evidence covers every new tenant table or public identity path.
• [ ] Empty/loading/error/retry/fallback states are implemented and translated.
• [ ] Observability and runbooks cover new queues, providers, public endpoints, and retention.
• [ ] Documentation describes tenant and operator workflows.
• [ ] Workstream acceptance scenario runs in staging.
• [ ] Reviewer verifies the workstream against the design spec, not only against passing tests.

Objective-to-Evidence Matrix

Original requirement	Authoritative completion evidence
Manage and generate static HTML menus	Workstream 1 CRUD/renderer/publication/rollback tests and staging bundle manifest
QR on *.dailymark.me	Workstream 2 wildcard staging URL, stable QR test, DNS/TLS runbook
Custom domain	Workstream 2 verification + exact-host Caddy ask tests and staging certificate
Recognize uploaded menu document	Workstream 3 golden PDF/photo corpus and reviewed merge e2e
Generate item images/descriptions with AI	Workstream 4 provider contract, review audit, provenance, cost tests
Generate item 3D animation or video	Workstream 5 validated MP4/GLB, fallback, lazy-load and review e2e
Per-tenant menu analytics	Workstream 6 signed event, cross-tenant, aggregate/dashboard/export/deletion tests
Management checklists	This program plan's readiness, review, launch, release, operations, and incident checklists

Plan Completion Gate

• [ ] All six detailed plan documents exist and start with the required worker header.
• [ ] No placeholder marker, vague cross-reference, unnamed error handling, or undefined interface remains.
• [ ] Every design-spec requirement maps to at least one task and one evidence source.
• [ ] Shared type/function names are consistent across plan files.
• [ ] User selects an execution mode before code implementation begins.