platepilot

Development

Toolchain

PlatePilot requires Node.js 22.x and pnpm 10.34.5. From the repository root:

corepack pnpm --version
corepack pnpm install --frozen-lockfile

The workspace uses pnpm and Turbo. Invoke pnpm as corepack pnpm because a bare pnpm shim is not guaranteed. corepack enable is optional for environments where shim installation works. Do not use npm or Yarn to install dependencies and do not regenerate the lockfile with another pnpm version.

Local environment

cp .env.example .env
cp apps/api/.env.example apps/api/.env
docker compose up -d --wait
corepack pnpm --filter @platepilot/api exec prisma migrate deploy
corepack pnpm prisma:generate

The example values are synthetic and local-only. PostgreSQL and LocalStack S3/SQS bind to loopback. Do not make these ports public. docker compose up -d --wait waits for both service health checks; apply migrations only after it succeeds.

Run applications in separate terminals:

corepack pnpm --filter @platepilot/api dev
corepack pnpm --filter @platepilot/mobile start
corepack pnpm --filter @platepilot/admin dev

The admin application is optional and remains a support shell with no customer-data access.

Validation

Run the complete workspace gate:

corepack pnpm check

It checks formatting, linting, types, tests, and builds. Run focused checks when their boundary changes:

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

• PostgreSQL repository tests use the dedicated platepilot_integration_test schema and apply pending Prisma migrations before running:

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

  The command derives that schema only from the default loopback platepilot database. For any other server or database, set INTEGRATION_DATABASE_URL to a URL whose database or schema is explicitly test-only. Unsafe targets fail before migrations or cleanup run.

• Keep unit tests deterministic and colocated according to the owning package’s convention.
• Exercise shared schemas at untrusted boundaries and provider adapters with fakes.
• Add failure, retry, authorization, and redaction cases when those features are introduced.
• Do not lower validation or coverage expectations to make a change pass.

Storybook is deferred until its Expo SDK 57 integration is validation-stable. NutritionSummaryCard.example.tsx is the compile-checked component example and does not change the Expo runtime.

Package boundaries

• Put provider- and persistence-independent data contracts in packages/contracts.
• Put external-service ports and deterministic mocks in packages/provider-contracts.
• Keep Prisma details inside the API persistence boundary.
• Keep mobile and admin presentation concerns out of domain packages.
• Treat OpenAPI and shared schemas as compatibility surfaces.
• Record durable boundary changes in an ADR.

Data and content safety

Do not add customer fixtures, access tokens, uploaded meal photos, personal email addresses, medical claims, or minor profiles. Use obviously synthetic adult identities and records. Avoid “good/bad food,” diagnosis, prescription, or guaranteed-outcome language.

.env.example enables deterministic provider mocks. Mocks do not make real personal data acceptable and are not a production fallback.

Infrastructure constraint

CDK is synthesis-only:

corepack pnpm cdk:synth

Do not run deployment commands from this repository. The synthesized design contains non-production placeholders. Before a future deployment, reviewed API/worker images, managed runtime database configuration, certificates, an approved email identity, optional social-provider secrets, security controls, and the pending operational runbooks must all be completed.

Change handoff

Before requesting review:

1. Keep the change focused and use conventional commit wording.
2. Run corepack pnpm check plus relevant focused commands.
3. Summarize tests and any unvalidated behavior.
4. Update README, UX status, threat model, runbooks, or ADRs when their assumptions change.
5. Confirm generated output, secrets, local volumes, and personal data are not included.