platepilot

PlatePilot M1 Adult Logging Implementation Plan

For LLM: REQUIRED SUB-SKILL: Use @.github/prompts/execute-plan.prompt.md to implement this plan task-by-task.

Goal: Deliver a production-quality adult-only logging vertical slice: onboarding, manual food and water entries, asynchronous mock photo analysis, daily totals, history, and offline-safe synchronization.

Architecture: Keep domain behavior behind small interfaces in shared contracts and API application modules. The mobile app owns drafts and an offline command queue; the API owns identity, authorization, persistence, quotas, and accepted records. External systems remain replaceable adapters, with deterministic M0 mocks used until approved credentials exist.

Tech Stack: React Native/Expo Router, React Native Paper, TanStack Query, Zustand, React Hook Form, Zod, NestJS, REST/OpenAPI, Prisma/PostgreSQL, LocalStack S3/SQS, Vitest, React Native Testing Library, Maestro.

---

Scope

M1 includes:

• Adult-only onboarding and 18+ affirmation.
• One private adult profile in a one-member household.
• Manual meal and water logging.
• Camera/library intake with a local mock upload and asynchronous analysis job.
• Provisional, editable AI estimates.
• Daily nutrition totals and history.
• Offline command queue with visible pending, failed, and conflict states.
• Privacy-safe audit events for sensitive mutations.

M1 excludes:

• Real Cognito, LogMeal, Spoonacular, RevenueCat, push, or health-provider adapters.
• Two-adult invitations and sharing.
• Weekly planning, grocery lists, subscriptions, and production deployment.
• Real customer data or personal meal-photo fixtures.

Task 1: Establish M1 Domain Contracts

Files:

• Create: packages/contracts/src/adult-profile.ts
• Create: packages/contracts/src/diary.ts
• Create: packages/contracts/src/sync.ts
• Create: packages/contracts/src/adult-profile.test.ts
• Create: packages/contracts/src/diary.test.ts
• Create: packages/contracts/src/sync.test.ts
• Modify: packages/contracts/src/index.ts

Step 1: Write failing tests

Cover:

• Adult affirmation requires ageVerified: true and a verification timestamp.
• Birth month is 1–12 and birth year cannot imply an age below 18.
• Meal sources are manual, photo_estimate, or planned.
• Estimate states are provisional, confirmed, or needs_review.
• Meal entries use breakfast/lunch/dinner/snacks and non-negative nutrition.
• Water entries require a positive milliliter amount.
• Client operations have an idempotency key, device ID, base version, and local timestamp.
• Sync conflicts are explicit data, never a silent last-write-wins result.

Step 2: Verify RED

corepack pnpm --filter @platepilot/contracts test

Expected: tests fail because the M1 schemas do not exist.

Step 3: Implement minimal contracts

Use strict Zod objects and inferred TypeScript types. Keep Prisma, HTTP, Expo, and provider types out of this package.

Step 4: Verify GREEN

corepack pnpm --filter @platepilot/contracts test
corepack pnpm --filter @platepilot/contracts typecheck

Expected: all contract tests pass.

Step 5: Commit checkpoint

Only if commit authorization is provided:

git add packages/contracts
git commit -m "feat(contracts): define adult diary and sync models"

Task 2: Complete the Adult-Private Persistence Model

Files:

• Modify: apps/api/prisma/schema.prisma
• Create: apps/api/prisma/migrations/<timestamp>_m1_adult_diary/migration.sql
• Create: apps/api/src/adult-profile/adult-profile.repository.ts
• Create: apps/api/src/adult-profile/prisma-adult-profile.repository.ts
• Create: apps/api/src/adult-profile/adult-profile.repository.test.ts
• Create: apps/api/src/diary/diary.repository.ts
• Create: apps/api/src/diary/prisma-diary.repository.ts
• Create: apps/api/src/diary/diary.repository.test.ts

Step 1: Write failing repository tests

Test through repository interfaces:

• A Cognito-like subject maps to exactly one adult profile.
• An adult can read and mutate only their own entries.
• Reusing an idempotency key returns the original result.
• Optimistic version mismatch returns an explicit conflict.
• Deleting an adult profile cascades private diary data.
• Household membership does not grant access to another adult’s private diary.

Step 2: Verify RED

Start PostgreSQL and run the dedicated integration target:

docker compose up -d postgres
corepack pnpm --filter @platepilot/api test:integration

Expected: tests fail because repositories and diary tables are absent.

Step 3: Implement the minimal schema and adapters

Add adult-scoped meal, food-item, water, and client-operation tables. Use internal UUID primary keys and prefixed public IDs. Add unique and foreign-key constraints for subject, public ID, idempotency key, and ownership.

