Home
Architecture documentation for the Foundation platform — presented by h11h.io
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:
Coding agent — primary is undecided. Both Claude Code and GitHub Copilot are greenlit; which one is the primary agent is still an open decision (see the open-decisions section of the Stack Index). Treat neither as settled until this is resolved.
| Step | What happens |
|---|---|
| 1. Write a ticket | Describe the change in Linear in plain English — feature, bug fix, or refactor — with enough detail for an agent to act on it. |
| 2. Assign to a coding agent | A greenlit coding agent (Claude Code / GitHub Copilot) picks up the ticket and opens a pull request implementing the change. |
| 3. Spin up a preview environment | Every PR automatically provisions a full-stack ephemeral environment — an isolated Neon branch plus a dedicated Cloud Run deployment — so the submitter can verify the result before anything touches production. |
| 4. Merge or escalate | CODEOWNERS governs who can approve and merge. If the submitter has merge rights, they merge it themselves. If not, they request a review from someone who does. |
| 5. Ship to production | Once the PR is merged, the CI/CD pipeline deploys to production automatically — no further manual steps required. |
This is made possible by three complementary capabilities: Neon branching gives each PR an isolated copy-on-write database — schema, data, and branched auth — in seconds; GCP Cloud Run spins up a throwaway, prod-identical service; and Coder / GitHub Codespaces gives agents a fully-configured execution environment. The architecture's strict one-concern-per-file modularity means agents rarely produce merge conflicts even when dozens of tickets are in flight simultaneously.
Architecture at a Glance
| Layer | Technology | Hosting |
|---|---|---|
| Frontend (Applications) | Vite + TanStack (Router + Query), TypeScript | GCP Cloud Run |
| Frontend (Marketing) | Next.js 14, App Router, TypeScript | GCP Cloud Run |
| Auth | Better Auth — hosted by the applications-UI server | GCP Cloud Run |
| Authorization | Cerbos (policy-as-code PDP, self-hosted) — with Neon RLS as the enforcement floor | GCP Cloud Run |
| Frontend (Mobile) | Expo, React Native, TypeScript | App Store / Play Store |
| Backend API | FastAPI (HTTP only), Python 3.11+ — backend/api | GCP Cloud Run |
| API Contract | FastAPI OpenAPI → typed TS client (openapi-typescript) | — |
| Durable Execution | Restate Cloud (managed) — virtual objects + durable promises, suspend-to-zero — backend/worker | Restate Cloud + GCP Cloud Run |
| AI Tier | Gemini on Vertex AI — reasoning · embeddings · voice | GCP |
| OLTP Database | Neon (PostgreSQL) | Neon (Scale plan, BAA) |
| OLAP / Data Warehouse | Google BigQuery | GCP |
| Data Transform | dbt (incremental, Neon → BigQuery) | GitHub Actions (scheduled) |
| Backups & DR | Neon PITR · BigQuery time-travel · GCS versioning | — |
| Infrastructure as Code | Pulumi (TypeScript) | Pulumi Cloud |
| Observability | OpenTelemetry → GCP-native (Logging / Trace / Monitoring) | GCP |
| Secrets | Pulumi ESC + GCP Secret Manager | GCP |
| CI/CD | GitHub Actions | GitHub |
| Monorepo | Turborepo | — |
| JS/TS Tooling | Biome (lint + format), Lefthook (hooks) | — |
| Python Tooling | Ruff (lint + format), pytest | — |
| Dev Environment | Devbox, direnv, process-compose, Coder | — |
Key Design Principles
- 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.
- 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.
- Monorepo with strict modularity. One concern per file. Enables parallel AI-assisted development with zero merge conflicts.
- Cross-cloud data bridge. Neon (OLTP, source of truth) → BigQuery (OLAP) via incremental sync (
WHERE updated_at >), minimizing egress across the GCP ↔ AWS boundary. - Reproducible environments. Devbox + direnv + process-compose ensure every developer gets an identical setup in one command.
- Coverage gates. ≥ 80% test coverage enforced in CI. No PR merges without passing all quality checks.
Documentation Sections
| Section | Description |
|---|---|
| Incubation Workflow | Rapid prototyping with GitHub Spark and a zero-friction graduation path into the monorepo |
| Monorepo Structure | Turborepo layout, workspaces, and build pipelines |
| Frontend (Web) | Vite + TanStack applications, Next.js marketing site, Better Auth, Cloud Run hosting |
| Mobile | Expo + React Native with expo-router |
| Backend | FastAPI HTTP (backend/api) + Restate durable worker (backend/worker), Neon, Docker |
| AI Tier | Gemini on Vertex — reasoning/orchestration, embeddings + pgvector, voice; in-boundary |
| Infrastructure | Pulumi IaC for GCP + Neon setup notes |
| Data Pipeline | dbt models, Neon → BigQuery, incremental sync |
| Backups & Recovery | Neon PITR, BigQuery time-travel, GCS versioning, RTO/RPO + restore runbook |
| CI/CD | GitHub Actions quality gates and deployments |
| PR Preview Environments | Ephemeral full-stack environments per pull request |
| Secure PHI GitOps | Dual-Neon PHI/non-PHI split, isolated Coder compute, and the dev/main/release branch strategy |
| Developer Tooling | Devbox, Biome, Ruff, Lefthook, dev containers |
| Code Organization | File modularity and the "one concern per file" rule |
| Observability | OpenTelemetry → GCP-native + PHI scrubbing |
| HIPAA Compliance | Vendor BAAs, the PHI-free service list, technical controls |
| Libraries | Canonical Python and JS/TS library reference |
| Environment Variables | Master env var reference across all services |
| Content Management | Decoupled marketing stack — Sanity.io CMS + PostHog (product analytics + feature flags + experiments + session replay + error tracking + LLM observability & evals) |
| Secret Management | Pulumi ESC + GCP Secret Manager |
| GitHub Copilot Skills | Reusable agent skills for common multi-step dev tasks |
| The Stack | Complete service catalog with pricing at every team size |
| Business Operations | Non-product IT/ops stack — M365 identity/security, finance, GTM, support |
Prompt Templates
This architecture ships with two prompt templates for AI-assisted project management:
| Template | Purpose |
|---|---|
GITHUB-JUMPSTART.md | Scaffold a new project from scratch following this architecture |
APPLY-ARCHITECTURE.md | Migrate an existing project to conform to this architecture |