Foundation Architecture

The complete technological blueprint for any company whose mission includes shipping software — from the first git init to a fully observable, HIPAA-compliant production environment.

Foundation defines every layer of the stack — infrastructure, CI/CD, observability, security, data pipelines, developer tooling, and the SaaS services that tie them together — so that a team of any size can stand up a production-grade platform in days, not months. Whether you are a three-person startup or a hundred-person organization, this documentation is the single source of truth for how your technology operates.

AI-Native Development

Foundation is designed from the ground up for AI-native development — a workflow where anyone who can write a clear, detailed ticket can ship production code, regardless of their engineering background.

The entire stack is structured so that a greenlit coding agent (Claude Code / GitHub Copilot) can take a plain-English ticket from Linear all the way to a merged, deployed feature with minimal human intervention:

Architecture at a Glance

Key Design Principles

1. AI-native by design. The entire workflow — ticket → agent → PR → preview → merge → production — is optimized for coding agents. Anyone who can write a clear ticket can ship code.
2. HIPAA-first. Every vendor touching PHI requires a BAA, and several services are explicitly kept PHI-free (see HIPAA Compliance). PHI never appears in logs. Compliance is scaffolded, not bolted on.
3. Monorepo with strict modularity. One concern per file. Enables parallel AI-assisted development with zero merge conflicts.
4. Cross-cloud data bridge. Neon (OLTP, source of truth) → BigQuery (OLAP) via incremental sync (WHERE updated_at >), minimizing egress across the GCP ↔ AWS boundary.
5. Reproducible environments. Devbox + direnv + process-compose ensure every developer gets an identical setup in one command.
6. Coverage gates. ≥ 80% test coverage enforced in CI. No PR merges without passing all quality checks.

Documentation Sections

Prompt Templates

This architecture ships with two prompt templates for AI-assisted project management:

Stack Index — Function → Greenlit Tool

This is the greenlit-tool registry — the canonical function → tool lookup and the first place to answer "what do we use for X?". One row per function, grouped by domain, with columns Function · Role · Vendor · Product. Each tool's role, wiring, and rationale live on the linked Foundation page — click the Product cell to jump to the detail.

Product — Frontend & Client

Product — Backend, Data & AI

Product — Infrastructure, DevOps & Observability

Product build — Collaboration & Knowledge

Business Ops — Productivity, Communication & Identity

Business Ops — People, Finance & Legal

Business Ops — Corp Dev / M&A

The acquisition motion (~a dozen deals over ~5 years) gets first-class functions.

Business Ops — Sales, Marketing & Support

Inherited (legacy systems)

Systems inherited at close. Disposition (keep / migrate / sunset) is unresolved for every row — each is a ⚠️ gap, not a greenlit choice, and none is documented in Foundation yet.

Open & deferred decisions

Every ⚠️ / ⏸ row above, collected so an agent never treats an in-flight bake-off as a locked choice.

See also:

• The Stack (Pricing) — per-tool pricing for the greenlit stack
• Business Operations — the non-product IT / ops stack in detail
• HIPAA Compliance — the trust zone, vendor BAAs, and PHI-free surfaces

Incubation Workflow (GitHub Spark)

The Incubation Workflow allows for zero-friction prototyping using GitHub Spark. Use Spark to vibe the initial UI and logic of a feature or micro-app. Once the idea has legs, use the Foundation agentic pipeline to port the code into the production monorepo.

The Service-First Rule

To ensure graduation is a near 1:1 operation, every Spark project must follow the Service Abstraction Pattern. This prevents lock-in to Spark's managed runtime (window.spark).

Spark Context File

When starting a new Spark project, upload or paste the following rules into the Spark editor as context. A ready-to-use template is available for download:

📥 Download SPARK-RULES.md

The Graduation Process

When you are ready to move a Spark project into the Foundation monorepo, follow these steps:

Self-Consistency Checklist

The Incubation Workflow is consistent with the following Foundation principles:

Monorepo Structure — Turborepo

All Foundation projects are organized as a Turborepo monorepo. This provides unified build orchestration, dependency deduplication, and a single repository for all application code, infrastructure, and configuration.

Directory Layout

/
├── ui/
│   ├── web-app/     # Authenticated web application — Vite + TanStack (Router + Query, TypeScript)
│   ├── marketing/   # Marketing site — Next.js 14 (App Router, TypeScript)
│   ├── ios/         # Mobile app — Expo (React Native, TypeScript)
│   ├── types/       # Shared TypeScript type definitions
│   ├── components/  # Shared React component library
│   ├── common/      # Shared TypeScript "business logic" libraries
├── backend/
│   ├── api/         # FastAPI HTTP service (Python)
│   ├── worker/      # Restate durable-execution handlers — durable / agent workflows (Python)
├── schema/          # Drizzle Kit — schema, migrations, RLS policies (single migration history; TypeScript)
├── policies/        # Cerbos authorization policies — app-level PDP that pairs with Neon RLS (YAML)
├── infra/           # Pulumi infrastructure-as-code (TypeScript) — includes restate.ts (Restate Cloud wiring)
├── dbt/             # dbt project — BigQuery adapter (Neon → BigQuery)
├── .github/
│   ├── copilot-instructions.md   # AI assistant context
│   ├── skills/                   # Repository copilot skills
│   └── workflows/                # GitHub Actions CI/CD
├── turbo.json
├── package.json         # Root workspace manifest
├── pnpm-workspace.yaml  # pnpm workspace packages
├── biome.json           # BiomeJS config (JS/TS linting + formatting)
├── lefthook.yml         # Git hooks
└── README.md

turbo.json

Defines pipelines for all monorepo tasks:

Remote caching should be configured when available (left as a commented-out TODO in fresh scaffolds).

📥 Download turbo.json template

Root package.json

The root package.json serves as the workspace manifest:

{
  "private": true,
  "packageManager": "pnpm@latest",
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "format": "turbo run format",
    "type-check": "turbo run type-check"
  },
  "devDependencies": {
    "turbo": "latest",
    "@biomejs/biome": "latest",
    "lefthook": "latest"
  }
}

📥 Download root package.json template

Workspaces are declared in pnpm-workspace.yaml (pnpm does not use the workspaces field in package.json):

packages:
  - "ui/*"
  - "backend/*"
  - "schema"

Workspace Conventions

• ui/ — Frontend applications and shared UI libraries. Contains deployable apps (web-app/ — Vite + TanStack applications frontend on Cloud Run; marketing/ — Next.js 14 marketing site on Cloud Run; ios/ — Expo React Native) and shared packages (types/, components/, common/). Each has its own package.json, build command, and deployment target.
• backend/ — Backend services. Contains the FastAPI HTTP service (api/) and the Restate durable-execution handlers (worker/) for async / agent workflows. Each has its own pyproject.toml, build command, and deployment target.
• schema/ — Drizzle Kit package: the single migration history, schema, and RLS policies (TypeScript, its own tsconfig.json). The Python backend reflects this schema — no Alembic.
• policies/ — Cerbos authorization policies (YAML) — the app-level policy decision point that pairs with Neon RLS. Not part of the JS or Python workspace graph.
• infra/ — Pulumi program (includes restate.ts, which wires the managed Restate Cloud environment — no self-hosted node). Has its own package.json and is not part of the Turborepo workspace graph (deployed separately).
• dbt/ — dbt project (BigQuery adapter). Pure SQL + YAML, managed by Python tooling (not part of the JS workspace graph).

TypeScript Configuration

Foundation follows a one tsconfig.json per logical unit rule. A "logical unit" maps to each workspace package (deployable app or shared library package) — not to arbitrary subdirectories inside a package.

Typical settings

Each tsconfig should extend a shared base (e.g., @tsconfig/strictest or a root-level tsconfig.base.json):

// ui/marketing/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "plugins": [{ "name": "next" }],
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src", "next-env.d.ts", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

// ui/ios/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-native",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src", "app", "*.ts", "*.tsx"],
  "exclude": ["node_modules"]
}

// ui/components/tsconfig.json  (repeated pattern for every shared package)
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "declaration": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

If present, a root-level tsconfig.base.json at the repo root holds the common strict settings (strict: true, noUncheckedIndexedAccess, exactOptionalPropertyTypes, etc.) so each unit opts in by extending it rather than duplicating options.

Why Turborepo?

1. Incremental builds. Only rebuilds what changed. Dramatically speeds up CI.
2. Parallel execution. Tasks across workspaces run concurrently by default.
3. Dependency graph awareness. Automatically determines build order based on workspace dependencies.
4. Remote caching. (When enabled) Shares build artifacts across the team and CI.
5. Simple configuration. Single turbo.json file, no complex plugin system.

Frontend — Applications + Marketing

There are two web surfaces, both deployed to GCP Cloud Run (no Vercel):

• ui/web-app — the applications UI. A full-stack Vite + TanStack server (Router + Query, TypeScript) running on Node → GCP Cloud Run — not a static SPA. Its server runtime hosts Better Auth and server-side Drizzle data access, so it needs runtime secrets (DATABASE_URL, BETTER_AUTH_SECRET) — not just build-time config. This is where authenticated, PHI-touching product features live.
• ui/marketing — the marketing site. Built with Next.js 14 (App Router), TypeScript. Public content only — no auth, no PHI.

Core Stack

Auth — Better Auth (on the applications-UI server)

