platepilot

PlatePilot M2 Planning and M3 Foundations Implementation Plan (backend)

Goal: Deliver the API side of M2 Planning as a generated weekly meal plan (Monday to Sunday, produced from stored preferences through a mock provider seam, editable, regenerated every Sunday morning, with a synchronized shopping list) plus plan-to-diary confirmation and shared planning, and the M3 foundations the mobile app will consume next: two-adult household invitations and sharing, a mock subscription with a photo-analysis allowance, per-adult export and verified deletion, and calm alerts through the notification seam.

Direction change (2026-09-20, product): the manual planner first built under Task 1 was replaced in place by the generated planner (ADR-0010). Existing item endpoints and SDK operations were kept; preferences, generation, and the shopping list were added.

Architecture: Every capability is a NestJS module shaped like the M1 modules: Zod contracts in packages/contracts, a repository port with a Prisma adapter, an audited service, a controller with hand-written OpenAPI schemas, and colocated unit tests plus an integration test against PostgreSQL. Provider seams stay mock-only (ADR 0003/0005). Nothing is shared between adults without an explicit sharing setting (ADR 0006/0008), plans never become diary facts without confirmation, and the allowance never gates manual entry (ADR 0009).

Tech Stack: NestJS, Zod, Prisma/PostgreSQL, LocalStack S3, Vitest, @hey-api/openapi-ts.

Status (2026-09-20): Tasks 1–7 implemented in the working tree; mobile screens are the mobile agent’s follow-up and consume packages/api-client/src/generated/sdk.gen.ts.

---

Product rules carried into this plan

• Adults only; two adults per household maximum; each adult owns a private diary.
• Nothing is shared without an explicit sharing setting; shared plans are read-only; a shared day summary is only the eight daily totals.
• Plans are suggestions, never prescriptions; confirmation creates a diary meal with source planned through the diary service and never auto-converts.
• No medical thresholds. Alerts are (a) reminders for planned meals and water and (b) notices about saving or photo-estimate problems, delivered through the mock NotificationProvider only.
• Every sensitive mutation is audited through AuditService.
• No real vendors, credentials, or cloud deploys.

Task 1: M2 Planning — apps/api/src/planning

Files: packages/contracts/src/planning.ts (+ test), migration 20260920100211_m2_plan_items, planning.dto.ts, planning.repository.ts, prisma-planning.repository.ts, planning.service.ts, planning.controller.ts, planning.module.ts, planning.service.test.ts, planning.controller.test.ts, planning.repository.test.ts; DiaryService.createPlannedMeal.

• PlanItem rows carry plan_… public IDs, local date, slot, title, optional note, optional eight-metric estimate, optional sourceMealId, confirmedMealEntryId (FK, set null on meal deletion), and a version. Check constraints mirror the diary tables.
• Mutations (POST /planning/items, PATCH /planning/items/:id, DELETE /planning/items/:id, POST /planning/items/:id/move) use the diary’s operation envelope: idempotency key replay, baseVersion optimistic concurrency, 409 with details.reason on stale or deleted items, all recorded in client_operations with new operation types.
• POST /planning/items/:id/confirm creates the diary meal through DiaryService.createPlannedMeal (source planned, estimate confirmed, recorded as confirm_plan_item), then links the plan item to that meal exactly once. Replays with the same idempotency key return the same meal; a different operation on an already-confirmed item is a 409.
• GET /planning/week?start= returns seven dates, the adult’s items, and, only when both adults have sharePlans on, the other adult’s items flagged readOnly: true with authorAdultId.
• Audit actions: plan.create, plan.update, plan.move, plan.delete, plan.confirm.

Task 1b: Generated weekly meal plans, preferences, shopping list, Sunday job

Files: packages/contracts/src/meal-planning.ts (+ test), packages/provider-contracts MealPlanProvider + DeterministicMealPlanProvider + synthetic recipe library (+ tests), migration 20260920135330_m2_generated_meal_plans, planning-preferences.repository.ts, prisma-planning-preferences.repository.ts, shopping-list.ts, plan-generation.scheduler.ts, extended planning.dto.ts / planning.repository.ts / prisma-planning.repository.ts / planning.service.ts / planning.controller.ts / planning.module.ts, worker wiring, tests (planning.service.test.ts, planning.controller.test.ts, meal-plan.repository.test.ts, shopping-list.test.ts, plan-generation.scheduler.test.ts).

• Preferences per adult (GET/PATCH /planning/preferences): 14 EU allergens (hard), free-text dislikes (soft), focus (balanced, lighter, more_fuel, higher_protein, more_plants; no numeric goals), dietary pattern, household servings, unit system, country + city/postal code only, time zone, autoGenerate.
• Generation (POST /planning/weeks/:monday/generate {dates?, replaceEdits?}): seven days times four slots through the seam; each item carries description, per-serving nutrition, ingredients with store sections and allergens, servings, and origin: generated. Generated items are replaced on regeneration; manual items are kept unless replaceEdits; a week with edits answers 409 week_edited without it. Confirmed items are never replaced.
• Week view (GET /planning/week?start=) snaps to the Monday-to-Sunday week and adds a week summary (source, edited, focus, generatedAt).
• Shopping list (GET /planning/weeks/:monday/shopping-list, PATCH /planning/shopping-items/:id {state, version}): rebuilt after every generation and manual change, one line per ingredient and unit, ordered by first day needed, tick state preserved by ingredient key (reset when the quantity grew), optimistic versions.
• Sunday job: PlanGenerationScheduler.runDue in the worker every minute; on Sunday from PLAN_AUTO_GENERATE_HOUR (default 7) local time generates next week for adults who have not opted out, skipping weeks that already exist; audited as system.
• Audit actions: plan.generate, plan.preferences_update.