Step 4: Generate and inspect the migration

corepack pnpm --filter @platepilot/api exec prisma migrate dev --name m1_adult_diary
corepack pnpm prisma:generate

Verify that the migration contains no child/dependent fields and no public photo URLs.

Step 5: Verify GREEN

corepack pnpm --filter @platepilot/api test:integration
corepack pnpm prisma:validate

Step 6: Commit checkpoint

Only with authorization:

git add apps/api/prisma apps/api/src/adult-profile apps/api/src/diary
git commit -m "feat(api): persist private adult diary records"

Task 3: Add Mock Identity and Adult Onboarding

Files:

• Create: apps/api/src/auth/current-adult.ts
• Create: apps/api/src/auth/mock-auth.guard.ts
• Create: apps/api/src/auth/auth.module.ts
• Create: apps/api/src/adult-profile/adult-profile.service.ts
• Create: apps/api/src/adult-profile/adult-profile.controller.ts
• Create: apps/api/src/adult-profile/adult-profile.service.test.ts
• Create: apps/api/src/adult-profile/adult-profile.controller.test.ts
• Modify: apps/api/src/app.module.ts

Step 1: Write failing tests

Cover:

• Missing or invalid mock tokens return the shared 401 envelope.
• The accepted synthetic token resolves one verified adult subject.
• Onboarding rejects an unverified 18+ affirmation.
• Month/year is optional and validated when provided.
• Repeating onboarding is idempotent.
• Responses never expose internal database IDs.

Step 2: Verify RED

corepack pnpm --filter @platepilot/api test -- src/auth src/adult-profile

Step 3: Implement minimal behavior

Use the existing IdentityProvider seam and mock adapter. Keep authorization in an API-owned module rather than controllers.

Step 4: Verify GREEN

corepack pnpm --filter @platepilot/api test
corepack pnpm --filter @platepilot/api typecheck

Step 5: Commit checkpoint

Only with authorization:

git add apps/api/src/auth apps/api/src/adult-profile apps/api/src/app.module.ts
git commit -m "feat(api): add adult onboarding boundary"

Task 4: Implement Manual Meal and Water Logging

Files:

• Create: apps/api/src/diary/diary.service.ts
• Create: apps/api/src/diary/diary.controller.ts
• Create: apps/api/src/diary/diary.module.ts
• Create: apps/api/src/diary/diary.service.test.ts
• Create: apps/api/src/diary/diary.controller.test.ts
• Modify: apps/api/src/app.module.ts

Step 1: Write failing tests

Cover:

• Create, edit, and delete a manual meal.
• Add, edit, and delete water.
• Reject negative nutrients and zero/negative water.
• Keep the four fixed meal slots.
• Preserve the user-selected timezone and local diary date.
• Return daily totals for all eight dashboard metrics.
• Reject access across adult profiles.
• Return the original result for a repeated idempotency key.
• Return a 409 conflict for stale versions.

Step 2: Verify RED

corepack pnpm --filter @platepilot/api test -- src/diary

Step 3: Implement minimal behavior

Controllers validate transport input and delegate. The diary service owns authorization, idempotency, optimistic concurrency, totals, and repository orchestration.

Step 4: Verify GREEN

corepack pnpm --filter @platepilot/api test
corepack pnpm --filter @platepilot/api test:integration

Step 5: Commit checkpoint

Only with authorization:

git add apps/api/src/diary packages/contracts
git commit -m "feat(api): add manual meal and water logging"

Task 5: Implement Mock Photo-Analysis Workflow

Files:

• Create: apps/api/src/photo/photo-storage.ts
• Create: apps/api/src/photo/localstack-photo-storage.ts
• Create: apps/api/src/photo/photo.controller.ts
• Create: apps/api/src/photo/photo.service.ts
• Create: apps/api/src/photo/photo.module.ts
• Create: apps/api/src/photo/photo.service.test.ts
• Create: apps/api/src/photo/photo.controller.test.ts
• Modify: apps/api/src/meal-analysis/meal-analysis.service.ts
• Modify: apps/api/src/app.module.ts

Step 1: Write failing tests

Cover:

• Only supported image type/size/dimension metadata is accepted.
• The service issues an adult-scoped, short-lived upload request.
• Completion creates one idempotent queued analysis job.
• The external provider request contains no adult, household, email, or auth identifier.
• Failed/pending/succeeded states remain distinguishable.
• A succeeded mock result creates a provisional diary entry.
• Unknown nutrition is not fabricated.
• Default originals are deleted after processing; the one-day bucket lifecycle is only a fallback.
• Manual entry remains available after failure.

