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 Cloud Run API service, worker job, five-minute
Cloud Scheduler trigger, Google Secret Manager bindings, Artifact Registry image,
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.
make pwa-e2e starts an isolated local API on port 8010, an isolated PWA on port
4175, and Chromium. It uses the synthetic development identity in .env.e2e, not
Google OAuth, so it can exercise the real database, R2 resolver path, CORS, and browser
rendering without manual login or browser clicks. 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.
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