Task 2: Household — apps/api/src/household

Files: packages/contracts/src/household.ts (+ test), migration 20260920101655_m3_household_invitations_sharing, household.dto.ts, household.repository.ts, prisma-household.repository.ts (also implements PlanSharingReader), household.service.ts, household.controller.ts, household.module.ts, three tests; mock identity token local.synthetic-token-b.

• HouseholdInvitation (12-character code from an unambiguous alphabet, single use, 7-day expiry, status pending/accepted/declined/revoked/expired) and HouseholdSharingSetting (sharePlans, shareDaySummary, both default off).
• Endpoints: GET /household, POST /household, POST /household/invitations, POST /household/invitations/:code/accept|decline, DELETE /household/invitations/:id, PATCH /household/sharing, DELETE /household/membership, GET /household/shared-summary?date=.
• Accepting moves the second adult into the inviter’s household, deletes their empty solo household, revokes other open invitations, and never copies or exposes diary data. Leaving moves the adult into a fresh solo household and clears their sharing settings.
• Audit actions: household.create, household.invitation_create, household.invitation_accept, household.invitation_decline, household.invitation_revoke, household.sharing_update, household.leave.

Task 3: Subscription and allowance — apps/api/src/subscription

Files: packages/provider-contracts BillingProvider + DeterministicBillingProvider, packages/contracts/src/subscription.ts, migration 20260920102915_m3_subscription_alerts_deletion_receipts (shared with Tasks 5 and 6), environment SUBSCRIPTION_TRIAL_DAYS, SUBSCRIPTION_MONTHLY_ANALYSIS_ALLOWANCE, SUBSCRIPTION_MONTHLY_PRICE_DISPLAY, subscription.* module files and three tests; photo service allowance guard; explicit error code support in the shared error envelope.

• 14-day trial starts lazily on first use (or explicitly via POST /subscription/trial/start); POST /subscription/restore activates a 30-day mock period; POST /subscription/cancel keeps access until the period ends. A lapsed active period rolls forward one month without charging.
• GET /subscription reports status (trial, active, cancelled, expired), access end, renewal, plan (display price from configuration), manage-URL placeholder, and the month’s allowance/usage counted from meal_analysis_jobs.
• POST /photo/uploads asks the guard before authorizing a new upload; when the allowance is exhausted or access ended it answers 403 with code: analysis_allowance_exhausted. Manual entry is never gated.
• Audit actions: subscription.trial_start, subscription.restore, subscription.cancel.

Task 4: Export and verified deletion — apps/api/src/adult-data

Files: packages/contracts/src/adult-data.ts, adult-data.* module files and three tests, docs/runbooks/data-export-and-deletion.md.

• GET /adult-profile/export returns platepilot.adult-export.v1 JSON: profile, privacy, household facts (never the other adult), subscription, alert preferences, diary, plan items, photo-analysis metadata. No photo bytes, object keys, or tokens.
• DELETE /adult-profile requires X-Confirm-Deletion: <adultProfileId>, removes retained diary photos from the retention bucket first (503 and no deletion if storage is unavailable), then deletes the adult in one transaction (cascades), drops an empty household, writes a deletion_receipts row holding a subject hash, and answers 202 with the receipt.
• Audit actions: adult_profile.export, adult_profile.delete.

Task 5: Alerts — apps/api/src/alerts

Files: packages/contracts/src/alerts.ts, alerts.* module files and three tests.

• GET /alerts?date=&notices= derives meal reminders from the adult’s unconfirmed plan items (fixed suggested times per slot), adds the fixed water schedule only when waterReminders is on, passes through client problem notices with calm copy, sends each through the mock NotificationProvider, and returns receipts. Nothing is stored.
• GET/PATCH /alerts/preferences manage mealReminders (default on) and waterReminders (default off). Audit action: alerts.preferences_update.

Task 6: Cross-cutting

• OpenAPI operation IDs name the SDK functions the mobile agent will call (see the table in the README delivery status). pnpm --filter @platepilot/api-client generate regenerates packages/api-client/openapi/platepilot.openapi.json and src/generated/**.
• Docs: this plan, docs/plans/README.md, docs/architecture.md, docs/threat-model.md, docs/runbooks/data-export-and-deletion.md, README delivery status and mock-provider notes, ADR 0008 (household sharing model), ADR 0009 (mock billing and allowance), ADR 0010 (generated weekly meal plans).

Definition of Done

• Typecheck, lint, and Prettier clean for apps/api, packages/contracts, packages/provider-contracts.
• API unit suite (Docker, Node 22) passes including new controller and service tests.
• Integration tests for every new repository pass against local PostgreSQL.
• Live smoke through the running containers: two adults invite/accept/share, plan week and confirmation, preferences and week generation, shopping list, Sunday scheduler run by the worker, subscription restore/cancel, export and deletion, alerts with receipts.
• Generated API client regenerated and its tests pass; root pnpm check passes in Docker.
• Mobile screens consume the SDK (mobile agent).
• Device/simulator validation and Maestro flows for the new screens (mobile agent).

Follow-ups

• Real provider adapters (identity, billing, notifications) remain out of scope by ADR 0003/0005.
• Production deletion: stronger re-verification, cooling-off policy, vendor evidence, backup restore suppression (see the runbook).
• Push delivery: alerts are computed on request and sent through the mock; a scheduler that pushes at localTime needs a real notification adapter and the adult’s time zone.
• Household safety research (TM-04) before any sharing default changes.