Step 2: Verify RED

corepack pnpm --filter @platepilot/api test -- src/photo src/meal-analysis

Step 3: Implement the deep module

Expose a small PhotoMealService interface. Keep storage, queue, provider, persistence, quota, and retention details behind it. Use LocalStack adapters and deterministic provider mocks only.

Step 4: Verify GREEN

docker compose up -d
corepack pnpm --filter @platepilot/api test
corepack pnpm --filter @platepilot/api test:integration
docker compose down

Step 5: Commit checkpoint

Only with authorization:

git add apps/api/src/photo apps/api/src/meal-analysis apps/api/prisma packages
git commit -m "feat(api): add asynchronous mock photo logging"

Task 6: Add the Generated Mobile Client and Offline Command Queue

Files:

• Create: packages/api-client/
• Create: apps/mobile/src/data/api-client.ts
• Create: apps/mobile/src/data/offline-store.ts
• Create: apps/mobile/src/data/sync-engine.ts
• Create: apps/mobile/src/data/sync-engine.test.ts
• Modify: pnpm-workspace.yaml
• Modify: apps/mobile/package.json

Step 1: Write failing tests

Cover:

• Manual meal and water commands are persisted before network submission.
• Successful replay removes only the acknowledged operation.
• Transient failure remains pending with retry metadata.
• Validation/auth failures become visible permanent failures.
• Version conflicts remain unresolved until the adult chooses a resolution.
• Replaying the same idempotency key cannot create a duplicate.
• Sign-out clears private cached data.

Step 2: Verify RED

corepack pnpm --filter @platepilot/mobile test -- src/data/sync-engine.test.ts

Step 3: Implement minimal offline infrastructure

Use an encrypted SQLite-backed store on native builds and a test adapter for Vitest. Keep access tokens in secure storage, never in Zustand or general query persistence. Generate the REST client from OpenAPI rather than hand-copying endpoint types.

Step 4: Verify GREEN

corepack pnpm --filter @platepilot/mobile test
corepack pnpm --filter @platepilot/mobile typecheck

Step 5: Commit checkpoint

Only with authorization:

git add packages/api-client apps/mobile/src/data apps/mobile/package.json
git commit -m "feat(mobile): add offline command synchronization"

Task 7: Build Adult Logging Screens

Files:

• Create: apps/mobile/app/onboarding/
• Create: apps/mobile/app/log/
• Create: apps/mobile/app/history/
• Create: apps/mobile/src/components/
• Create: apps/mobile/src/features/diary/
• Create: apps/mobile/src/features/photo/
• Create: apps/mobile/src/features/water/
• Create: apps/mobile/src/**/*.test.tsx
• Modify: apps/mobile/app/index.tsx
• Modify: apps/mobile/app/_layout.tsx

Step 1: Write failing component tests

Cover:

• Adult affirmation and wellness copy.
• Just-in-time camera/library permissions.
• Face-detection block/crop-retake state.
• Photo upload pending, retrying, failed, needs-review, provisional, and confirmed states.
• Full edit of items, portions, meal slot/time, and nutrients.
• Manual meal and water entry.
• Standard/Simple dashboard metrics.
• Offline and synchronization indicators.
• Persisted meal occurrence/portion values and reload round trips.
• Saved meal/water edit and delete, reversible pending water confirmation, and full provisional photo review from Today or History.
• Automatic replay on reconnect, foreground, and retry deadline through one session-scoped coordinator.
• Current-photo crop plus app-owned temporary-media cleanup on replacement, discard, and sign-out.
• Confirmed destructive sign-out copy for permanent authentication failure; no same-adult renewal promise in M1.
• Canonical create/update/delete acknowledgement reconciliation shared by immediate and cold-start replay.
• Atomic edit-and-replace for failed manual meal, water, and photo create operations.
• Backward-compatible SQLCipher ui_json migration with strict fail-closed validation and immutable idempotency equivalence.
• Explicit offline-command schema version 2 with transactional normalization of pre-Task-7 meal occurrence and portion fields before strict validation.
• Disabled edit/delete controls plus adapter guards while a target mutation is blocked.
• Adult-scoped SQLCipher photo-job recovery across navigation, process recreation, foreground, retry, review, cancellation, and sign-out, without storing photo bytes.
• Durable encrypted photo-upload attempts with stable authorization and completion idempotency, restart recovery, and retained registration failures until the analysis job is locally durable.
• Compatibility drainage for outstanding versioned originals/ objects: sanitize into processing/, transactionally repoint the job, and delete the exact legacy source version.
• Immediate save, retry, and keep-mine flows reconcile every FIFO acknowledgement into all loaded diary days before returning.
• Adult-scoped SecureStore persistence for Standard/Simple and metric/US customary preferences.
• Canonical milliliter water storage with centralized metric/fluid-ounce presets, draft conversion, row formatting, and low-drift edit round trips.
• Locale-aware decimal-pad parsing and formatting for meal portions, nutrients, and water, with locale grouping rejected and persisted precision limited to three decimal places.
• Dedicated app-owned photo temp directory with startup/sign-out discovery sweeps.
• Screen-reader names, focus order, dynamic type, non-color status, and large touch targets.
• No action silently succeeds.

