Libraries

Canonical Library Reference

These are the standard libraries for all Foundation projects. Do not substitute without explicit justification and team approval.

Python

Library	Purpose
`fastapi`	HTTP API framework
`uvicorn[standard]`	ASGI server
`pydantic`	Data validation and serialization
`pydantic-settings`	Settings management from environment variables
`sqlalchemy`	Postgres query layer / ORM (Neon)
`asyncpg`	Async Postgres driver (Neon)
`pyjwt[crypto]`	Validate Better Auth JWTs (Neon RLS / auth)
`polars`	DataFrame / data transformation
`fire`	CLI interface generation
`google-cloud-bigquery`	Google BigQuery client (analytics sync)
`google-genai`	Google Gen AI SDK for Gemini — reasoning, embeddings, and voice, configured for Vertex (`vertexai=True`, project + location); never `ai.google.dev`. Used by `backend/worker` + embedding jobs (see AI Tier)
`restate-sdk`	Durable-execution client (Restate, 1.0) — ASGI/Hypercorn, some glue vs FastAPI-native
`cerbos`	Authorization PDP client — checks + Query Plan API (SQL filters that pair with Neon RLS)

Python Dev / Test

Library	Purpose
`ruff`	Linting + formatting
`pytest`	Test runner
`pytest-cov`	Coverage reporting
`httpx`	Async HTTP client (FastAPI test client)

JavaScript / TypeScript

Library	Purpose
`vite`	Build tool for the application UIs
`@tanstack/react-router`	Application routing
`@tanstack/react-query`	Application data fetching / server state
`openapi-typescript` + `openapi-fetch`	Typed API client generated from the FastAPI OpenAPI schema (the frontend ↔ backend contract)
`better-auth`	Authentication (hosted by the applications-UI server)
`drizzle-orm` + `pg`	Typed data access — direct Postgres → Neon, with RLS
`drizzle-kit`	Schema migrations + DDL for Neon — schema, migrations, and RLS policies live in the top-level `schema/` package (owns tables and RLS; single migration history — the Python side reflects, no Alembic)
`next`	Marketing site framework (Next.js 14, App Router)
`expo` + `expo-router`	Mobile framework (React Native)
`posthog-js`	Product analytics + session replay on `ui/web-app` (client; masking on)
`posthog-node`	Server-side PostHog for flags (local eval) + events — `ui/web-app` server and `ui/marketing`
`posthog-react-native`	Product analytics + session replay on `ui/ios` (masking on)
`turbo`	Monorepo build system (Turborepo)

JS/TS Dev / Test

Library	Purpose
`@biomejs/biome`	Linting + formatting
`lefthook`	Git hooks
`vitest`	Test runner (`ui/web-app`, `ui/marketing`, `ui/ios`)
`@testing-library/react` + `@testing-library/react-native`	React / React Native component testing

Substitution Policy

These libraries were chosen for:

Ecosystem fit — they work well together and with the rest of the stack.
Performance — e.g., Polars over Pandas for data processing, Biome over ESLint for speed.
Maintenance — actively maintained with strong community support.
Compliance — compatible with HIPAA requirements and vendor BAAs.

If a project requires a different library:

Document the justification in the PR description.
Update .github/copilot-instructions.md to reflect the change.
Ensure the replacement meets the same quality and compliance standards.