Authentication is Better Auth, self-hosted by the applications-UI server (the Vite + TanStack app's server runtime) — not the marketing site.

• Better Auth stores its tables in Neon (Postgres adapter) → inside the HIPAA boundary; auth branches with each Neon branch for free.
• It issues sessions and a JWKS endpoint. The FastAPI backend and Neon RLS (pg_session_jwt) validate those JWTs so auth.user_id() drives row access.
• Supports email/password, OAuth social, sessions, and 2FA / SSO plugins.

Serverless notes (Cloud Run scale-to-zero)

Better Auth is a request-handler library, not an always-on service — all its state (users, sessions, JWKS keys) lives in Neon, so it bundles into the ui/web-app container and scales to zero cleanly (no background worker). Configure it for serverless:

• Rate-limit storage — the default is in-memory, which is wrong for scale-to-zero / multi-instance (not shared, wiped on every cold start). Point it at Neon (or a secondary store). This is the one that bites people.
• Session validation — enable cookieCache so most requests skip a Neon round-trip on session lookup, cutting latency + DB load when bursty cold starts all hit the database.
• Connections — use Neon's pooled connection string so a burst of Cloud Run instances doesn't exhaust Postgres connections.
• JWKS — have the FastAPI API cache the JWKS (long TTL) so a request during an idle window doesn't cold-start the app server just to fetch keys.

Data access (applications UI)

Server-side only, via Drizzle ORM over a direct Neon Postgres connection — never the Neon Data API (it sits outside the HIPAA boundary). Drizzle-managed RLS (crudPolicy, authenticatedRole) — defined in the top-level schema/ package alongside the tables and migrations — keeps authorization reviewable through the PR schema-diff gate. See Backend and HIPAA Compliance.

Browser → API calls

The applications UI talks to two backends, and the auth token flows through both:

1. The ui/web-app server issues the Better Auth session and a signed JWT (Better Auth's JWKS endpoint lives here — see above).
2. Browser calls to the Python backend/api go through the generated openapi-fetch client (types + client in src/lib/api/, see Backend), which attaches the Better Auth JWT as a bearer token.
3. backend/api validates that JWT against the JWKS (BETTER_AUTH_JWKS_URL) and binds it to the Neon connection, so Neon RLS (pg_session_jwt + the authenticated role) keys row access on auth.user_id().

So the same Better Auth identity that gates the UI server also drives DB-level row isolation on the API — no second login, one identity end-to-end. (Mobile does the same with its session token — see Mobile.)

Environment Variables

Dependencies

Applications (ui/web-app) — runtime

• vite, @tanstack/react-router, @tanstack/react-query
• better-auth — auth server + client
• drizzle-orm + pg — data access (Neon)
• openapi-typescript + openapi-fetch — typed API client generated from the FastAPI OpenAPI schema into src/lib/api/ (via pnpm gen:api; see Backend)
• posthog-js — product analytics + session replay on the client (masking on — see below)

Marketing (ui/marketing) — runtime

• next

Dev / Test (both)

• vitest + @testing-library/react

Product analytics — PostHog (posthog-js)

ui/web-app initialises posthog-js on the client for product analytics, feature flags, experiments, session replay, and client error tracking. Server-side flag evaluation / event capture uses posthog-node (single long-lived client, local evaluation) as on the marketing site. PostHog's full role across the stack (analytics + flags + experiments + replay + client error tracking + LLM observability & evals) is described in Observability and Content Management.

Because replay runs on clinical screens, masking is not optional — this closes a real HIPAA gap:

• Turn on session-replay masking: maskAllInputs: true and mask clinical text (maskTextSelector covering PHI-bearing elements).
• Identify by opaque user IDs only — never a name, email, or MRN.
• Keep no PHI in event names, property keys, or flag keys. See HIPAA Compliance.

// lib/analytics.ts
import posthog from 'posthog-js'
 
posthog.init(import.meta.env.VITE_POSTHOG_KEY, {
  api_host: import.meta.env.VITE_POSTHOG_HOST,
  session_recording: {
    maskAllInputs: true,          // never record raw input values
    maskTextSelector: '[data-phi]', // mask clinical text nodes
  },
})

Cloud Run Deployment

Both surfaces are containerised and deployed to GCP Cloud Run, matching the backend worker. Each has its own Dockerfile; the marketing Next.js build uses output: 'standalone'.

Mobile — ui/ios (Expo)

The mobile application uses the Expo managed workflow with React Native and TypeScript.

Core Stack

Auth — Better Auth

The mobile app authenticates against the same Better Auth instance the web applications use — hosted by the applications-UI server (see Frontend), backed by Neon. Use the Better Auth Expo client plugin; a login screen is scaffolded at app/(auth)/login.tsx via expo-router. The app never talks to Neon directly — it calls the FastAPI API with the Better Auth session token.

Environment Configuration

Environment variables are provided via app.config.ts reading EXPO_PUBLIC_* vars:

export default {
  expo: {
    extra: {
      apiUrl: process.env.EXPO_PUBLIC_API_URL,
      betterAuthUrl: process.env.EXPO_PUBLIC_BETTER_AUTH_URL,
    },
  },
};

Dependencies

• expo — Expo SDK
• expo-router — File-based routing
• better-auth + @better-auth/expo — auth client
• expo-secure-store — secure token storage
• posthog-react-native — product analytics + session replay (masking on — see below)

Dev

• vitest + @testing-library/react-native — component testing (React Native environment)

Analytics — PostHog (posthog-react-native)

The mobile app uses posthog-react-native for product analytics, feature flags, experiments, and session replay, feeding the same PostHog project as the web app. PostHog's full role across the stack is described in Observability.

The same masking discipline applies — replay can capture clinical screens, so:

• Enable session-replay masking: maskAllTextInputs: true and maskAllImages: true, plus wrap PHI-bearing views in <PostHogMaskView> (or the ph-no-capture marker).
• Identify by opaque user IDs only — never a name, email, or MRN. Keep no PHI in event names, property keys, or flag keys. See HIPAA Compliance.

// app/_layout.tsx — wrap the router in the PostHog provider
import { PostHogProvider } from 'posthog-react-native'
 
export default function RootLayout() {
  return (
    <PostHogProvider
      apiKey={process.env.EXPO_PUBLIC_POSTHOG_KEY!}
      options={{ host: process.env.EXPO_PUBLIC_POSTHOG_HOST }}
      autocapture={{
        captureScreens: true,
        // Session replay masks PHI by default on-device.
        sessionReplay: { maskAllTextInputs: true, maskAllImages: true },
      }}
    >
      {/* expo-router <Slot /> / <Stack /> */}
    </PostHogProvider>
  )
}

Testing

Tests run on Vitest with @testing-library/react-native, enforcing ≥ 80% coverage via Vitest's v8 provider.

Because React Native ships no DOM, Vitest needs an RN-aware setup rather than the old jest-expo preset: alias react-native to react-native-web (or an RN-compatible resolver) so components resolve under Node, register @testing-library/react-native in a setup file, and run in a jsdom environment. Example vitest.config.ts:

// vitest.config.ts
import { defineConfig } from 'vitest/config'
 
export default defineConfig({
  // Resolve the RN entrypoint under Node — RN's native modules can't load in Vitest.
  resolve: {
    alias: {
      'react-native': 'react-native-web',
    },
  },
  test: {
    // jsdom gives react-native-web a DOM to render into.
    environment: 'jsdom',
    // Registers @testing-library/react-native matchers + cleanup and RN globals.
    setupFiles: ['./vitest.setup.ts'],
    globals: true,
    coverage: {
      provider: 'v8',
      thresholds: {
        branches: 80,
        functions: 80,
        lines: 80,
        statements: 80,
      },
    },
  },
})

The setup file registers the RN matchers and auto-cleanup so every test file gets them without repeating boilerplate:

// vitest.setup.ts
import '@testing-library/react-native/extend-expect' // toBeVisible(), toHaveTextContent(), …
import { cleanup } from '@testing-library/react-native'
import { afterEach, vi } from 'vitest'
 
// Unmount the rendered tree after each test to avoid cross-test state leaks.
afterEach(() => cleanup())
 
// Native-only modules aren't available under Node — stub the ones tests touch.
vi.mock('expo-secure-store', () => ({
  getItemAsync: vi.fn(),
  setItemAsync: vi.fn(),
  deleteItemAsync: vi.fn(),
}))

Backend — API (backend/api) & Durable Worker (backend/worker)

The backend is two Python services on GCP Cloud Run, both backed by Neon (Postgres):

• backend/api — a FastAPI HTTP service (request/response; the typed OpenAPI contract).
• backend/worker — the Restate durable-execution service: long-running, retriable, human-in-the-loop workflows (durable / agent orchestration).

Directory Structure

backend/
├── api/                     # FastAPI HTTP service
│   ├── src/
│   │   ├── main.py          # FastAPI app entry point
│   │   ├── config.py        # pydantic-settings BaseSettings
│   │   ├── db.py            # Neon (Postgres) engine — SQLAlchemy / asyncpg
│   │   └── routers/
│   │       └── health.py    # GET /health — liveness probe
│   ├── tests/
│   ├── Dockerfile           # Multi-stage build
│   ├── pyproject.toml
│   └── .env.example
└── worker/                  # Restate durable-execution handlers
    ├── src/
    │   ├── main.py          # Restate ASGI app (registers durable handlers)
    │   └── jobs/
    │       └── sync.py      # Durable handler: sync_wellsky_changes
    ├── tests/
    ├── Dockerfile
    ├── pyproject.toml
    └── .env.example

Dependencies

Runtime

Dev / Test

Configuration — config.py

All configuration is managed via pydantic-settings BaseSettings:

from pydantic_settings import BaseSettings
 
class Settings(BaseSettings):
    DATABASE_URL: str            # Neon Postgres connection string (branch-scoped)
    BETTER_AUTH_JWKS_URL: str    # Better Auth JWKS endpoint — validates request JWTs
    GCP_PROJECT_ID: str
    BIGQUERY_DATASET: str
    WELLSKY_CLIENT_ID: str
    WELLSKY_CLIENT_SECRET: str

Data access — Neon (Postgres)

The API talks to Neon directly over Postgres — no Supabase client, no Data API:

• SQLAlchemy or raw asyncpg over a direct connection.
• Row-Level Security is enforced in Neon. Per request, backend/api validates the caller's Better Auth JWT against the JWKS (BETTER_AUTH_JWKS_URL) and then sets that JWT on the Neon connection/transaction — Neon's pg_session_jwt extension plus the authenticated role expose the claims to SQL, so RLS policies keyed on auth.user_id() drive row access. See Libraries and HIPAA Compliance.
• RLS policies are the single source of truth for authorization; migrations + policy diffs go through the PR schema-diff gate (see PR Environments).
• Schema + migrations (including RLS) are owned by Drizzle Kit — one migration history. The Python side reflects the schema (SQLAlchemy automap / generated models); it does not run Alembic.

Authorization — Cerbos + RLS

Authorization is two-layered, and the two layers stay coherent by design:

• Cerbos is the application-level policy-decision-point (PDP). It decides relationship and role/attribute policy — "may this user perform this action on this resource?" — from policy-as-code (YAML resource policies + CEL conditions). backend/api calls the PDP per request (during HTTP request authorization) via the Python cerbos SDK. The policies live in a version-controlled, top-level policies/ directory (Cerbos YAML) loaded by the self-hosted Cerbos PDP.
• Neon Row-Level Security (RLS) remains the enforcement floor. Even if an app-layer check is missed, RLS blocks the row at the database. RLS is the last line and is non-negotiable for PHI tables.

The two layers are layered, not the same rule — defense in depth. Neon RLS is the coarse enforcement floor: tenant/row isolation, deny-by-default, always enforced by the database no matter what the app does. Cerbos adds a fine-grained relationship/action policy on top, at the app layer. Instead of asking "can this user see resource X?" one row at a time, backend/api asks Cerbos's Query Plan API for a query plan and receives a set of conditions that compile to a SQL WHERE filter. That filter is applied in addition to RLS on the same query — so a request must satisfy both the DB floor and the app-layer policy. The two are not expected to be identical rules and can legitimately differ in granularity (RLS the tenant/row floor, Cerbos the action/relationship detail); layering them is the point.

API contract — OpenAPI → typed client

FastAPI generates an OpenAPI schema from the routes + Pydantic models automatically. That schema is the contract between the API and the TypeScript app — there is no hand-written, drift-prone client.

• The API serves its schema at /openapi.json (FastAPI built-in).
• ui/web-app generates a typed client into ui/web-app/src/lib/api/ with openapi-typescript (types) + openapi-fetch (a tiny typed fetch wrapper), via a pnpm gen:api script. Types flow end-to-end: change a Pydantic model and every affected call site in the app becomes a TypeScript error.
• The generated client is committed and regenerated in CI; a drift-check job in ci.yml re-runs pnpm gen:api and fails the build on any diff between openapi.json and the committed types, so the contract can never silently rot.

Durable / async jobs — backend/worker (Restate)

Long-running and event-driven work runs in backend/worker on the Restate durable-execution layer (retriable, resumable steps) — not inline in the API's request handlers. The worker's durable handlers (in backend/worker/src/jobs/) are registered as a deployment with Restate Cloud via the Restate ASGI app in main.py; Restate Cloud then invokes, journals, and re-drives them on retry, calling the worker's signed public endpoint. Example: sync_wellsky_changes (backend/worker/src/jobs/sync.py):

• Trigger: wellsky/sync.requested — emitted by backend/api (e.g. from a WellSky webhook route) and delivered to the handler by Restate Cloud.
• Steps: Fetch changes from WellSky → upsert into Neon → sync analytics rows to BigQuery
• PHI discipline: event payloads carry opaque, short-lived IDs only — never stable DB primary keys — and the function fetches PHI from Neon inside the boundary. Short-lived IDs are the primary entity identifier so the metadata Restate does hold can't become a durable re-identification vector. This keeps PHI out of the orchestration layer regardless of vendor.

Dockerfile

Multi-stage build optimized for Cloud Run:

The runtime stage exposes port 8080 (Cloud Run default).

Code Quality

Ruff Configuration (pyproject.toml)

[tool.ruff]
line-length = 100
target-version = "py311"
 
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "S"]
ignore = ["S101"]
 
[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S"]

Build Targets

A Makefile or justfile provides standard targets:

AI Tier — Gemini on Vertex AI

Decision: the entire AI tier runs on Google Gemini via Vertex AI. One Google Cloud BAA covers reasoning, embeddings, and voice — in the same cloud as the app, with PHI staying in-boundary. We break a subcomponent out to another provider only when a concrete, evidenced need forces it (see Escalation). The full provider bake-off lives in the Compute Stack Plan (Notion).

Subcomponents

Each is separable — the boundary and BAA are shared, so swapping one (e.g. the reasoning model) doesn't disturb the others.

Why one provider

• One boundary, one BAA. Reasoning + embeddings + voice all sit inside the Google Cloud BAA, in the same cloud as the Cloud Run app — no third-party inference hop, no second contract.
• Gemini uniquely closes two gaps that bite single-model shops: in-GCP HIPAA-covered embeddings (gemini-embedding-001) and a realtime voice path with named-covered STT/TTS (Chirp). Claude, for example, offers neither and would force a second provider for both.
• Fewer moving parts beats marginal per-task model quality at this stage.

HIPAA posture (required)

• BAA: Vertex AI is covered under the Google Cloud BAA (on the covered-products list as "Generative AI on Gemini Enterprise Agent Platform"). Never use the ai.google.dev Gemini Developer API or AI Studio — not BAA-covered.
• Region: pin to a US region, not global (global lacks CMEK / Access Transparency).
• Retention: request abuse-logging opt-out / Zero Data Retention (default abuse logging retains prompts up to 90 days).
• Isolation: VPC-SC + CMEK; a separate GCP project for HIPAA workloads.
• Schema hygiene: never put PHI in JSON-schema field names / enums / regex (schemas are cached without PHI protections).

Escalation — break out only when forced

Default everything to Gemini/Vertex. Reach for another provider only when a specific, evidenced need demands it — and even then, prefer to stay inside a BAA boundary. Both of these are subcomponent-level swaps, not a tier rewrite:

• Reasoning quality — if an eval shows Gemini losing materially on our concierge / clinical tasks, escalate that subcomponent to Claude on Vertex AI (still the same GCP BAA, same boundary).
• Retrieval latency — if RAG traffic needs to be co-located with Neon, run embeddings on Bedrock (us-west-2) (the AWS BAA, same region as the DB).

The bake-off and trade-offs behind this are documented in the Compute Stack Plan (Notion).

Agentic Architecture — Multi-Agent Care Orchestration

The system behind agent-driven onboarding, scheduling, and care ops — the product's core differentiator. It is a multi-agent, orchestrated design: a durable Restate orchestrator (backend/worker) sequences specialist Gemini agents, grounded on an append-only care-context event log in Neon + pgvector, with human-in-the-loop gates and everything held inside the Vertex BAA boundary (see AI Tier and HIPAA Compliance).

1. Topology — multi-agent, orchestrated

• Orchestrator — a durable Restate workflow in backend/worker that owns the end-to-end journey (prospect → onboarded client), routes to specialists, holds durable state, and enforces the human-in-the-loop gates.
• Specialist agents — each a Gemini loop with a scoped toolset:

• Each specialist is a sub-workflow / durable step the orchestrator invokes; the orchestrator sequences them and owns the kickoff gate. Conversational surfaces (the ui/web-app and, later, voice) drive the intake agent through the orchestrator, never the model directly.

2. The agent loop

• Each agent is Gemini via Vertex (SDK google-genai, vertexai mode) running a bounded reason → tool-call → observe loop. Model tier and BAA/region posture are governed by the AI Tier decision (US region, abuse-logging opt-out, no ai.google.dev).
• Tools are typed functions (JSON-schema, derived from the OpenAPI / Pydantic contract in backend/api) that:
  • read/write Neon under RLS — the agent acts as the session identity, so it sees only entitled rows;
  • call WellSky (referrals, EVV, caregivers);
  • retrieve from the care-context log + pgvector;
  • take actions — propose plan, commit schedule, send comms via Telnyx / AWS SES.
• Determinism boundary: each LLM call and each tool call is wrapped as a Restate durable step — journaled and retriable. On crash the workflow resumes exactly where it left off, and already-committed side-effects are not re-run on replay.

3. Memory & the data moat

• Short-term (conversation + working state) lives in Restate workflow state — durable, survives restarts, no separate session store.
• Long-term = the moat: an append-only care-context event log in Neon — every interaction, decision, plan, schedule change, and outcome captured as structured events. This is the proprietary dataset.
  • Retrieval: pgvector over embeddings (gemini-embedding-001) of the log + notes, RLS-scoped so retrieval only surfaces entitled context. Agents ground via RAG, not prompt-stuffing.
  • Embeddings are computed in-boundary — clinical text is PHI, so it is embedded inside the Vertex BAA boundary; never an out-of-boundary embedder.
• A BigQuery mirror (via dbt) serves analytics / eval — de-identified where it leaves the boundary (see Data Pipeline).

The event-log schema is defined in schema/ (Drizzle) alongside the rest of the Neon model.

4. Durability + human-in-the-loop (why Restate)

• The signature flow — chat → design schedule → implement → human kickoff call → activate — is long-running, suspendable, and human-gated.
• Restate durable promises make "await a human" a first-class primitive: the workflow suspends to zero (scale-to-zero on Cloud Run) while waiting for a human action, then resumes deterministically — no polling, no lost state.
• Approval gates: schedule commit + go-live block on a durable promise resolved by a care-coordinator UI action in the ui/web-app.
• Idempotency: each step is keyed; WellSky / SES / Telnyx calls are idempotent + journaled, so retries never double-book or double-send.

5. Boundary, safety & governance (HIPAA)

• In-boundary: Gemini via Vertex (BAA); PHI in Neon (RLS); retrieval in-zone. No agent I/O to Notion or any no-BAA surface (see HIPAA Compliance).
• PHI-free telemetry: agent traces/logs carry opaque IDs only; full transcripts (if kept) live in Neon and are redacted in Cloud Logging. This keeps the observability plane on the PHI-free service list.
• Tool-level authz = RLS + Cerbos — the agent can't touch what the acting identity can't. Cerbos supplies policy-as-code decisions (Query Plan → SQL filters) over the Neon RLS floor; each agent gets a least-privilege toolset.
• Guardrails / eval: in/out PHI-leak filters on anything crossing a boundary; an eval harness (golden transcripts) gates prompt/tool changes; human-in-the-loop for high-stakes actions.
• Auditability: the event log + the Restate journal together form a complete, replayable audit trail of every agent decision and action.

6. Open questions

See also:

• Backend — backend/api, the backend/worker Restate runtime, Cerbos, Neon RLS, and schema/
• AI Tier — Gemini on Vertex, embeddings, and the HIPAA posture for the model layer
• HIPAA Compliance — the trust zone, vendor BAAs, and PHI-free telemetry

Infrastructure as Code — infra/ (Pulumi, TypeScript)

Infrastructure is managed using Pulumi with TypeScript, spanning Google Cloud Platform (compute, registry, secrets), Neon (Postgres), and Cloudflare (DNS + CDN). State lives on Pulumi Cloud — no self-managed state bucket.

Directory Structure

infra/
├── index.ts          # Main Pulumi program — wires the modules together, stack exports
├── gcp.ts            # Cloud Run (web-app/marketing/api/worker), Load Balancing + Cloud Armor, GCS, Artifact Registry, Secret Manager, WIF, BigQuery
├── restate.ts        # Restate Cloud wiring — environment config + request-signing key (Secret Manager); the runtime itself is managed off-cluster
├── neon.ts           # Neon project (Scale, hipaa:true), branches, roles
├── cloudflare.ts     # DNS records, proxied CDN endpoints
├── tailscale.ts      # Tailscale subnet router (GCE VM) + internal ALB — non-prod tailnet access
├── Pulumi.yaml       # Project configuration
├── Pulumi.dev.yaml   # Dev stack config (placeholder values)
└── package.json      # Pulumi + provider dependencies

State Backend — Pulumi Cloud

Pulumi state and secrets encryption are hosted on Pulumi Cloud (app.pulumi.com). This gives the team drift detection, per-stack history, and a shared encryption key without operating a state bucket.

GCP Resources — gcp.ts

Cloud Run Services

Four services, all containers from Artifact Registry:

Cloud Run IAM

• Public invocation is allowed for the marketing site, the /health liveness probe, and the worker's Restate ingress path only. The worker endpoint is public at the Cloud Run IAM layer because Restate Cloud is an off-GCP caller — it is authenticated in the handler by verifying Restate Cloud's request signature, not by Cloud Run IAM.

Restate Cloud wiring — restate.ts

The Restate durable-execution runtime is Restate Cloud — a fully managed, serverless Restate environment (region us), not a self-hosted server. There is no GCE VM, no persistent disk, and no Rust node to operate: Restate Cloud holds the durable state and drives execution, invoking the worker's HTTP handlers and suspending them to zero between steps. restate.ts therefore provisions no compute — it only wires the connection: the Restate Cloud environment endpoint/region and the request-signing public key, materialized into Secret Manager for the worker.

• Runtime: managed by Restate Cloud off-GCP. Because it is serverless there is no always-on node in our VPC to size, patch, or pay for at idle.
• Invocation: Restate Cloud calls the worker's public HTTPS endpoint and each request is signed with the environment key; the worker verifies the signature in-handler. Handlers suspend between steps, so worker still scales to zero when idle.
• Config: the worker service reads RESTATE_* (Restate Cloud environment endpoint + identity/signing keys) from Secret Manager. See Environment Variables and Backend.

Artifact Registry

• Docker image repository for the web-app, marketing, api, and worker services.
• Images are tagged with commit SHA for traceability.

Secret Manager

• Runtime store for application secrets, materialized from Pulumi ESC and mounted into Cloud Run at deploy time. See Secret Management.

Workload Identity Federation

• GitHub Actions authenticates to GCP via Workload Identity Federation (GitHub OIDC) — no long-lived service-account JSON keys are stored as secrets.

BigQuery Dataset

• Name: raw_data
• Location: US
• Landing zone for the incremental Neon → BigQuery extract-load (see Data Pipeline).

Object Storage — GCS (user uploads / documents)

User-uploaded files and generated documents live in Google Cloud Storage, inside the trust zone:

• CMEK — buckets are encrypted with customer-managed encryption keys (Cloud KMS), not just Google-default keys.
• Signed URLs — clients never get direct bucket ACLs; the API mints time-limited signed URLs for upload/download so access is scoped and auditable.
• No public buckets. Uniform bucket-level access; PHI-bearing objects stay private and are served only via signed URLs.
• PHI-bearing uploads live in GCS inside the trust zone; the full PHI-at-rest list (Neon · GCS · Vertex AI · WellSky · the governed M365 plane) is on the HIPAA Compliance page.

Neon — neon.ts

Neon is managed by Pulumi via the Neon Pulumi provider — the project, its HIPAA posture, branches, and roles are all declarative resources:

1. Project on the Scale plan, region AWS us-west-2 (same metro as Cloud Run us-west1 to minimize cross-cloud egress).
2. hipaa: true set on the project (irreversible; sets audit_log_level=hipaa). The BAA is self-serve on Scale — no separate add-on.
3. Extensions: pgvector (embeddings) and pg_session_jwt (Better Auth JWT → RLS auth.user_id()).
4. Roles & authorization: least-privilege application role(s). Neon RLS is the enforcement floor — the last-line database guard that holds even if app code is wrong — while Cerbos (a self-hosted, stateless PDP running in-boundary) is the app-level policy decision point for richer, contextual authorization. RLS schema + migrations live in the top-level schema/ dir (owned by Drizzle Kit); Cerbos policies live in the top-level policies/ dir. RLS is the floor, not the authorization source of truth.
5. Branches: the primary branch plus the copy-on-write branch-per-PR model — ephemeral pr-<n> branches are created by CI, not Pulumi.

Edge & WAF — split by PHI exposure

The edge is deliberately split so that PHI never transits a vendor we don't need a BAA with:

Cloudflare — cloudflare.ts

DNS and CDN are managed with the Cloudflare Pulumi provider:

• DNS records for the apex + subdomains. Marketing points at its Cloud Run service via the Cloudflare proxy; the web-app / API hostnames are DNS-only (grey-cloud), resolving to the GCP load balancer so their traffic bypasses Cloudflare entirely.
• Proxied (orange-cloud) endpoints for CDN + DDoS protection on the PHI-free marketing surface only.

Tailnet Access — Tailscale (non-prod dev surfaces)

Every non-production surface — per-PR previews, the shared dev / staging env, and the Coder remote-dev workspaces — is reachable only from the company tailnet (Tailscale). Production is unaffected. One tailnet is the single "dev network," so there is no second access mechanism to operate.

Shape — one internal LB, wildcard DNS, tailnet-only:

1. Preview / staging Cloud Run services deploy with ingress = internal-and-cloud-load-balancing — no public *.run.app URL. They are reachable only through the internal load balancer.
2. One regional internal Application Load Balancer (a private VIP in the VPC) does host-based routing. A wildcard Cloud DNS private zone *.pr.internal resolves to the LB VIP, so there is no per-PR DNS record — CI adds a serverless NEG + one URL-map host rule per PR (web-app-pr-<n>.pr.internal, api-pr-<n>.pr.internal) and removes them on teardown. One LB, N backends.
3. A Tailscale subnet router — one always-on node (small GCE VM; infra/tailscale.ts) — advertises the route to the LB VIP into the tailnet and pushes split-DNS for *.pr.internal. A Tailscale ACL scopes reachability to the dev group.
4. Net effect: a dev on the tailnet opens https://web-app-pr-42.pr.internal; it resolves to the internal LB, host-routes to the right service — and nothing off the tailnet can reach it (the LB has no public IP; the only ingress path is the subnet router). This is network-level isolation, stronger than a public endpoint gated by IAP.

Caching — Redis deferred

There is no Redis in the initial stack. The two things a cache would carry are handled in-database for now:

• Better Auth rate-limit storage and light caching live in Neon (Postgres). Better Auth supports a database-backed rate limiter, which is sufficient at launch volumes.
• Add Memorystore (Redis) only when real pressure appears — hot-path read latency, rate-limit write contention, or session/cache volume that Postgres shouldn't absorb. It slots in as a managed GCP resource (in-boundary) when the need is demonstrated, not preemptively.

Resource Organization

Following the code organization principle of one concern per file:

As the infrastructure grows, further split gcp.ts by service (e.g., cloudrun.ts, artifact-registry.ts, bigquery.ts, secrets.ts).

See also:

• Secret Management — Pulumi ESC + GCP Secret Manager
• PR Environments — ephemeral Neon branch + Cloud Run per PR
• HIPAA Compliance — Neon Scale + BAA, hipaa:true

Data Pipeline — Neon → BigQuery (dbt)

The data pipeline syncs Neon (OLTP / application database — the source of truth) into BigQuery (OLAP / analytics warehouse). Neon is where the app reads and writes; BigQuery is where analytics, reporting, and data-moat modeling run. Data flows app → warehouse (the reverse of the older Supabase-era pipeline).

Architecture

App (Cloud Run) ──writes──▶ Neon (Postgres · OLTP · source of truth)
                                  │
                    extract-load (incremental, nightly)
                                  ▼
                           BigQuery (raw_*)
                                  │
                              dbt (transform, in BigQuery)
                                  ▼
                           BigQuery (marts) ──▶ BI / analytics / ML

1. The app reads/writes Neon for low-latency OLTP.
2. A scheduled extract-load job copies changed rows from Neon into BigQuery raw_* tables — incrementally, WHERE updated_at > <watermark>.
3. dbt (BigQuery adapter) transforms raw_* → marts within BigQuery.

Directory Structure

dbt/
├── dbt_project.yml
├── profiles.yml.example      # BigQuery target
├── models/
│   ├── staging/
│   │   └── stg_patients.sql          # cleans raw_patients (from the Neon extract)
│   └── marts/
│       └── active_patients.sql       # incremental mart, materialized in BigQuery
└── README.md

jobs/
└── neon_to_bq.py             # extract-load: changed Neon rows → BigQuery raw_*

Extract-Load — neon_to_bq.py

Reads changed rows from Neon and loads them into BigQuery raw tables, watermarked to minimize egress:

# conceptual — pulled from Neon each run, then loaded into BigQuery raw_*
SELECT * FROM patients WHERE updated_at > :last_watermark;

• Runs as a scheduled Cloud Run Job (neon-to-bq) — a standalone job, not part of the backend/worker service. Cloud Scheduler (or the nightly dbt.yml workflow) triggers it.
• Loads into BigQuery raw_* via the google-cloud-bigquery client.
• Persists the watermark (max updated_at) so each run transfers only new/changed rows.

Cross-Cloud Egress

Neon runs in AWS us-west-2; BigQuery in GCP. The WHERE updated_at > watermark keeps the Neon → BigQuery transfer incremental — only new/changed records cross the boundary. Full-table cross-cloud scans are prohibited (egress cost + compliance risk).

Key Model — active_patients.sql (in BigQuery)

Incremental materialization minimizes reprocessing on each run:

{{ config(materialized='incremental', unique_key='patient_id') }}
 
SELECT
    patient_id,
    first_name,
    last_name,
    date_of_birth,
    updated_at
FROM {{ ref('stg_patients') }}
{% if is_incremental() %}
WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
{% endif %}

Scheduling — GitHub Actions

The pipeline runs nightly via .github/workflows/dbt.yml:

Backups & Disaster Recovery

Every data store has a defined backup mechanism, retention window, and restore path. This is a HIPAA contingency-plan requirement (§164.308(a)(7)) — designed in, not bolted on.

What backs up what

RTO / RPO targets

Restore runbook — Neon

1. Identify the target time — the last-known-good timestamp, before the incident.
2. Branch, don't overwrite. Create a Neon branch at that timestamp (neondatabase/create-branch-action / Neon API) and validate the data there first — never restore in place blind.
3. Cut over — repoint the app's DATABASE_URL (via GCP Secret Manager) to the restored branch, or promote it to primary.
4. Rebuild downstream — trigger the extract-load + dbt to rebuild BigQuery from the restored Neon state.
5. Record the event (what, when, blast radius, root cause) for the compliance / audit log.

Managed in IaC

Retention windows, GCS object versioning + lifecycle, and BigQuery snapshot schedules are declared in Pulumi (see Infrastructure) — reproducible and code-reviewed, never clicked in by hand.

CI/CD — GitHub Actions

All CI/CD pipelines run on GitHub Actions. Each workflow lives in its own .yml file under .github/workflows/.

ci.yml — Pull Request Quality Gate

Trigger: pull_request targeting dev (feature work), release/* (release candidates), or hotfix/* (production hotfixes) — see the branch strategy

All jobs run in parallel where possible. No PR may be merged unless all jobs pass.

Deployment workflows — one per deployable surface

Each deployable surface has its own workflow, triggered by a push to main with a path filter scoped to that surface. All follow the same pattern: authenticate via Workload Identity Federation (keyless), build + push a Docker image to Artifact Registry, then google-github-actions/deploy-cloudrun.

PR Preview Environments — pr-env-up.yml / pr-env-down.yml

Every pull request gets an isolated full-stack environment — a Neon branch, a backend API on Cloud Run, and a frontend UI on Cloud Run — that is automatically provisioned and torn down.

See PR Preview Environments for the full specification, including workflow structure, secrets, and application code requirements.

dbt.yml — Nightly Data Pipeline

Trigger: Schedule 0 3 * * * (3:00 AM UTC) + workflow_dispatch

dbt uses the dbt-bigquery adapter and authenticates to BigQuery via Workload Identity Federation — it transforms entirely inside BigQuery and never connects to Neon/Postgres. The Neon → BigQuery move is the separate extract-load step, which runs as a scheduled Cloud Run Job before dbt run.

See Data Pipeline for details on the extract-load job and dbt models.

Workflow Organization

Each workflow is a separate file, following the code organization principle:

.github/workflows/
├── ci.yml               # PR quality gate (lint · Vitest · pytest · type-check · openapi-drift · build)
├── deploy-api.yml       # Cloud Run deploy — backend/api (FastAPI)
├── deploy-worker.yml    # Cloud Run deploy — backend/worker (Restate)
├── deploy-web-app.yml   # Cloud Run deploy — ui/web-app
├── deploy-marketing.yml # Cloud Run deploy — ui/marketing
├── pr-env-up.yml        # Ephemeral PR environment spin-up
├── pr-env-down.yml      # Ephemeral PR environment teardown
└── dbt.yml              # Nightly data pipeline (extract-load Cloud Run Job + dbt run/test on BigQuery)

Ephemeral PR Preview Environments

Every pull request automatically gets an isolated, full-stack environment — a dedicated applications UI (Vite + TanStack), Python API, and Neon database branch (with isolated auth) — that is torn down when the PR closes.

Architecture Overview

GitHub Actions Secrets

Spin-Up Workflow — pr-env-up.yml

Trigger: pull_request on types [opened, synchronize, reopened], scoped to base: dev (branches: [dev]). Only PRs targeting dev — i.e. feature/* work — spin up a Staging preview. release/* / hotfix/* PRs (which target main) get no preview env; they verify in-boundary against a Neon Production branch instead. See Secure PHI GitOps.

Concurrency: Cancel in-progress runs for the same PR to avoid race conditions.

Job 1 — Database Provisioning (Neon)

Uses neondatabase/create-branch-action to create a branch scoped to the PR off the non-PHI Staging project — feature branches never fork production. See Secure PHI GitOps for the dual-project (Staging non-PHI / Production PHI) model:

- uses: neondatabase/create-branch-action@v5
  with:
    project_id: ${{ secrets.NEON_PROJECT_ID }}
    branch_name: pr-${{ github.event.number }}
    api_key: ${{ secrets.NEON_API_KEY }}

Outputs passed to subsequent jobs:

• Branch Postgres connection string (DATABASE_URL)
• Branch-scoped Better Auth config (JWKS URL registered against this branch via the Neon API)

Job 2 — Backend Deployment (Python API)

Needs: Job 1

Environment variables injected into Cloud Run:

The service deploys with --ingress=internal-and-cloud-load-balancing (no public URL) and is registered as a serverless NEG + host rule api-pr-<n>.pr.internal on the internal ALB — reachable only on the tailnet (see Tailnet Access). Its internal hostname is passed to Job 3.

Job 3 — Web App Deployment (Vite + TanStack server)

Needs: Job 1, Job 2

The web-app is a server, not a static bundle — it hosts Better Auth + Drizzle and connects to Neon at runtime. So it is built and deployed as a server container carrying both build-time (VITE_*) and runtime (DATABASE_URL / BETTER_AUTH_SECRET) config.

Build arguments (inlined at build time):

Runtime environment variables injected into Cloud Run:

Job 4 — PR Comment

Needs: Job 3

Posts (or updates) a sticky comment with the preview URLs:

🚀 Preview Environment Ready  (tailnet-only — connect via Tailscale)
- UI:       https://web-app-pr-42.pr.internal
- API:      https://api-pr-42.pr.internal
- Database: Neon branch `pr-42`

Teardown Workflow — pr-env-down.yml

Trigger: pull_request on types [closed] (fires for merged and unmerged PRs).

Cleanup runs in parallel:

Cleanup GCP

# Remove the tailnet host rules + serverless NEGs from the internal ALB first, then the services
gcloud compute url-maps remove-host-rule <internal-lb-url-map> --host=web-app-pr-${{ github.event.number }}.pr.internal --quiet || true
gcloud compute url-maps remove-host-rule <internal-lb-url-map> --host=api-pr-${{ github.event.number }}.pr.internal --quiet || true
gcloud run services delete api-pr-${{ github.event.number }} --region=$GCP_REGION --quiet
gcloud run services delete web-app-pr-${{ github.event.number }} --region=$GCP_REGION --quiet

Cleanup Neon

- uses: neondatabase/delete-branch-action@v3
  with:
    project_id: ${{ secrets.NEON_PROJECT_ID }}
    branch: pr-${{ github.event.number }}
    api_key: ${{ secrets.NEON_API_KEY }}

Deleting the branch also disposes of its isolated auth data and any per-PR secrets.

Application Code Requirements

Web app (Vite + TanStack server)

1. Dynamic API URLs. All client API calls use VITE_API_URL — never hardcode localhost or a staging domain.
2. Server container, not a static dist/. The web-app hosts Better Auth + Drizzle, so it ships as a server container that reads DATABASE_URL + BETTER_AUTH_SECRET at runtime (from the PR's Neon branch + the minted per-PR secret). VITE_* values are baked in as build args; server secrets stay runtime env vars.

Python (Backend)

1. Dynamic CORS. The CORS middleware accepts requests from the ephemeral web-app-pr-*.run.app domains via a strict, anchored regex:

   allow_origin_regex=r"^https://web-app-pr-\d+\.pr\.internal$"

   [!WARNING] Never use a wildcard (*) for CORS — sessions and tokens must be protected even in PR environments.

2. Database migrations. Run migrations (Drizzle Kit, from the top-level schema/ dir) against the Neon PR branch on startup or as a distinct pre-deploy step; the schema-diff-action comment is the human review gate for schema + RLS changes.

Workflow File Organization

.github/workflows/
├── ci.yml                # PR quality gate (lint, test, type-check, build) — targets dev / release/*
├── deploy-api.yml        # Cloud Run deployment — backend/api (FastAPI), filter backend/api/**
├── deploy-worker.yml     # Cloud Run deployment — backend/worker (Restate handlers), filter backend/worker/**
├── deploy-web-app.yml    # Cloud Run deployment — ui/web-app (Vite), filter ui/web-app/**
├── deploy-marketing.yml  # Cloud Run deployment — ui/marketing (Next.js), filter ui/marketing/**
├── pr-env-up.yml         # Ephemeral PR environment spin-up
├── pr-env-down.yml       # Ephemeral PR environment teardown
└── dbt.yml               # Nightly Neon → BigQuery dbt sync

See also:

• CI/CD — Production deployment workflows
• Environment Variables — Master env var reference
• Infrastructure — Pulumi IaC for production GCP resources

Secure PHI GitOps — PHI / non-PHI Separation via Neon Branching

This is the branching + environment architecture that lets us keep developer velocity with database branching while enforcing strict HIPAA containment. It rests on three pillars: two isolated Neon projects (non-PHI vs PHI) with matching object-storage buckets (§6), an isolated compute boundary for the rare PHI-touching work, and automated Git ↔ Neon synchronization.

1. Neon Project Configuration

Two separate Neon projects — separate projects, not two branches of one, so the PHI boundary is a hard connection-level boundary, not a policy convention.

Project A — Staging (non-PHI)

• Purpose: durable sandbox for everyday development.
• Data profile: sanitized, masked, or synthetic data only. Zero PHI.
• Access: open to all developers from standard local IDEs (localhost).
• Branching: CI creates an ephemeral Neon branch off this project's primary branch for every feature/* PR. This is the existing PR Preview Environment mechanism, now explicitly rooted in the non-PHI project.

Project B — Production (PHI)

• Purpose: live application data and pre-release verification against real data shapes.
• Data profile: real PHI.
• Access: highly restricted. Database connections permitted only from:
  1. Live GCP production application instances.
  2. Authorized CI/CD runner identities (Workload Identity Federation; Neon IP Allow).
  3. Isolated Coder workspaces running inside the secure GCP subnet.
• Branching: CI creates ephemeral Neon branches off this project's primary branch only for release/* and hotfix/* PRs.

2. Compute & Network Boundary (GCP + Coder)

To prevent local PHI contamination during release troubleshooting:

• Deploy Coder into a dedicated, private GCP subnet, reachable only over the company tailnet (Tailscale) — the same tailnet that gates previews / staging (see Infrastructure › Tailnet Access).
• Configure VPC firewall rules so that only this subnet may reach the Neon Production project (Neon IP Allow / private networking). Nothing outside the subnet can open a connection to Project B.
• The Coder workspace image enforces an approved, in-boundary coding assistant (e.g., Gemini Code Assist; the specific coding-agent choice is still WIP, tracked under the AI-Native Dev Stack effort — not blocked on it, since any approved in-boundary tool satisfies the boundary) — arbitrary local agents are not used against PHI.
• Disable clipboard sharing and local file download/upload from the Coder workspace via policy.
• All PHI-adjacent compute stays inside the GCP BAA boundary; PHI never lands on an endpoint device.

3. GitHub Branch Strategy & Protection

Two long-lived trunks — main (production) and dev (staging / integration) — plus short-lived feature/*, release/*, and hotfix/* branches. Configure protection via Settings → Branches.

main (Production)

• Require a pull request before merging: on.
• Require approvals: 1–2, and Require review from Code Owners: ON — this is the gate that routes schema / RLS changes to the CTO (see §4).
• Restrict who can push/merge: limited to the Release Managers / Lead Engineers team (this — not CODEOWNERS — is how "only release managers land main" is enforced).
• Require status checks: Integration Tests, E2E Tests, Migration Checks.
• Do not allow bypassing the above settings: on.

dev (Staging / Integration)

• Require a pull request before merging: on.
• Require approvals: 1 (peer review / quality gate). Require review from Code Owners: OFF — so schema changes flow freely into dev without the CTO gate.
• Require status checks: Unit Tests, Staging DB Migration Checks.

release/* (Release Candidates)

• Require a pull request before merging: on.
• Require status checks: the full suite run against a Neon Production fork (real-data-shape verification).

hotfix/* (Production Hotfixes)

• Require a pull request before merging: on.
• Require status checks: the same full release suite, run against a Neon Production branch — a hotfix/* branches off Production and targets main, mirroring release/*. It exists to patch prod urgently without waiting on the normal release train.
• After merge to main, the automated backmerge (main → dev) carries the fix downstream (Workflow C).

4. CODEOWNERS Configuration

.github/CODEOWNERS enforces the quality gate by file path. Adapted to this monorepo — schema/migrations are Drizzle Kit (single migration history; the Python side reflects — no Prisma, no Supabase, no Alembic), so the paths differ from the common boilerplate:

# App code — peer + lead review
/ui/                     @your-org/frontend       @your-org/lead-engineers
/backend/                @your-org/backend         @your-org/lead-engineers
 
# CI/CD + infrastructure — DevOps review
/.github/workflows/      @your-org/devops
/infra/                  @your-org/devops
 
# Schema, migrations + RLS policies — the top-level schema/ dir (Drizzle Kit owns
# the single migration history). Owner = the CTO for now (swap for a
# @your-org/database-admins team as the org grows).
/schema/                 @your-org/cto
 
# Analytics models (Neon → BigQuery)
/dbt/                    @your-org/data

5. CI/CD Pipeline Workflows (GitHub Actions)

Four workflows orchestrate Neon and GitHub. GCP auth is Workload Identity Federation throughout (no long-lived keys — see PR Environments).

Workflow A — Feature Development (feature/* → dev)

1. Trigger: PR opened against dev.
2. Create a branch on the Neon Staging project named pr-<number> (neondatabase/create-branch-action).
3. Run Drizzle Kit migrations against the Staging branch; post the neondatabase/schema-diff-action comment as the review gate.
4. Run application tests.
5. Teardown: on PR merge/close, delete the Neon Staging branch.
6. Post-merge: run migrations on Staging main to update the baseline schema future forks branch from.

Workflow B — Release / Hotfix Verification (release/* / hotfix/* → main)

1. Trigger: PR opened against main (branch matches release/* or hotfix/*).
2. Create a branch on the Neon Production project named release-<version> (or hotfix-<id>).
3. Spin up secure CI compute (in-boundary runner) and connect to the Neon Prod branch.
4. Immediately execute pending Drizzle migrations.
5. Run integration / E2E tests against the migrated real-data-shape schema.
6. Intervention (if needed): a developer opens a Coder workspace in the secure subnet, connects to the Neon Prod branch to debug, and commits fixes directly to the release/* branch.
7. Teardown: on merge to main, delete the Neon Prod branch.

Workflow C — Automated Backmerge (main → dev)

1. Trigger: push / merge on main.
2. Attempt a fast-forward or clean merge of main into dev.
3. On success: push the updated dev.
4. On conflict: create sync-main-to-dev-<timestamp>, open a PR into dev, and assign the release PR's author to resolve.

Workflow D — Staging Data Refresh (Cron)

1. Trigger: weekly schedule (e.g. Sunday 02:00).
2. Take a logical dump of Neon Production — inside the boundary.
3. Pipe the dump through a HIPAA-capable masking / synthetic-data tool (e.g., Neosync — OSS, anonymization + synthetic; alternatives: Tonic, postgresql-anonymizer, Snaplet seed).
4. Restore the masked dump into the Neon Staging project, giving developers realistic data volumes and shapes with zero PHI.
5. Refresh the Staging blob base too (§6): regenerate synthetic blob fixtures into the Staging bucket for every object the masked dataset references, so masked rows resolve to masked blobs — no dangling keys, no PHI. Same in-boundary masking pass; only masked/synthetic bytes ever reach Staging.

6. Object Storage (GCS) — same boundary, overlay reads

A Neon branch is only half a preview: its rows reference blobs (clinical-note attachments, uploaded documents) that must resolve to a matching, isolated store. So blobs follow the same PHI split as the database — per-class buckets plus an overlay (copy-on-write) read so a branch sees its own writes layered over a read-only base, and never mutates the base.

Buckets

Each preview branch writes under its own prefix: …-preview/<branch>/<key>.

Overlay semantics (copy-on-write)

• Read key: try the preview bucket at <branch>/<key>; on miss, read the base bucket at <key>. The base is read-only — prod/staging blobs are never touched by a preview.
• Write key: always the preview bucket at <branch>/<key>. New uploads and overwrites land in the branch's own layer.
• Delete key: removes only the preview copy. (If a preview must hide a base object, write a zero-byte tombstone under <branch>/<key> that the read path treats as "not found" — rarely needed.)
• Teardown: delete the <branch>/ prefix on PR close; the short-TTL lifecycle rule is the backstop.

IAM is the write-barrier

Grant each preview identity objectViewer on its base bucket (read-only) and objectAdmin on its own preview bucket only; the non-PHI preview SA gets nothing on …-uploads-prod. So "the service can't edit prod" is not a code convention — a stray write to the base is IAM-denied. (Same WIF / least-privilege model as §2 and Secret Management.)

Store logical keys, not gs:// URIs

Persist a logical object key (e.g. tenant/<id>/note/<id>) in Postgres — never an absolute gs://bucket/… URI. The storage layer composes bucket + branch prefix from environment config at call time, so the same branched DB row resolves to the prod bucket in prod, the phi-preview overlay in a release branch, and the nonphi-preview overlay in a feature branch — for free, no row rewriting.

Transparency lives in the adapter, not in GCS

GCS has no native overlay / read-through / union-bucket setting — no bucket config says "fall back to bucket A on a miss" (Anywhere Cache caches one bucket; versioning/soft-delete are within a bucket; a fronting proxy is just infra you'd write). So the overlay lives in a thin BlobStorageService every consumer goes through:

get(key)               # overlay read: preview/<branch>/key → base/key
put(key, data)         # always preview/<branch>/key
delete(key)            # preview copy only
signed_read_url(key)   # resolve which bucket holds it, then sign THAT object
signed_write_url(key)  # always sign the preview object

Consumers pass logical keys only and never learn which bucket answered. The environment class (prod | phi-preview | nonphi-preview), base bucket, write bucket, and branch prefix are injected as config — the same place the Neon branch DATABASE_URL is injected. In prod, write-bucket == base-bucket and there is no overlay, so one class covers every environment. Because a signed URL points at a specific object in a specific bucket, a read URL is a server-side exists-check-then-sign — you can't hand a client a fallback URL.

How it all fits

See also:

• PR Preview Environments — the ephemeral per-PR branch + Cloud Run mechanics this builds on
• HIPAA Compliance — the PHI boundary + PHI-free-service rules
• CI/CD · Secret Management · Backend (Drizzle / RLS) · Developer Tooling

Developer Tooling

Every Foundation project ships with a fully reproducible development environment. No manual tool installation after the initial workspace build.

Toolchain Overview

Devbox — devbox.json

Devbox provides a reproducible Nix-backed shell with all system-level tools:

Packages (Nix)

git, curl, wget, jq, yq, gnumake, direnv, lefthook, uv, nodejs_22, gh, process-compose, docker, docker-compose, ripgrep, fd, bat, eza, zsh, pulumi-bin, google-cloud-sdk, caddy, netcat-openbsd, iputils, dnsutils, traceroute, openssl, unzip, htop, tree, file, vim

act is not in packages — it is installed at init_hook time via the official curl installer so the binary survives in /usr/local/bin across devbox shell restarts.

Environment Variables

Dev-time defaults for DATABASE_URL (points at the developer's own Neon dev branch by default), API_URL, OTEL_EXPORTER_OTLP_ENDPOINT (the local otel-collector process — see Observability), and DEVBOX_COREPACK_ENABLED (enables pnpm/yarn via Corepack).

Shell Init Hook

Activates direnv for bash (guarded for non-bash shells), sources NVM, and installs act via the official curl installer if not present:

[ -n "${BASH_VERSION:-}" ] && command -v direnv >/dev/null 2>&1 && eval "$(direnv hook bash)" 2>/dev/null || true
export NVM_DIR="${HOME}/.nvm"
[ -s "${NVM_DIR}/nvm.sh" ] && . "${NVM_DIR}/nvm.sh" --no-use || true
 
# act installed via curl installer so it persists at /usr/local/bin/act
if ! command -v act >/dev/null 2>&1; then
  curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b /usr/local/bin
fi

Scripts

The devbox.lock file must be committed to ensure identical Nix store paths for all developers.

{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.13.7/.schema/devbox.schema.json",
  "packages": [
    "git@latest",
    "curl@latest",
    "wget@latest",
    "jq@latest",
    "yq@latest",
    "gnumake@latest",
    "direnv@latest",
    "lefthook@latest",
    "uv@latest",
    "nodejs_22@latest",
    "gh@latest",
    "process-compose@latest",
    "docker@latest",
    "docker-compose@latest",
    "ripgrep@latest",
    "fd@latest",
    "bat@latest",
    "eza@latest",
    "zsh@latest",
    "pulumi-bin@latest",
    "google-cloud-sdk@latest",
    "caddy@latest",
    "netcat-openbsd@latest",
    "iputils@latest",
    "dnsutils@latest",
    "traceroute@latest",
    "openssl@latest",
    "unzip@latest",
    "htop@latest",
    "tree@latest",
    "file@latest",
    "vim@latest"
  ],
  "env": {
    "DATABASE_URL": "postgresql://<user>:<pass>@<your-neon-dev-branch>.neon.tech/app?sslmode=require",
    "API_URL": "http://localhost:8000",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
    "DEVBOX_COREPACK_ENABLED": "true"
  },
  "shell": {
    "init_hook": [
      "# Activate direnv integration only for bash shells.",
      "# devbox run invokes init_hook via /usr/bin/sh, and direnv has no 'sh' hook target.",
      "[ -n \"${BASH_VERSION:-}\" ] && command -v direnv >/dev/null 2>&1 && eval \"$(direnv hook bash)\" 2>/dev/null || true",
      "",
      "# Source NVM so that node/pnpm from nvm is available in devbox shells",
      "# || true is required: under set -e (prepended by devbox to hooks.sh), a",
      "# failing [ -s ] && . exits the script if NVM isn't installed yet.",
      "export NVM_DIR=\"${HOME}/.nvm\"",
      "[ -s \"${NVM_DIR}/nvm.sh\" ] && . \"${NVM_DIR}/nvm.sh\" --no-use || true",
      "",
      "# Install act (local GitHub Actions runner) via the official installer if not present.",
      "# act is not in nixpkgs because the Nix build sandbox conflicts with Docker-in-Docker;",
      "# the curl installer places the binary at /usr/local/bin/act which survives devbox shell restarts.",
      "if ! command -v act >/dev/null 2>&1; then",
      "  echo '==> Installing act (local GitHub Actions runner)...'",
      "  curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b /usr/local/bin >/dev/null 2>&1 && echo '  → act installed.' || echo '  → Warning: act install failed.'",
      "fi"
    ],
    "scripts": {
      "setup": [
        "#!/usr/bin/env bash",
        "set -eu",
        "",
        "# ── Project dependencies & first-time setup ──────────────────────────────",
        "echo '==> Running project setup (deps, env files, git hooks)...'",
        "bash scripts/setup.sh",
        "",
        "# ── Oh My Zsh ────────────────────────────────────────────────────────────",
        "echo '==> Configuring Oh My Zsh...'",
        "",
        "if [ ! -d \"${HOME}/.oh-my-zsh\" ]; then",
        "  echo '  → Installing Oh My Zsh...'",
        "  if ! RUNZSH=no CHSH=no sh -c \"$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)\"; then",
        "    echo '  → Warning: Oh My Zsh install failed; continuing setup'",
        "  fi",
        "fi",
        "",
        "ZSH_CUSTOM=\"${ZSH_CUSTOM:-${HOME}/.oh-my-zsh/custom}\"",
        "",
        "if [ ! -d \"${ZSH_CUSTOM}/plugins/zsh-autosuggestions\" ]; then",
        "  echo '  → Installing zsh-autosuggestions...'",
        "  git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions \"${ZSH_CUSTOM}/plugins/zsh-autosuggestions\"",
        "fi",
        "",
        "if [ ! -d \"${ZSH_CUSTOM}/plugins/zsh-syntax-highlighting\" ]; then",
        "  echo '  → Installing zsh-syntax-highlighting...'",
        "  git clone --depth=1 https://github.com/zsh-users/zsh-syntax-highlighting \"${ZSH_CUSTOM}/plugins/zsh-syntax-highlighting\"",
        "fi",
        "",
        "if [ ! -d \"${ZSH_CUSTOM}/plugins/pnpm\" ]; then",
        "  echo '  → Installing oh-my-zsh pnpm plugin...'",
        "  git clone --depth=1 https://github.com/ntnyq/omz-plugin-pnpm \"${ZSH_CUSTOM}/plugins/pnpm\"",
        "fi",
        "",
        "# ── Configure .zshrc ─────────────────────────────────────────────────────",
        "ZSHRC=\"${HOME}/.zshrc\"",
        "[ ! -f \"${ZSHRC}\" ] && touch \"${ZSHRC}\"",
        "",
        "if grep -q '^ZSH_THEME=' \"${ZSHRC}\" 2>/dev/null; then",
        "  sed -i 's/^ZSH_THEME=.*/ZSH_THEME=\"agnoster\"/' \"${ZSHRC}\"",
        "else",
        "  printf 'ZSH_THEME=\"agnoster\"\\n' >> \"${ZSHRC}\"",
        "fi",
        "",
        "if grep -q '^plugins=' \"${ZSHRC}\" 2>/dev/null; then",
        "  sed -i 's/^plugins=.*/plugins=(git docker python node pnpm history direnv zsh-autosuggestions zsh-syntax-highlighting)/' \"${ZSHRC}\"",
        "else",
        "  printf 'plugins=(git docker python node pnpm history direnv zsh-autosuggestions zsh-syntax-highlighting)\\n' >> \"${ZSHRC}\"",
        "fi",
        "",
        "if ! grep -q '# foundation-devbox-zsh' \"${ZSHRC}\" 2>/dev/null; then",
        "  printf '\\n# foundation-devbox-zsh\\n' >> \"${ZSHRC}\"",
        "  printf 'export NVM_DIR=\"$HOME/.nvm\"\\n' >> \"${ZSHRC}\"",
        "  printf '[ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"\\n' >> \"${ZSHRC}\"",
        "  printf 'ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE=\"fg=60\"\\n' >> \"${ZSHRC}\"",
        "  printf 'ZSH_AUTOSUGGEST_STRATEGY=(history completion)\\n' >> \"${ZSHRC}\"",
        "fi",
        "",
        "if ! grep -q '# foundation-direnv-zsh-hook' \"${ZSHRC}\" 2>/dev/null; then",
        "  printf '\\n# foundation-direnv-zsh-hook\\n' >> \"${ZSHRC}\"",
        "  printf 'command -v direnv >/dev/null 2>&1 && eval \"$(direnv hook zsh)\"\\n' >> \"${ZSHRC}\"",
        "fi",
        "",
        "if ! grep -q '# foundation-tmux' \"${ZSHRC}\" 2>/dev/null; then",
        "  printf '\\n# foundation-tmux\\n' >> \"${ZSHRC}\"",
        "  printf '# Use repo .tmux.conf when TMUX_CONF is set (populated by .envrc).\\n' >> \"${ZSHRC}\"",
        "  printf 'if [ -n \"${TMUX_CONF:-}\" ]; then\\n' >> \"${ZSHRC}\"",
        "  printf \"  alias tmux='tmux -f \\\"\\$TMUX_CONF\\\"'\\n\" >> \"${ZSHRC}\"",
        "  printf 'fi\\n' >> \"${ZSHRC}\"",
        "fi",
        "",
        "echo '==> Zsh configuration complete!'"
      ],
      "hooks:install": "lefthook install",
      "dev": "process-compose up",
      "dev:app": "cd ui/web-app && pnpm dev",
      "dev:marketing": "cd ui/marketing && pnpm dev",
      "dev:api": "cd backend/api && uv run uvicorn --app-dir src main:app --reload --port 8000",
      "dev:db": "docker compose -f docker-compose.db.yml up",
      "test:api": "cd backend/api && uv run pytest",
      "test:app": "cd ui/web-app && pnpm test",
      "lint:app": "cd ui/web-app && pnpm dlx @biomejs/biome check ./src",
      "format:app": "cd ui/web-app && pnpm dlx @biomejs/biome format --write ./src",
      "lint:api": "cd backend/api && uv run ruff check src/",
      "ci:local": "act pull_request --container-architecture linux/amd64 -W .github/workflows/ci.yml"
    }
  }
}

