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 Architecture
Frontend-backend communication and integration:
- ADR 009: API Architecture & Client Generation - REST API with OpenAPI, hey-api client generation, 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
Observability & Analytics
Product usage and observability:
- ADR 011: Product Analytics - PostHog for web and mobile product analytics, funnels, retention, session replay, feature flags
Deployment & CI/CD
Mobile app build and preview workflows:
- ADR 010: Expo CI/CD - EAS builds, preview distribution, PR OTA updates (Android-only v1)
Publishing Packages
How to publish monorepo packages to npm using the dual-mode export strategy.
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.