Codex Courier

A mobile-first peer-to-peer courier MVP for moving one permitted small item from one person to another inside one configured local service zone.

One item. One pickup. One destination.

The controlling product and technical source of truth is the Peer-to-Peer Small-Item Courier MVP Specification v1.0 (11 August 2026). Product rules must not be inferred from this README when the specification is more precise.

Workspace

• apps/web — customer, courier, and recipient-link PWA
• apps/admin — operations and support interface
• packages/domain — delivery states, validation, money, errors, permissions, and provider contracts
• packages/ui — shared accessible UI primitives
• packages/supabase — typed browser client and generated database types
• supabase/migrations — ordered canonical database migrations
• supabase/functions — trusted Edge Functions (introduced by workflow phase)
• supabase/tests/database — pgTAP database and authorization tests
• docs — architecture decisions, implementation plan, security, and progress

Prerequisites

• Node.js 20.19+ (Node 24 is used in CI)
• pnpm 11
• Docker Desktop or another Docker-compatible runtime for local Supabase

Local setup

Copy-Item .env.example .env.local
pnpm install
pnpm supabase:start
pnpm db:reset
pnpm db:types
pnpm dev

The web PWA runs on http://127.0.0.1:5173, the admin app on http://127.0.0.1:5174, Supabase Studio on http://127.0.0.1:54323, and captured local email on http://127.0.0.1:54324.

pnpm local:start starts Supabase and both Vite apps in one command after the first installation.

Phase 1 adds email/password authentication, customer profiles, courier applications, private verification documents, MFA-gated staff review, and versioned service zones. The local seed creates only development fixtures:

• admin email: admin.local@example.test
• local-only password: Local-only-password-1!
• one clearly labelled non-production Brisbane South rectangle

Enroll a local authenticator from the admin app on first sign-in. These fixtures are not production bootstrap instructions and must never be copied to another environment.

Serve the authorized document-link function while testing staff document review:

pnpm exec supabase functions serve admin-document-url

Phase 2 adds the customer address/item/contact flow, immutable 10-minute quotes, one-time delivery creation, and Stripe test checkout. Copy server-only test values to an ignored supabase/.env.local, then serve the trusted functions:

pnpm exec supabase functions serve --env-file supabase/.env.local

Use MAPS_PROVIDER=deterministic locally. It makes no provider calls and produces development-only route facts inside the seeded zone. For Stripe checkout, configure only sk_test_... and whsec_... values in the server environment, add the matching pk_test_... value as VITE_STRIPE_PUBLISHABLE_KEY, and forward Stripe CLI test webhooks to http://127.0.0.1:54321/functions/v1/stripe-webhook. Never place a Stripe secret or webhook secret in a VITE_ variable.

Production staff bootstrap is an audited database administration procedure described in Security; no production administrator is hard-coded in migrations or frontend code.

Validation

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm db:lint
pnpm db:test
pnpm db:types

Database commands require the local Supabase stack to be running. CI regenerates the database types and rejects schema/type drift.

Migrations and rollback

Migrations are forward-only, timestamped SQL in supabase/migrations. Develop locally, run pnpm db:reset, run pgTAP tests, and regenerate types before review. Do not run db reset --linked against staging or production. A production rollback must be a reviewed compensating migration; destructive rollback is not an operational shortcut.

Cloudflare

Each frontend has a wrangler.jsonc Pages configuration. Build from its workspace directory and publish only after the corresponding Pages project, DNS, WAF, rate limits, Turnstile policy, and environment bindings have been reviewed. No Cloudflare resource is created by this repository.

Stripe

Use Stripe test mode only during implementation. The platform uses a customer charge followed by a later connected-account transfer, but the exact Connect account configuration and merchant-of-record position remain an explicit legal/commercial decision.

Phase 2 creates the customer PaymentIntent only. Courier transfers, payouts, refunds, live Connect configuration, and reconciliation remain later work.

Phase 3 adds canonical courier presence, configurable PostGIS matching waves, private expiring offers, atomic first-winner assignment, an in-app notification outbox, and the courier dispatch screen. Exact addresses and contacts remain hidden until assignment. Configure a local active dispatch_rules row and an ignored DISPATCH_JOB_SECRET before exercising later waves; the seeded radii and eligibility fixtures used by tests are not production policy.

Security

Only the Supabase URL and publishable browser key may enter Vite bundles. See Security for environment separation, secret rotation, logging restrictions, and incident handling.