📥 Download devbox.json template

Local Database — Neon dev branch (default)

Local development runs against a per-developer Neon dev branch, not a local database. Each developer gets a copy-on-write branch of the shared dev database, so schema and seed data match production shape without anyone running a Postgres server.

• DATABASE_URL in devbox.json (and the git-ignored .env) points at the developer's own Neon branch. Hydrate secrets from Pulumi ESC — see Secret Management.
• Schema, migrations, and RLS live in the top-level schema/ package, owned by Drizzle Kit; apply them to your branch with drizzle-kit push / migrate. The Python side reflects the schema — no Alembic. See Libraries.
• Better Auth stores its tables in Neon, so your dev branch carries an isolated auth environment for free.

direnv — .envrc

eval "$(devbox generate direnv --print-envrc)"

This auto-activates the Devbox shell whenever a developer cds into the project directory. Committed to the repo.

# Load devbox environment (generates shell env from devbox.json)
eval "$(devbox generate direnv --print-envrc)"
 
# ── Auto-bootstrap Python venv & deps for backend/api ────────────────────────
if [ ! -d backend/api/.venv ]; then
  echo "direnv: creating backend/api/.venv ..."
  (cd backend/api && uv venv --quiet)
fi
if [ -f backend/api/uv.lock ] && [ backend/api/uv.lock -nt backend/api/.venv/.direnv-synced ] \
   || [ ! -f backend/api/.venv/.direnv-synced ]; then
  echo "direnv: running uv sync in backend/api/ ..."
  (cd backend/api && uv sync --all-extras --quiet) && touch backend/api/.venv/.direnv-synced
