Skip to main content

Architecture Decision Records (ADRs)

Complete catalog of all technical decisions for TVL Platform

What are ADRs?​

Architecture Decision Records document WHY we chose specific technologies, patterns, and approaches. Each ADR captures:

  • Context - The problem we're solving
  • Decision - What we chose
  • Rationale - Why we chose it (3-5 key reasons)
  • Alternatives - What else we considered (and why we rejected them)
  • Consequences - Trade-offs and mitigations

Status Legend​

  • ✅ Accepted - Decision is active and implemented
  • 🚧 Proposed - Under review
  • ⛔ Deprecated - No longer recommended
  • 🔄 Superseded - Replaced by newer ADR

ADR Index (55 Total)​

Pre-Existing Foundation (4 ADRs)​

#TitleStatusCategory
ADR-0001Google OIDC + RBAC + RLS✅ AcceptedSecurity
ADR-0002PostgreSQL 15+ Data Modeling✅ AcceptedDatabase
ADR-0003BullMQ + Exponential Backoff✅ AcceptedInfrastructure
ADR-0004Vercel + Railway + Supabase + Upstash✅ AcceptedHosting

Foundation & Infrastructure (11 ADRs)​

Core technologies and architectural patterns

#TitleWhy It MattersKey Benefit
ADR-0005TypeScript 5.3+ Strict ModeType safetyCatch 70% of bugs at compile time
ADR-0006Node.js 20 LTSRuntime stabilityLTS support until 2026-04-30
ADR-0007pnpm 8.x for MonorepoFast installs2-3x faster than npm
ADR-0008Doppler Secrets ManagementSOC 2 compliance10min rotation vs 2hr manual
ADR-0009Domain-Driven Design (14 domains)Modular architectureClear boundaries
ADR-0010pnpm WorkspacesCode sharingShared packages across apps
ADR-0011Nx Build SystemBuild performance68% faster builds (cold)
ADR-0012Drizzle ORMType-safe queriesLightweight vs Prisma
ADR-0013Zod ValidationRuntime safetyType inference + validation
ADR-0014Vitest Testing FrameworkTest speed10x faster than Jest
ADR-0055NODE_ENV vs APP_ENV StrategyEnvironment clarityCorrect framework optimizations

Frontend Stack (7 ADRs)​

User interface and client-side architecture

#TitleWhy It MattersKey Benefit
ADR-0015React 18UI frameworkConcurrent rendering
ADR-0016Next.js 14 App RouterSSR + routingServer Components
ADR-0017Tailwind CSS 3.xStylingUtility-first CSS
ADR-0018Shadcn UI ComponentsComponent libraryCopy-paste, not dependency
ADR-0019Zustand State ManagementClient stateSimpler than Redux
ADR-0020TanStack Query (React Query)Server stateAuto cache invalidation
ADR-0021React Hook Form + ZodFormsPerformance + validation

Backend API (7 ADRs)​

REST API architecture and design

#TitleWhy It MattersKey Benefit
ADR-0022Fastify 4.xAPI framework3x faster than Express
ADR-0023REST over GraphQLAPI patternIndustry standard (92% adoption)
ADR-0024OpenAPI 3.0 SpecificationAPI docsAuto-generated from Fastify
ADR-0025RFC 7807 Error HandlingError formatStandardized problem details
ADR-0026URL-Based API VersioningVersioning/api/v1/, /api/v2/
ADR-0053Temporary Supabase Direct Access⛔ RejectedSuperseded by ADR-0054
ADR-0054API-First Approach for MVP.0Production architectureNo migration debt, mobile-ready

Integration Architecture (9 ADRs)​

External API integrations and webhooks

#TitleWhy It MattersKey Benefit
ADR-0027HMAC SHA-256 Webhook SecuritySecurityPrevent tampering
ADR-0028Webhook Idempotency (Payload Hashing)ReliabilityPrevent duplicate processing
ADR-0029Async Webhook Processing (BullMQ)Performance<100ms response time
ADR-0030Transactional Outbox PatternEvent reliabilityNo lost events
ADR-0031Redis Streams as Event BusEvent distributionPersistent pub/sub
ADR-0032Adapter Pattern for ChannelsIntegrationUniform API for all channels
ADR-0033JSONB Field MappingFlexibilityNo code changes for new fields
ADR-0034Circuit Breaker (Opossum)ResiliencePrevent cascade failures
ADR-0035Structured Integration LoggingDebuggingCorrelation IDs for tracing

Caching & Performance (7 ADRs)​

Redis caching strategy and optimization

#TitleWhy It MattersKey Benefit
ADR-0036Redis Application CachingPerformance<1ms cache hits
ADR-0037Cache Key Naming ConventionOrganizationPrevent collisions
ADR-0038Cache Invalidation StrategyCorrectnessPrevent stale data
ADR-0039Cache Stampede PreventionScalabilityPrevent DB overload
ADR-0040LRU Cache EvictionMemory managementKeep hot data
ADR-0041Redis Session StorageAuthenticationFast, distributed sessions
ADR-0042Redis-Based Rate LimitingAbuse preventionToken bucket algorithm

