Architecture Decisions
Architecture Decision Records (ADRs) documenting key technical decisions for the monorepo.
Architecture Decision Records (ADRs) document key technical decisions made during development. Each ADR captures the context, considered options, decision rationale, and consequences.
Foundation Layer
Foundational infrastructure decisions:
- ADR 001: Monorepo vs Standalone - Monorepo architecture with Turborepo
- ADR 005: Package Manager - pnpm for package management with Node.js LTS runtime
Backend Stack
Server infrastructure and data storage:
- ADR 002: Backend Framework & Runtime - Node.js LTS + Fastify for backend API
- ADR 008: Database Platform & Strategy - PostgreSQL with Supabase and portability strategy
- ADR 007: Backend ORM - Drizzle ORM for type-safe PostgreSQL queries
API Contract Layer
Frontend-backend communication and integration:
- ADR 009: API Architecture & Contract Strategy - OpenAPI-first with hey-api, REST-first, multi-language SDK strategy, AI/MCP integration
Frontend Stack
Client application infrastructure:
- ADR 003: Frontend Framework - Next.js for frontend applications
- ADR 004: Design System - Shadcn/ui with Tailwind CSS
Code Quality
Development tooling and code standards:
- ADR 006: Linters & Formatters - Hybrid Biome + ESLint architecture
Portability Strategy
Zero vendor lock-in architecture designed to migrate from Vercel (rapid iteration) to GCP/AWS (production security) without code changes.
ADR 001: Monorepo vs Standalone Repositories
Decision to adopt a monorepo architecture using Turborepo for better code reuse, unified tooling, and simplified dependency management across multiple frontend and backend applications.