fi
 
# ── Auto-bootstrap Node deps for ui/web-app ────────────────────────────────────
if [ -f ui/web-app/package.json ] && [ ! -d ui/web-app/node_modules ]; then
  echo "direnv: running pnpm install in ui/web-app/ ..."
  (cd ui/web-app && pnpm install --no-fund --reporter=silent)
fi
 
# ── Activate Python venv so pytest / CLI tools are on PATH ────────────────────
export VIRTUAL_ENV="$PWD/backend/api/.venv"
PATH_add "$VIRTUAL_ENV/bin"
 
# ── Add ui/web-app/node_modules/.bin so vitest / biome are on PATH ─────────────
PATH_add ui/web-app/node_modules/.bin
 
# ── Project-level environment variables ──────────────────────────────────────
export API_URL="${API_URL:-http://localhost:8000}"

📥 Download .envrc template (rename to .envrc after download)

process-compose — process-compose.yml

Orchestrates all development services:

Each process declares dependency ordering and readiness probes (HTTP/TCP health checks) so services start in the correct order.

devbox run dev or process-compose up brings up the entire local stack in one command.

📥 Download process-compose.yml template

Caddy — Local Reverse Proxy

Caddy runs as a process-compose service and acts as the local TLS-terminating reverse proxy, routing traffic across all dev services behind a single HTTPS endpoint. It uses tls internal to auto-generate certificates via the Caddy local CA.