Observability & Monitoring (5 ADRs)​

Metrics, traces, logs, and error tracking

#TitleWhy It MattersKey Benefit
ADR-0043OpenTelemetry for Distributed TracingDebuggingTrack requests across services
ADR-0044Grafana Cloud (Mimir + Tempo + Loki)Unified observabilitySingle pane of glass
ADR-0045Loki for Log AggregationLog centralization50GB/month free tier
ADR-0046Sentry for Error TrackingError managementStack traces + breadcrumbs
ADR-0047Winston for Application LoggingStructured loggingJSON logs for parsing

Code Quality & DX (4 ADRs)​

Developer experience and code standards

#TitleWhy It MattersKey Benefit
ADR-0048ESLint for Code QualityConsistencyCatch bugs early
ADR-0049Prettier for Code FormattingNo debatesAuto-format on save
ADR-0050Husky for Git HooksQuality gatesPrevent bad commits
ADR-005180% Test Coverage RequirementReliabilityCritical paths tested

Documentation Infrastructure (1 ADR)​

Documentation publishing and hosting

#TitleWhy It MattersKey Benefit
ADR-0052Docusaurus + Cloudflare PagesDocumentation hostingFree tier + Google SSO

ADRs by Category​

Security (5 ADRs)​

  • ADR-0001: Google OIDC + RBAC + RLS
  • ADR-0008: Doppler Secrets Management
  • ADR-0027: HMAC SHA-256 Webhook Security
  • ADR-0041: Redis Session Storage
  • ADR-0042: Rate Limiting

Database (4 ADRs)​

  • ADR-0002: PostgreSQL 15+ Data Modeling
  • ADR-0012: Drizzle ORM
  • ADR-0030: Transactional Outbox Pattern
  • ADR-0033: JSONB Field Mapping

Performance (8 ADRs)​

  • ADR-0011: Nx Build System
  • ADR-0022: Fastify (3x faster than Express)
  • ADR-0036-0042: Caching ADRs

Observability (6 ADRs)​

  • ADR-0035: Integration Logging
  • ADR-0043-0047: Observability ADRs

Developer Experience (7 ADRs)​

  • ADR-0005: TypeScript Strict Mode
  • ADR-0013: Zod Validation
  • ADR-0014: Vitest Testing
  • ADR-0048-0051: Code Quality ADRs

How to Use ADRs​

When making technical decisions:​

  1. Check existing ADRs first - Decision may already be made
  2. Reference ADRs in code - Link to ADR in comments
  3. Update ADRs if context changes - Mark as deprecated, create superseding ADR

When onboarding:​

  1. Read Foundation ADRs (0005-0014) - Understand core stack
  2. Read your domain's ADRs - E.g., Frontend team reads ADR-0015-0021
  3. Reference ADRs during code review - "This violates ADR-0005 (TypeScript strict mode)"

When proposing changes:​

  1. Create new ADR - Document decision + rationale
  2. Get team review - Discuss alternatives
  3. Mark old ADR as superseded - If replacing existing decision

Quick Reference​

Most referenced ADRs:

  • ADR-0001 (Auth): Every authentication/authorization question
  • ADR-0002 (Database): Every schema change
  • ADR-0005 (TypeScript): Every code style question
  • ADR-0022 (Fastify): Every API endpoint question

ADRs with code samples:

  • All ADRs include TypeScript/SQL code examples
  • See "Implementation" section in each ADR

ADRs with cost implications:

  • ADR-0004: Hosting topology ($0-50/month)
  • ADR-0008: Doppler ($0-12/user/month)
  • ADR-0044: Grafana Cloud ($0-250/month)

ADR Process​

Creating a new ADR:​

# 1. Copy template
cp docs/reference/decisions/adr-template.md docs/reference/decisions/adr-XXXX-title.md

# 2. Fill in sections:
#    - Status (Proposed)
#    - Context
#    - Decision
#    - Alternatives (3-5)
#    - Consequences

# 3. Get team review

# 4. Mark as Accepted

# 5. Update this index

Updating an ADR:​

## Status
**Deprecated** - 2025-02-01
**Superseded by:** [ADR-0052](./adr-0052-new-approach.md)

Statistics​

  • Total ADRs: 54
  • Accepted: 53
  • Rejected: 1 (ADR-0053)
  • Proposed: 0
  • Deprecated: 0
  • Categories: 9 (Foundation, Frontend, Backend, Integration, Caching, Observability, Code Quality, Documentation, Pre-Existing)
  • Last Updated: 2025-01-26

Questions about ADRs? See CONTRIBUTING.md or ask in #tvl-dev Slack channel.

Last Updated: 2025-01-26 Maintained By: Tech Lead Status: Complete (54/54 ADRs documented)