This repository contains the implementation and normative specifications for a recurring, area-based community carpool application. The current development slice includes a React PWA authentication shell, a Python API, immutable PostgreSQL migrations, and synthetic-only development fixtures.
The first-release deployment direction is:
- One responsive TypeScript PWA/SPA served as static objects from public Cloudflare R2, using hash-based client routes and no Cloudflare Worker.
- Google OAuth through Supabase Auth.
- Supabase Free PostgreSQL for active/current operational data, RLS-protected published-view key grants, and durable PGMQ queues.
- Google Cloud Run for the transactional API, scheduler, solver, and background workers.
- Google Cloud Scheduler for the five-minute worker tick.
- Public R2 for encrypted client-view bundles.
- Private R2 for rolling archives and encrypted database backups.
The hosted Supabase development project is the authoritative migration target because it
provides both required extensions: pgcrypto and PGMQ. Keep its database connection string
only in the current shell; use the Session pooler on port 5432 when the host lacks IPv6.
set -a; . .env.supabase; set +a
export CARPOOL_ENVIRONMENT=development
export CARPOOL_DATABASE_URL='postgresql://...'
make migrate verify-db
make apiIn another shell, configure apps/pwa/.env.local from its .env.example, then run
npm run dev in apps/pwa.
The repository contains an idempotent Cloud Run + Cloudflare R2 release path.
It provisions or updates the public Cloud Run API service, private
request-billed worker service, five-minute Cloud Scheduler trigger, Google
Secret Manager bindings, Artifact Registry image, nightly backup job, and the
R2-hosted hash-routed SPA. Configuration stays in ignored local .env files;
the deployment never places secrets in the container image or repository.
cp .env.deploy.example .env.deploy
# Set the GCP project and the public R2 URL that serves the SPA.
scripts/deploy.sh update --dry-run
scripts/deploy.sh bootstrap
# Later releases:
scripts/deploy.sh updateSee infra/deploy/README.md for the required local values, one-time Supabase OAuth URL settings, update behavior, and scoped commands.
Restore verification is an environment-operator incident-response procedure, not an administrator UI action. The administrator UI reports missing, failed, or stale nightly backups; it does not treat restore-rehearsal age as an application issue.
Run the existing local rehearsal from a trusted operator workstation with Docker and the deployment environment configured:
make rehearse-restoreThe command selects the newest available or verified backup recorded by the
configured source database, downloads its encrypted object from the configured
private R2 bucket, obtains the independent backup key from Google Secret
Manager, and restores into a temporary local Supabase-compatible PostgreSQL
container. It verifies the ciphertext checksum, authenticated decryption,
pg_restore, migration watermark, required extensions, browser-role schema
denial, and current schedule uniqueness. The container and restored database
are discarded on exit. It does not create a new backup and never restores into
the source database.
To rehearse a specific backup rather than the newest usable one:
export CARPOOL_BACKUP_ID='<backup-uuid>'
make rehearse-restore
unset CARPOOL_BACKUP_IDRecommendations:
- Run only from a trusted operator workstation; never expose the backup key or restore command through the browser.
- Verify before real participant data is introduced, after material backup/storage changes, and during incident response when recoverability must be established.
- Confirm that the loaded deployment environment identifies the intended source database and private R2 bucket before starting.
- Preserve the recorded verification result and command output as incident or release evidence; do not retain the temporary restored database.
- Treat a failed verification as an operational incident: preserve existing backups, correct the failure, and repeat the rehearsal before claiming recoverability.
See the deployment and operations runbook for the full procedure and target-safety requirements.
make pwa-e2e starts an isolated local API on port 8010, an isolated PWA on port
4175, and Chromium. It derives two isolated synthetic users from the development identity
in .env.e2e, not Google OAuth, and provisions a separately marked disposable organization
in the development database. This lets the suite exercise the real scheduler, database, R2
resolver path, CORS, multi-user confirmations, and browser rendering without manual login or
browser clicks or consuming queued work from a human integration organization. The
multi-user mutation scenario pauses scheduling while one household changes rider attendance,
driver availability, and vehicle capacity; it then processes only those scoped impacts,
rebuilds and republishes one area plan, and verifies both households, both drivers, and the
coordinator see and complete their own resulting work. Global teardown hard-deletes only
that exact marked organization and its descendants; it never falls back to cleaning the
human integration organization. The checked-in .env.e2e.example defines the only one-time
setup; never point it at a production identity.
make pwa-e2e-live uses the same untouched fixture but forces the test-only API entry point
to select the scoped live-fallback branch. Together the two commands cover both sides of the
publication-coherency boundary without waiting for or altering a real scheduling run.
make schedule-mutation-sim runs a deterministic, database-free integration simulation
modeling a published six-household, three-date plan. It removes riders, applies
date-specific driver unavailability, removes vehicles, reduces capacity, verifies
fail-closed behavior under insufficient capacity, and explores twenty seeded combined
mutation sequences. Every feasible successor must preserve exact rider coverage, capacity,
driver/vehicle interval safety, deterministic allocation, and the immutable predecessor
snapshot. The same target also covers recurring and special-activity precedence,
cross-activity rider conflicts, movement deduplication and wave separation, plus the
two-phase outbound/shared-return response flow. Twenty additional activity seeds exercise
precedence combinations; composed scenarios cover unequal-balance fairness and canonical
equivalence across exact and scalable backtracking. These simulations are also part of the
normal Python test suite.
The worker also reconciles authoritative in-app confirmation actions. The PWA's Action Center
uses the API only: reading or dismissing a notification cannot confirm a ride, and its
Review confirmation control reauthorizes the target before showing the current action.
make local-db-up provides a plain PostgreSQL foundation for development utilities. It does
not replace Supabase's PGMQ extension or browser-role/RLS verification.
Read the specifications in this order when learning the system. When changing one concern, use the responsibility column to identify the authoritative artifact and then propagate its consequences to downstream documents.
| Order | Specification | Responsibility | Principal content |
|---|---|---|---|
| 1 | Persona and Experience Model | Product intent and scope | Personas, terminology, first-release capabilities, area isolation, household fairness policy, scheduling expectations, confirmations, emergency behavior, mobile/PWA experience, and product-level acceptance rules. |
| 2 | Domain Model and ERD | Information model and durable invariants | Entities, relationships, identity, topology, memberships, sessions, demands, plans, assignments, confirmations, execution, credits, notifications, published-view grants, archives, database invariants, and transaction boundaries. |
| 3 | State-Machine Specification | Lifecycle authority | States, guarded commands, revisions, deadlines, confirmation transitions, handoffs, trip execution, emergency incidents, season lifecycle, invalid transitions, and required atomic side effects. |
| 4 | Scheduling and Rebalancing Algorithm | Allocation mathematics and repair policy | Demand derivation, transport-wave compatibility, hard constraints, vehicle minimization, rider placement, parent-driver priority, fairness selection, stability, local repair, emergency solving, and deterministic outputs. |
| 5 | Permissions and Field-Visibility Matrix | Authorization and data minimization | Roles, relationship scope, command authority, row and field visibility, temporary driver access, dual-role behavior, offline data, encrypted published-view grants, denial codes, and authorization tests. |
| 6 | Event and Notification Catalog | Event and human-action delivery policy | Domain events, outbox behavior, logical actions, audiences, in-app alerts, first-release Web Push, retry profiles, escalation, grouping, supersession, provider failure, privacy, and delivery audit. |
| 7 | Service and Data Architecture Plan | Runtime, persistence, and deployment architecture | Modular-monolith boundaries, Supabase data and queues, Cloud Run services and workers, Cloud Scheduler, PWA sync, public encrypted R2 views, private archives/backups, rolling hot/cold storage, concurrency, recovery, and observability. |
| 8 | Physical Data and Published-View Contract | Executable persistence contract | PostgreSQL namespaces, tables, constraints, indexes, RLS, queues, outbox, timers, idempotency, migration rules, seed data, archive catalogs, and the encrypted R2 bundle and Supabase grant contracts excluded from OpenAPI. |
| 9 | API Contract Plan | Client/service contract shape | Cloud Run HTTP conventions, Google/Supabase identity, request context, idempotency, revisions, errors, endpoint families, synchronization, resolver-mediated R2 grants, live publication fallback, security, and contract tests. |
| 10 | OpenAPI 3.1 Contract | Machine-readable Cloud Run contract | Supabase bearer authentication, common headers, all public endpoint operations, scope-qualified paths, command and projection schemas, idempotency, revisions, fingerprints, synchronization, stable errors, asynchronous operations, manifests, confirmations, and export responses. The separate Supabase RLS grant read is deliberately excluded. |
| 11 | Security, Privacy, and Retention Specification | Data-protection baseline | Threat model, trust boundaries, data classification, minimization, OAuth and enrollment security, RLS, browser and public-ciphertext controls, credentials, retention, deletion, recovery, incident response, and security acceptance. |
| 12 | PWA Client Architecture Specification | Browser-client architecture | React and TypeScript modules, static R2 and hash routing, Supabase Auth, resolver-mediated encrypted-view loading, online coherence, Web Push, updates, security, accessibility, and client tests. |
| 13 | UI, UX, Responsive Design, and Accessibility Specification | Product presentation and interaction | Mobile-first information architecture, additive multi-role workspaces, role-specific screens and workflows, responsive behavior, coordinator operations board, driver safety, action/alarm hierarchy, forms, system states, notifications, WCAG 2.2 AA, content, design-system guidance, and usability acceptance. |
| 14 | Split-Outbound/Shared-Return Fixture | Small normative domain example | The canonical example proving that group-specific outbound arrival waves can consolidate into one same-end-time return wave without duplicating riders, capacity, confirmations, or credits. |
| 15 | Algorithm Scenarios and Fairness Review | Broader normative scenario suite | Representative schedules, capacity failures, household placement, parent-driver behavior, binning, fairness outcomes, mid-season normalization, repairs, emergencies, and edge-case review. |
| 16 | Implementation and Acceptance Plan | Build sequence and release gates | First-release scale and service objectives, vertical slices, dependency order, test architecture, normative traceability, environments, migration and rollout gates, pilot readiness, rollback, and implementation completion criteria. |
The implemented presentation topology is tracked in the UI, Information Architecture, and UX Redesign Plan. Its reusable visual and interaction rules are recorded in the UI Design Tokens and Component-State Matrix. Automated gates and the deployed release candidate are recorded in the UI Redesign Release Evidence. The former participant-based UI Pilot Validation Protocol and results template are retained as optional research references, not release gates. Pilot UI feedback is handled continuously as concrete issues and regression tests. The pilot intentionally ships without a product-analytics provider under the Pilot Product Analytics Decision. Remaining first-release UI and command work is tracked in the Missing Workflow Backlog.
Each artifact owns a different question:
Product intent
→ domain facts and invariants
→ lifecycle transitions
→ scheduling/allocation
→ authorization
→ events and notifications
→ service/deployment architecture
→ physical persistence and protected-view contracts
→ API contract
→ machine-readable OpenAPI
→ security, privacy, and retention controls
→ client architecture
→ UI/UX and accessibility
→ normative fixtures and scenarios
→ implementation slices and executable tests
- The Persona and Experience Model is authoritative for product intent, but it does not define database tables, HTTP endpoints, or solver equations.
- The Domain Model owns durable structure and invariants, while the State-Machine Specification owns allowed lifecycle changes.
- The Scheduling Algorithm may choose only among lifecycle- and domain-valid outcomes; it cannot override hard constraints.
- The Permissions Matrix applies to every UI, API, worker, export, cache, published bundle, and archive access path.
- The Event Catalog determines who is informed and when, but delivery never creates confirmation.
- The Architecture Plan selects deployment technology without weakening product, domain, lifecycle, scheduling, or authorization rules.
- The Physical Data Contract maps authoritative concepts to PostgreSQL, queues, RLS, and protected-view schemas without changing their meaning.
- The API Contract exposes those rules but cannot create an alternate transition or authorization path.
- The OpenAPI artifact makes the Cloud Run contract executable for clients and tests but cannot add an endpoint, role, field, or state transition absent from the authoritative narrative specifications.
- The Security, Privacy, and Retention Specification may narrow access or lifetime but cannot silently remove an operational safety or audit obligation.
- The PWA Client Architecture consumes the API and published-view contracts but cannot treat cached, optimistic, push-delivered, or offline state as canonical.
- The UI/UX Specification owns presentation and interaction but cannot flatten additive roles into an unscoped merged view, invent a transition, or conceal whether state is stale, pending, or unconfirmed.
- Normative fixtures and scenarios demonstrate required results. If a fixture appears inconsistent with its owning specification, resolve the owning specification first and then update the fixture.
- The Implementation and Acceptance Plan determines build order and evidence gates; completion requires the owning normative specifications and not merely a passing user-interface demonstration.
The pre-implementation P0 specifications and the deployment/operations baseline are complete. Organization-specific approvals and recovery contacts remain operator inputs before real participant data is used.
| Planned artifact | Status | Responsibility and expected content | Primary inputs |
|---|---|---|---|
spec/carpool_deployment_and_operations_runbook.md |
Implemented for development/pilot rehearsal | Exact Supabase, Google OAuth, Cloud Run, Cloud Scheduler and R2 configuration; secrets and quotas; Web Push/VAPID operations; observability; encrypted backup and isolated restore procedures; alarms; incidents; and repeatable deployment. | Architecture, physical data, security/privacy, implementation acceptance |
spec/carpool_preproduction_readiness_evidence.md |
Current synthetic rehearsal evidence | Automated test, accessibility, load, deployment, backup/restore, outage, and approved-deferral evidence for the current development release. | Implementation acceptance, deployment runbook |
These capabilities are not required for the first release. Their named documents are roadmap placeholders, not specification work items, and should not be created until the capability enters an approved release scope:
| Deferred artifact | Scope |
|---|---|
spec/carpool_email_delivery_integration_spec.md |
Transactional email provider, templates, consent, retries, delivery callbacks, and fallback policy. |
spec/carpool_whatsapp_delivery_integration_spec.md |
WhatsApp provider, approved templates, consent, localization, retries, callbacks, and jurisdictional constraints. |
spec/carpool_calendar_integration_spec.md |
Calendar feeds or provider integration, stable event identities, privacy, update/cancellation behavior, and revocation. |
spec/carpool_native_mobile_client_spec.md |
Native iOS/Android packaging only if later requirements justify moving beyond the PWA. |
| Item | Required before production-like rollout |
|---|---|
| Season closure and archive lifecycle | Verified archive, read-only historical access, retention review, and transactional archive deletion/tombstone. |
| Backup and restore operations | Execute and record an isolated restore rehearsal at least quarterly and before use with real participant data. |
| Pilot hardening | Target-scale/load, accessibility, dependency, migration, failure, and recovery gates from Slice 8. |
README.md
spec/
carpool_algorithm_scenarios_and_fairness_review.md
carpool_api_contract_plan.md
carpool_domain_model_and_erd.md
carpool_event_and_notification_catalog.md
carpool_implementation_and_acceptance_plan.md
carpool_openapi.yaml
carpool_permissions_and_field_visibility_matrix.md
carpool_persona_experience_model_spec.md
carpool_physical_data_contract.md
carpool_pwa_client_architecture_spec.md
carpool_scheduling_and_rebalancing_algorithm_spec.md
carpool_security_privacy_and_retention_spec.md
carpool_service_and_data_architecture_plan.md
carpool_split_outbound_shared_return_fixture.md
carpool_state_machine_spec.md
carpool_ui_ux_and_accessibility_spec.md
schema/
carpool_published_view_bundle.schema.json
carpool_published_view_grant.schema.json