Why default_bind tcp4/0.0.0.0?

The global default_bind tcp4/0.0.0.0 directive is required when running inside a Coder workspace. Coder's port-scanning infrastructure only discovers TCP4 sockets; without this directive Caddy binds to the dual-stack [::] address, which is invisible to Coder's port-forward scanner and prevents Coder Desktop from automatically detecting and forwarding the proxy ports.

Caddyfile

# Local dev reverse-proxy with auto-generated internal TLS certificates.
# Requires DNS: local.example.com & *.local.example.com → 127.0.0.1
# Also supports Coder Desktop via $CODER_WORKSPACE_NAME (e.g. myapp-local):
#   {CODER_WORKSPACE_NAME}.coder       → landing
#   app.{CODER_WORKSPACE_NAME}.coder   → app + API
{
	admin localhost:2020
	http_port 8080
	https_port 4443
 
	# REQUIRED for Coder Desktop port scanning: Coder's port-scanner only detects
	# TCP4 sockets. Without this, Caddy binds to dual-stack [::] and the proxy
	# ports are invisible to Coder's port-forward infrastructure.
	default_bind tcp4/0.0.0.0
}
 
# Landing page  –  local.example.com → Next.js marketing dev server
local.example.com {
	tls internal
	reverse_proxy localhost:3000 {
		header_up Host localhost:3000
	}
}
 
