Architecture Decision Records (ADRs)

This section documents why we made specific architectural and technology decisions.

What is an ADR?

An Architecture Decision Record (ADR) captures:

• Context: What problem were we solving?
• Decision: What did we choose?
• Rationale: Why did we choose it over alternatives?
• Consequences: What are the tradeoffs?

Quick Summary

Authentication

ADR-001: Keycloak vs Auth0 → ✅ Chose Keycloak

• Why: Self-hosted, HIPAA-compliant, $300/month savings vs Auth0
• When: August 2024
• Status: Production

ADR-002: Keycloakify Migration → ✅ Migrated from Freemarker

• Why: React-based, better DX, maintainable with frontend stack
• When: October 2025
• Status: Complete

Backend

ADR-005: FastAPI vs Django → ✅ Chose FastAPI

• Why: Async, modern, auto docs, type safety, WebSocket support
• When: July 2024
• Status: Production

ADR-006: React vs Next.js → ✅ Chose React + Vite

• Why: Simpler deployment, faster builds, more control
• When: July 2024
• Status: Production

Data & Infrastructure

ADR-003: RAG Removal → ✅ Removed Qdrant & scraping

• Why: Focus on scribe core value, reduce complexity, lower costs
• When: October 2025
• Status: Complete

ADR-004: Terraform for Keycloak → ✅ Infrastructure as Code

• Why: Reproducible setup, version control, team collaboration
• When: October 2025
• Status: Production

Product

ADR-007: Manual Invitations → ✅ No email infrastructure

• Why: Simpler onboarding, lower costs, admin control
• When: October 2025
• Status: Production

Package Decisions

All major package evaluations are documented in Package Decisions, including:

• Keycloak (Authentication) - vs Auth0, Supabase
• Anthropic Claude (LLM) - vs GPT-4, self-hosted Llama
• Deepgram (Transcription) - vs Whisper, AssemblyAI
• React (Frontend) - vs Vue, Next.js
• FastAPI (Backend) - vs Django, Flask
• PostgreSQL (Database) - vs MySQL, MongoDB
• React Query (Data fetching) - vs SWR, RTK Query
• TailwindCSS (Styling) - vs styled-components, CSS modules

Creating a New ADR

Use the ADR template when documenting new decisions.

All ADRs

ID	Title	Status	Date
001	Keycloak vs Auth0	✅ Adopted	2024-08
002	Keycloakify Migration	✅ Complete	2025-10
003	RAG Removal	✅ Complete	2025-10
004	Terraform for Keycloak	✅ Adopted	2025-10
005	FastAPI vs Django	✅ Adopted	2024-07
006	React vs Next.js	✅ Adopted	2024-07
007	Manual Invitations	✅ Adopted	2025-10