Step 2: Verify RED

corepack pnpm --filter @platepilot/mobile test

Step 3: Implement the approved Figma flow

Build from the reviewed design specification and shared tokens. Do not add new product scope while translating designs into code.

Step 4: Verify GREEN

corepack pnpm --filter @platepilot/mobile test
corepack pnpm --filter @platepilot/mobile typecheck
corepack pnpm expo:check

Step 5: Commit checkpoint

Only with authorization:

git add apps/mobile packages/design-tokens
git commit -m "feat(mobile): deliver adult diary experience"

Task 8: Add Privacy-Safe Audit and Operational Signals

Files:

• Create: apps/api/src/audit/audit-event.ts
• Create: apps/api/src/audit/audit.service.ts
• Create: apps/api/src/audit/audit.service.test.ts
• Create: apps/api/src/telemetry/telemetry.module.ts
• Modify: relevant M1 services
• Modify: docs/threat-model.md

Step 1: Write failing tests

Verify:

• Sensitive mutations emit actor, action, resource public ID, request ID, and outcome.
• Events never contain tokens, photo bytes/URLs, food text, nutrition values, birth data, or email.
• Failed mutations are audited without appearing successful.
• Metrics distinguish core API latency from provider-analysis completion.

Step 2: Verify RED

corepack pnpm --filter @platepilot/api test -- src/audit src/telemetry

Step 3: Implement minimal signals

Keep observability behind a small interface with an in-memory test adapter. Do not connect Sentry or AWS telemetry in M1 local mode.

Step 4: Verify GREEN

corepack pnpm --filter @platepilot/api test
corepack pnpm --filter @platepilot/api typecheck

Step 5: Commit checkpoint

Only with authorization:

git add apps/api/src/audit apps/api/src/telemetry docs/threat-model.md
git commit -m "feat(api): add privacy-safe audit signals"

Task 9: Add End-to-End Acceptance Coverage

Files:

• Create: apps/mobile/.maestro/onboarding-and-manual-log.yaml
• Create: apps/mobile/.maestro/photo-analysis-recovery.yaml
• Create: apps/mobile/.maestro/offline-sync-conflict.yaml
• Create: docs/runbooks/m1-local-demo.md
• Modify: root scripts and CI placeholders only as required

Step 1: Define failing acceptance flows

The flows must prove:

1. An adult completes onboarding and manually logs a meal and water.
2. A photo job is queued, completes through the deterministic mock, and remains provisional.
3. A provider failure exposes retry and manual entry.
4. Offline commands synchronize after connectivity returns.
5. A version conflict remains visible until resolved.
6. The dashboard totals match persisted entries.

Step 2: Verify RED

Run the API/mobile stack and execute the focused Maestro flows. Expected: fail before screens and fixtures exist.

Step 3: Implement only missing acceptance wiring

Do not add planning, households, subscriptions, or real providers.

Step 4: Verify GREEN

Run:

corepack pnpm check
corepack pnpm coverage
corepack pnpm compose:config
corepack pnpm prisma:validate
corepack pnpm expo:check
corepack pnpm cdk:synth

Then run the M1 integration and Maestro suites with PostgreSQL and LocalStack healthy.

Step 5: Commit checkpoint

Only with authorization:

git add .
git commit -m "feat: complete M1 adult logging vertical slice"

M1 Definition of Done

• Every M1 behavior was developed through a witnessed RED-GREEN-REFACTOR cycle.
• No real provider credentials, personal data, or cloud deployment exists.
• Manual meal/water and mock photo logging work end-to-end.
• Provisional, pending, failed, offline, synchronized, and conflict states are visibly distinct.
• Adult ownership checks protect every diary query and mutation.
• Default photo deletion and retention fallback are tested.
• OpenAPI and the generated mobile client agree.
• Unit, integration, accessibility, Maestro, build, audit, Compose, Prisma, Expo, and CDK checks pass.
• Documentation distinguishes M1 implementation from later planning, household, subscription, and real-provider milestones.