# App + API  –  app.local.example.com
app.local.example.com {
	tls internal
 
	# /api/* → FastAPI backend (path forwarded as-is)
	handle /api/* {
		reverse_proxy localhost:8000
	}
 
	# Everything else → Vite + TanStack app
	handle {
		reverse_proxy localhost:5173
	}
}
 
# Coder Desktop – landing  ({$CODER_WORKSPACE_NAME}.coder)
# Falls back to a no-op placeholder host when CODER_WORKSPACE_NAME is unset.
{$CODER_WORKSPACE_NAME:coder-workspace-placeholder}.coder {
	tls internal
	reverse_proxy localhost:3000 {
		header_up Host localhost:3000
	}
}
 
# Coder Desktop – app + API  (app.{$CODER_WORKSPACE_NAME}.coder)
app.{$CODER_WORKSPACE_NAME:coder-workspace-placeholder}.coder {
	tls internal
 
	# /api/* → FastAPI backend (path forwarded as-is)
	handle /api/* {
		reverse_proxy localhost:8000
	}
 
	# Everything else → Vite + TanStack app
	handle {
		reverse_proxy localhost:5173
	}
}
 
# Coder web port-forwarding catch-all ─────────────────────────────────────────
# Coder's browser-based port-forwarding (https://<port>--<workspace>.coder.domain/)
# terminates TLS at the Coder edge and forwards plain HTTP to the workspace port.
# Named site blocks above won't match the Coder-generated Host header, so this
# http:// catch-all handles those requests on port 8080 (the http_port).
# Use URL:  https://8080--main--<workspace>--<user>.coder.<domain>/
http:// {
	handle /api/* {
		reverse_proxy localhost:8000
	}
	handle {
		reverse_proxy localhost:5173
	}
}

📥 Download Caddyfile template

Lefthook — lefthook.yml

Pre-commit (parallel)

Pre-push

📥 Download lefthook.yml template

Biome — biome.json

Biome replaces both ESLint and Prettier with a single, faster tool.

📥 Download biome.json template

Ruff — pyproject.toml

See Backend for the full Ruff configuration.

Ruff replaces flake8, isort, black, and bandit with a single tool. Rule sets: E, F, I, UP, B, S.

Dev Container & Coder Workspace

.devcontainer/devcontainer.json

VS Code extensions pre-installed: Devbox, direnv, Ruff, Python/Pylance, Biome, Tailwind CSS, Copilot.

{
  "name": "Foundation Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
  // Run all devcontainer lifecycle commands as root, matching the user that
  // envbuilder / Coder run as inside the container.
  "remoteUser": "root",
  // NOTE: docker-in-docker is intentionally omitted.
  // envbuilder does not support the `privileged` or `init` feature properties
  // that docker-in-docker requires. Docker CE is installed by on-create.sh to
  // provide the daemon; Docker CLI + Compose may come from Devbox or Docker CE.
  // In Coder workspaces the Docker socket (/var/run/docker.sock) should be
  // mounted from the host via the workspace template.
  // Installs nix (single-user, sandbox disabled for Docker), devbox, and all
  // project packages. Nix installation is required; failures will stop the build.
  "onCreateCommand": "bash .devcontainer/on-create.sh",
  // postCreateCommand runs devbox run setup which installs pnpm/Python deps.
  // Output is tee'd to /tmp/postCreate.log; on failure the log is cat'd so it
  // appears in docker logs / envbuilder output for easy debugging.
  "postCreateCommand": "bash -c 'devbox run setup 2>&1 | tee /tmp/postCreate.log; exit ${PIPESTATUS[0]}'",
  // postStartCommand runs every time the container starts (including restarts).
  // It runs the post-start script, which restarts nix-daemon and waits for
  // Docker. Docker must be provided by a host-mounted socket.
  "postStartCommand": "bash -lc 'bash .devcontainer/post-start.sh'",
  "remoteEnv": {
    "DOCKER_BUILDKIT": "1",
    "SHELL": "/bin/zsh"
  },
  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.defaultProfile.linux": "zsh",
        "terminal.integrated.fontFamily": "'MesloLGS NF', 'Hack Nerd Font Mono', 'Courier New', monospace",
        "terminal.integrated.profiles.linux": {
          "zsh": { "path": "/bin/zsh", "args": ["-l"] },
          "bash": { "path": "/bin/bash", "args": ["-l"] }
        },
        "editor.formatOnSave": true,
        "python.defaultInterpreterPath": "${workspaceFolder}/backend/api/.venv/bin/python",
        "[python]": {
          "editor.defaultFormatter": "charliermarsh.ruff"
        },
        "[typescript]": {
          "editor.defaultFormatter": "biomejs.biome"
        },
        "[typescriptreact]": {
          "editor.defaultFormatter": "biomejs.biome"
        },
        "[javascript]": {
          "editor.defaultFormatter": "biomejs.biome"
        },
        "[javascriptreact]": {
          "editor.defaultFormatter": "biomejs.biome"
        },
        "[json]": {
          "editor.defaultFormatter": "biomejs.biome"
        }
      },
      "extensions": [
        "jetify-com.devbox",
        "mkhl.direnv",
        "charliermarsh.ruff",
        "ms-python.python",
        "ms-python.vscode-pylance",
        "biomejs.biome",
        "bradlc.vscode-tailwindcss",
        "GitHub.copilot",
        "GitHub.copilot-chat",
        "ms-vscode.makefile-tools",
        "redhat.vscode-yaml",
        "timonwong.shellcheck"
      ]
    },
    "codespaces": {
      "openFiles": ["README.md"]
    }
  },
  "forwardPorts": [3000, 5173, 8000, 5432, 8080, 4443],
  "portsAttributes": {
    "3000": { "label": "Next.js Marketing", "onAutoForward": "notify" },
    "5173": { "label": "Vite + TanStack App", "onAutoForward": "notify" },
    "8000": { "label": "FastAPI", "onAutoForward": "notify" },
    "5432": {
      "label": "Local Postgres (offline fallback)",
      "onAutoForward": "silent",
      "requireLocalPort": true
    },
    "8080": {
      "label": "Caddy HTTP",
      "onAutoForward": "silent"
    },
    "4443": {
      "label": "Caddy HTTPS",
      "onAutoForward": "silent"
    }
  }
}

📥 Download devcontainer.json template

.devcontainer/on-create.sh

Idempotent bootstrap script:

1. Ensure Docker is installed — uses get.docker.com convenience installer (Codespaces-aware: skips install if already present, warns without failing if daemon unreachable)
2. Initialize git submodules (non-fatal if credentials unavailable)
3. Install zsh if absent
4. Install tmux via apt (host-OS integration; not from Nix)
5. Configure Nix: sandbox = false, filter-syscalls = false (heredoc append, idempotent)
6. Install Nix (Determinate Systems: --init none, --no-confirm)
7. Start Nix daemon (sleep 3 for socket readiness)
8. Install Devbox
9. devbox install
10. Append Nix/Devbox PATH to ~/.bashrc + ~/.zshrc

#!/usr/bin/env bash
# .devcontainer/on-create.sh
# Runs as the devcontainer user (root) during onCreateCommand.
# Idempotent — safe to re-run.
set -euo pipefail
 
IS_CODESPACES="${CODESPACES:-}"
 
# ── 0. Ensure Docker is available early for lifecycle commands ───────────────
# Codespaces already provides Docker; avoid trying to start nested dockerd.
if ! command -v docker &>/dev/null; then
  if [ -n "$IS_CODESPACES" ]; then
    echo "WARNING: docker CLI is missing in Codespaces; skipping Docker bootstrap"
  else
    echo "→ Installing Docker CE..."
    curl -fsSL https://get.docker.com | sh
  fi
fi
 
if ! docker info &>/dev/null 2>&1; then
  if [ -n "$IS_CODESPACES" ]; then
    echo "WARNING: Docker daemon not reachable in Codespaces during on-create; continuing"
  elif command -v dockerd &>/dev/null; then
    echo "→ Starting dockerd..."
    dockerd \
      --host=unix:///var/run/docker.sock \
      --data-root=/var/lib/docker \
      >/tmp/dockerd.log 2>&1 &
 
    for i in $(seq 1 30); do
      docker info &>/dev/null 2>&1 && break
      sleep 1
    done
 
    if docker info &>/dev/null 2>&1; then
      echo "→ Docker daemon ready"
    else
      echo "WARNING: dockerd did not become ready within 30s (see /tmp/dockerd.log)"
    fi
  fi
fi
 
# ── 1. Initialize git submodules ──────────────────────────────────────────────
# NOTE: This runs before the Coder agent starts, so git credential helpers are
# not yet available. Private submodules requiring HTTPS auth may fail here.
# We make this non-fatal; the postStartCommand (or manual re-run) can complete
# it once the agent is running and git auth forwarding is active.
echo "→ Updating git submodules..."
git -C "$(dirname "$0")/.." submodule update --init --recursive \
  || echo "WARNING: submodule update failed (git credentials not yet available — re-run on-create.sh once the workspace is ready)"
 
# ── 2. Ensure zsh is installed ────────────────────────────────────────────────
if ! command -v zsh &>/dev/null; then
  echo "→ Installing zsh..."
  apt-get update -qq && apt-get install -y zsh
fi
 
# ── 2b. Ensure tmux is installed (apt, not nix, for host-OS integration) ─────
if ! command -v tmux &>/dev/null; then
  echo "→ Installing tmux..."
  apt-get update -qq && apt-get install -y tmux
fi
 
# ── 3. Configure nix to work without sandboxing ──────────────────────────────
# Most Docker environments (even privileged) can't run the nix build sandbox
# because they lack user-namespace support. Disabling sandbox + syscall filter
# allows nix/devbox to build and fetch packages normally.
mkdir -p /etc/nix
if [ ! -f /etc/nix/nix.conf ] || ! grep -q 'sandbox = false' /etc/nix/nix.conf; then
  cat >> /etc/nix/nix.conf <<'EOF'
sandbox = false
filter-syscalls = false
EOF
fi
 
# ── 4. Install nix (single-user, no daemon) if needed ────────────────────────
# The Determinate Systems installer handles Docker containers reliably.
if ! command -v nix &>/dev/null; then
  echo "→ Installing nix..."
  curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix \
    | sh -s -- install linux \
        --init none \
        --no-confirm \
        --extra-conf "sandbox = false" \
        --extra-conf "filter-syscalls = false"
fi
 
# Source the nix profile for the remainder of this script
if [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
  # shellcheck disable=SC1091
  . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
fi
 
# ── 5. Start the nix daemon ──────────────────────────────────────────────────
# The Determinate Systems installer does not start the daemon automatically
# (--init none). We start it here for this shell, and rely on postStartCommand
# in devcontainer.json to restart it on subsequent workspace restarts.
/nix/var/nix/profiles/default/bin/nix-daemon --daemon &>/tmp/nix-daemon.log &
NIX_DAEMON_PID=$!
echo "→ nix-daemon started (pid $NIX_DAEMON_PID)"
sleep 3  # wait for the daemon socket to be ready
 
# ── 6. Install devbox if needed ───────────────────────────────────────────────
if ! command -v devbox &>/dev/null; then
  echo "→ Installing devbox..."
  # -f = non-interactive (skip the "Install to /usr/local/bin?" prompt)
  curl -fsSL https://get.jetify.com/devbox | bash -s -- -f
fi
 
# ── 7. Install project packages ───────────────────────────────────────────────
echo "→ Running devbox install..."
devbox install
 
# ── 8. Ensure shell init is set up for both bash and zsh ─────────────────────
add_to_shell() {
  local marker="$1" text="$2" file="$3"
  touch "$file"
  grep -qF "$marker" "$file" || printf '\n%s\n' "$text" >> "$file"
}
 
# Source nix in all shells (devbox adds its own wrapper around this too)
NIX_INIT='. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh 2>/dev/null || true'
add_to_shell 'nix-daemon.sh' "$NIX_INIT" "$HOME/.bashrc"
add_to_shell 'nix-daemon.sh' "$NIX_INIT" "$HOME/.zshrc"
 
# devbox adds itself to PATH via its own init; make sure devbox shim is reachable
DEVBOX_PATH_INIT='export PATH="${HOME}/.local/share/devbox/global/default/.devbox/nix/profile/default/bin:${PATH}"'
add_to_shell 'devbox' "$DEVBOX_PATH_INIT" "$HOME/.zshrc"
add_to_shell 'devbox' "$DEVBOX_PATH_INIT" "$HOME/.bashrc"
 
echo "✓ on-create complete"

📥 Download on-create.sh template

.devcontainer/post-start.sh

Runs on every container start (including restarts). Keeps idempotent tasks that don't survive a stop/start cycle:

1. Restart nix-daemon (no systemd in devcontainers; daemon doesn't survive stop/start)
2. Wait for the Docker daemon to be reachable (timeout configurable via DOCKER_WAIT_SECONDS) — Docker is needed for act and the optional local Postgres fallback

#!/usr/bin/env bash
# .devcontainer/post-start.sh
# Runs on every container start. Keeps lightweight tasks idempotent.
set -euo pipefail
 
# Derive repo root dynamically to work across different workspace layouts.
ROOT="${ROOT:-${WORKSPACE_FOLDER:-}}"
if [ -z "${ROOT}" ]; then
  # Assume this script lives in .devcontainer/ under the repo root.
  SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd -P)"
  ROOT="$(cd "${SCRIPT_DIR}/.." >/dev/null 2>&1 && pwd -P)"
fi
# Final fallback to the current directory if derivation failed for some reason.
ROOT="${ROOT:-${PWD}}"
 
LOG_FILE="/tmp/postStart.log"
DOCKER_WAIT_SECONDS="${DOCKER_WAIT_SECONDS:-60}"
 
log() {
  printf '%s\n' "$*" | tee -a "$LOG_FILE"
}
 
# Restart nix-daemon for this container session (no systemd in devcontainers).
if [ -x /nix/var/nix/profiles/default/bin/nix-daemon ]; then
  /nix/var/nix/profiles/default/bin/nix-daemon --daemon &>/tmp/nix-daemon.log &
  nix_daemon_pid=$!
  sleep 2
  if ! kill -0 "$nix_daemon_pid" 2>/dev/null; then
    log "post-start: failed to start nix-daemon; see /tmp/nix-daemon.log"
    exit 1
  fi
  # Verify daemon is responsive
  if command -v nix >/dev/null 2>&1; then
    for _ in {1..5}; do
      nix store ping >/dev/null 2>&1 && break
      sleep 1
    done
  fi
fi
 
# Wait for Docker to be reachable (needed by act and the optional local
# Postgres fallback). Local dev otherwise talks to a remote Neon dev branch,
# so there are no database images to pre-pull.
log "post-start: waiting for Docker daemon (timeout ${DOCKER_WAIT_SECONDS}s)..."
for _ in $(seq 1 "$DOCKER_WAIT_SECONDS"); do
  if docker info >/dev/null 2>&1; then
    log "post-start: Docker is ready"
    break
  fi
  sleep 1
done

📥 Download post-start.sh template

Root Dockerfile (Devbox image)

Based on jetpackio/devbox:latest. Pre-populates the Nix store and optimizes layer size:

FROM jetpackio/devbox:latest
COPY devbox.json devbox.lock ./
RUN devbox run -- echo "Installed Packages."
RUN nix-store --gc && nix-store --optimise
CMD ["devbox", "shell"]

act — Local CI Testing

act runs GitHub Actions workflows locally inside Docker containers, giving you fast CI feedback without a push to GitHub.

Why act?

Installation

act is included in the Devbox package list and is available automatically inside the Devbox shell. No separate install step is required.

Quick-start

# Run the full PR quality-gate workflow (pull_request trigger)
devbox run ci:local
 
# Equivalent manual invocation
act pull_request --container-architecture linux/amd64 -W .github/workflows/ci.yml
 
# Run a single job
act pull_request -j lint-js -W .github/workflows/ci.yml
 
# List all available jobs across all workflows
act --list

Supplying secrets

act does not have access to GitHub repository secrets. Create a local secrets file (never commit it):

# .secrets  ← add to .gitignore
DATABASE_URL=...
NEON_API_KEY=...
GCP_PROJECT_ID=...

Then pass it to act:

act pull_request --secret-file .secrets -W .github/workflows/ci.yml

Alternatively, supply individual secrets via --secret NAME=VALUE flags.

Runner image

act defaults to a minimal node:16-buster-slim image. For workflows that rely on tools pre-installed on GitHub-hosted runners (e.g., docker, python), choose a fuller image:

# Medium image (~500 MB) — recommended for the Foundation CI workflow
act pull_request -P ubuntu-latest=catthehacker/ubuntu:act-22.04 \
    --container-architecture linux/amd64 \
    -W .github/workflows/ci.yml

Persist your preferred image in .actrc at the repo root (add to .gitignore):

-P ubuntu-latest=catthehacker/ubuntu:act-22.04
--container-architecture linux/amd64

📥 Download .actrc template (rename to .actrc after download)

.actrc vs committed config

.actrc is personal — it contains machine-specific flags and should be added to .gitignore. Shared workflow-level defaults belong in the workflow YAML itself.

Dependency Convention

Never install tools globally on the host machine. The Devbox shell (auto-activated by direnv) is the single entry point for all tooling.

Code Organization — File Modularity

Multiple developers and AI agents work on separate issues in parallel. To minimise merge conflicts and keep pull requests small and reviewable, the architecture enforces a strict "one concern per file" rule across every layer.

General Principles

One component / function / model per file

Each React component, FastAPI router, Pydantic model, durable job, and utility function lives in its own file. Prefer many small files over a few large ones.

Barrel files for public API only

index.ts (TypeScript) and __init__.py (Python) files re-export the module's public surface. Implementation stays in dedicated files beside the index. This means two developers can add new items to the same module without touching the same lines.

Co-locate tests appropriately

• TypeScript/React: Test files live next to source (Button.tsx → Button.test.tsx).
• Python: Tests go in a tests/ directory with filenames matching source modules.

Flat over nested

Two directory levels deep is fine. Five hinders discoverability. Avoid unnecessary nesting.

Frontend — ui/web-app & ui/components

ui/web-app is the applications UI; ui/components is a shared component/library workspace (one of the ui/* shared packages — see Monorepo) that houses reusable presentational components consumed by ui/web-app. The same one-concern-per-file rule applies to both.

Re-export from barrel files:

// components/index.ts
export { Button } from "./Button";
export { Card } from "./Card";

Backend — backend/api (HTTP) & backend/worker (durable)

backend/api is the FastAPI HTTP service; backend/worker holds the Restate durable-execution handlers. The same one-concern-per-file rule applies to both.

Schema — schema/ (Drizzle)

Tables, RLS, and migrations live in the top-level schema/ package — the single source of truth that Drizzle Kit owns and the Python api reflects (no Alembic). One concern per file:

schema/
├── src/
│   ├── tables/          # one Drizzle table (concern) per file
│   │   ├── patient.ts
│   │   └── appointment.ts
│   └── rls.ts           # crudPolicy / authenticatedRole RLS definitions
├── drizzle.config.ts    # Drizzle Kit config
└── migrations/          # generated SQL — one migration history

Authorization policies — policies/ (Cerbos)

Cerbos policy-as-code lives in a version-controlled, top-level policies/ directory (Cerbos YAML), loaded by the self-hosted Cerbos PDP (see Backend). One resource per file:

Infrastructure & Config

• One Pulumi resource group per file in infra/ (e.g., gcp.ts, neon.ts, cloudflare.ts).
• One dbt model per .sql file (dbt enforces this).
• One GitHub Actions workflow per .yml file.

Why This Matters for AI-Assisted Development

When AI coding agents (Copilot, Copilot Workspace, or third-party agents) work on issues concurrently, each agent typically modifies a small set of files. If unrelated features share a file, the agents' branches produce conflicting diffs on the same file, requiring manual resolution.

Granular files mean:

1. Zero conflicts. Two agents adding two different components create two different files.
2. Smaller PRs. Each change touches only the files it needs to.
3. Easier reviews. Human and automated reviewers see focused, relevant diffs.
4. Trivial reverts. Removing a feature is as simple as deleting its file(s).

Observability — OpenTelemetry → GCP-native

The observability stack uses OpenTelemetry for instrumentation and GCP-native backends for storage and visualization: Cloud Logging (+ Log Analytics), Cloud Trace, Cloud Monitoring, and Error Reporting. Telemetry stays inside the existing Google BAA — no second vendor boundary, no standing Elasticsearch cluster.

API OTel Setup — backend/api

Dependencies (pyproject.toml)

• opentelemetry-sdk
• opentelemetry-instrumentation-fastapi
• opentelemetry-exporter-otlp

Initialization (main.py)

• Initialize the OTel tracer + meter on application startup.
• Auto-instrument FastAPI with opentelemetry-instrumentation-fastapi.
• The OTLP endpoint is configured via OTEL_EXPORTER_OTLP_ENDPOINT.

In production, OTLP is exported to GCP's managed endpoint (telemetry.googleapis.com) → Cloud Trace / Cloud Monitoring. In development, it points at the local OTel Collector.

PHI Scrub Filter

A PHIScrubFilter stub class is included in the Python backend services (backend/api and backend/worker):

import logging
 
class PHIScrubFilter(logging.Filter):
    def filter(self, record):
        raise NotImplementedError(
            "Implement PHI scrubbing before production use"
        )

This filter is attached to the root logger in each service (backend/api and backend/worker) and will intentionally fail if any log message is emitted before the scrubbing logic is implemented. (This matches the PHIScrubFilter control in HIPAA Compliance, which covers both backends.)

TODO before production:

• Implement regex-based scrubbing for:
  • Medical Record Numbers (MRNs)
  • Dates of Birth (DOB patterns)
  • Patient names
• Test the filter with representative log data
• Verify no PHI appears in Cloud Logging, Cloud Trace spans, or Cloud Build logs

Local Development Stack — docker-compose.otel.yml

For local development, run a lightweight OTel Collector — no Elasticsearch/Kibana required:

The collector receives OTLP on 4317/4318 and, in dev, exports to the console and/or a local Jaeger UI. In production the same OTLP stream is pointed at telemetry.googleapis.com.

OTel Collector Configuration

An otel-collector-config.yml stub is provided:

• Dev: debug (console) exporter + optional otlp → Jaeger.
• Prod: googlecloud exporter (or OTLP → telemetry.googleapis.com).

Data Flow

FastAPI App (OTel SDK)
    → OTLP (gRPC/HTTP)
    → OTel Collector
    → Cloud Trace / Cloud Monitoring / Cloud Logging   (prod: telemetry.googleapis.com)
    → console / local Jaeger                            (dev)

Dashboards

Use Cloud Monitoring dashboards first. If Grafana-grade dashboards are needed, self-host Grafana on Cloud Run against Cloud Monitoring / Managed Prometheus data sources — GCP has no first-party managed Grafana, and Grafana Cloud SaaS would add a third-party boundary.

Alerting / On-Call

Alerting is GCP-native, matching the rest of the observability stack — no separate paging vendor at launch:

• Cloud Monitoring alert policies fire on metric thresholds, log-based metrics, and uptime checks.
• SLOs (Cloud Monitoring service-level objectives with burn-rate alerts) drive the signal — page on error-budget burn, not on every transient blip.
• Notification channels: alerts route to Microsoft Teams (via an incoming-webhook channel) and email. Teams is the primary real-time surface; email is the durable backstop.

Error Tracking

Error tracking is split by tier, each staying inside an existing boundary:

• Backends (backend/api, backend/worker) → GCP Error Reporting (part of Cloud Operations; groups exceptions from Cloud Run logs, in-boundary under the Google BAA).
• Clients (ui/web-app, ui/marketing, ui/ios) → PostHog error tracking — already the BAA-covered analytics/replay vendor, so it covers web + Expo/React Native with no extra boundary.
• Escalation: Sentry if richer release-health / source-map grouping is needed later (adds a vendor boundary + BAA).

LLM Observability & Evals

LLM calls (Gemini via Vertex) are traced and evaluated in PostHog (LLM analytics — prompt/response capture, latency + cost, and eval scoring), consolidating on the vendor already inside the BAA.

• Escalation: self-hosted Langfuse on Cloud Run (in-boundary) if deeper trace trees or dataset-based eval workflows are needed.

HIPAA Compliance Scaffold

HIPAA compliance is scaffolded into the architecture from day one. This is not an afterthought — every vendor choice, logging decision, and data flow is designed with the Security Rule and Privacy Rule in mind.

The Trust Zone (organizing principle)

Define one trust zone. A vendor may touch PHI only if it is inside it — i.e. we hold a signed BAA and the service is configured for it.

• PHI at rest lives only in Neon, GCS, Vertex AI, and WellSky, plus the governed Microsoft 365 plane.
• PHI in motion only crosses services that are inside the zone.
• Anything outside the zone receives references (opaque IDs), never PHI.

🚫 PHI-restricted services (opaque IDs by default)