Why it was built this way
Every architecture and operations decision made on a live production service — recorded as problem → options → decision → verification. New here? Start with the featured ADRs below.
How to read an ADR
- 1
Problem
What situation or constraint forced the decision
- 2
Options
Alternatives considered and their trade-offs
- 3
Decision
What was chosen, and why
- 4
Verification
How we confirmed the decision worked as intended
Featured ADRs
The decisions that matter most for understanding AlgoSu
ADR-001
ADR-001: Gateway → Identity DB Separation
Why read this Where service-level DB boundaries began — splitting the identity DB out of the gateway
ADR-002ADR-002: Outbox Pattern Adoption Review
Why read this The Outbox pattern that delivers events across services without loss
ADR-026ADR-026: Sprint 130 Operations Incident — Stuck Rollouts Left for 6 Days + SealedSecret Controller Key Mismatch Debt
Why read this Recovering from a stuck-rollout production incident and paying off SealedSecret debt
ADR-027ADR-027: aether-gitops Branch Discipline — Enforce Work Branch + PR
Why read this Branch discipline that keeps GitOps auto-deploys safe
ADR-028ADR-028: Dev Server (k3d / Separate Dev Cluster) Separation — Structural Block on Direct Production Modification
Why read this Separating prod and dev clusters so experiments never break production
Browse by topic
Go deep on the topics you care about.
Operations & Recovery
Real production incidents and the decisions that recovered and prevented them
Sprint
problem-service SP196 Migration Fix (tags jsonb DEFAULT cast failure — ERROR 42804)
CompletedCritical
Sprint 230
OracleScribeLibrarian+1 more
SprintPhase 3 External-Work Re-verification + Two Deferred Items Resolved (commitlint oracle scope + Build Blog SSG required check)
CompletedCritical
Sprint 205
OracleArchitectScribe
SprintPhase 3 External Track Closure + PR #365 Close + Cumulative Carryover x2 (CI Python 3.13 + Harness Checkup Seed)
CompletedCritical
Sprint 206
OracleArchitectScribe
SprintDiscord Decommission + BOT_TOKEN Reclamation — Closing the `.claude-tools/` Cleanup Pipeline
CompletedCritical
Sprint 204
OracleArchitectScribe+1 more
SprintRedis Stats Cache — Dashboard Direct DB Aggregation → Cache
CompletedCritical
Sprint 194
OracleArchitectConductor+1 more
Sprintsubmission CacheModule Circular Dependency Hotfix + StudyMemberGuard Redis Consolidation
CompletedCritical
Sprint 195
OracleConductorCritic
SprintCarryover seed cleanup — relocate sprint-87-plan.md to docs/planning/
CompletedHigh
Sprint 190
OracleScribeCritic
SprintBatch resolution of carryover seeds — filterAdjacency P2 · .claude-tools Phase 2 · prom-client Case C/D
CompletedHigh
Sprint 191
OracleArchitectScribe+1 more
SprintProduction Incident Recovery (submission/identity rollout stuck) + Monitoring Strengthening + SealedSecret Debt Clearance + Carryover Cleanup
CompletedCritical
Sprint 130
OracleArchitect
PermanentADR-003: Redis/RabbitMQ ACL Separation Design
UnknownHigh
PermanentADR-025: Gateway OAuth Error Code Normalization
UnknownCritical
PermanentADR-026: Sprint 130 Operations Incident — Stuck Rollouts Left for 6 Days + SealedSecret Controller Key Mismatch Debt
UnknownCritical
Agent Orchestration
How the multi-agent dispatch and cross-review workflow evolved
Sprint
Echelon 1 Tier Model Migration to claude-opus-4-8
CompletedCritical
Sprint 214
OracleCritic
SprintCritic Agent Establishment — Codex-based Cross Code Review
CompletedHigh
Sprint 114
SprintOracle Dispatch and Agent Workflow Improvements
CompletedCritical
Sprint 116
SprintOracle tmux Auto-Dispatch Pipeline
CompletedMedium
Sprint 82
Oracle
CI · GitOps
AI-generated code verification pipelines and GitOps deploy discipline
Sprint
Batch resolution of carryover seeds — filterAdjacency P2 · .claude-tools Phase 2 · prom-client Case C/D
CompletedHigh
Sprint 191
OracleArchitectScribe+1 more
SprintPython Compatibility Fix — asyncio.get_event_loop + Pydantic class Config
CompletedHigh
Sprint 192
OracleArchitectScribe+1 more
SprintCI Actual Measurement Data + Operations Convention Standardization + Commit Gate Automation
CompletedCritical
Sprint 105
PermanentADR-027: aether-gitops Branch Discipline — Enforce Work Branch + PR
UnknownCritical
PermanentADR-028: Dev Server (k3d / Separate Dev Cluster) Separation — Structural Block on Direct Production Modification
UnknownCritical
PermanentADR-029: Consolidate Infra Deployment Definition SSOT into aether-gitops (Retire AlgoSu Parallel Manifests)
UnknownCritical
Data & Problem Sets
Data boundaries, problem datasets, and event delivery decisions
Sprint
Redis Stats Cache — Dashboard Direct DB Aggregation → Cache
CompletedCritical
Sprint 194
OracleArchitectConductor+1 more
TopicProgrammers Dataset Bundling + Gateway External Integration
ProposedCritical
Sprint 95
OracleScoutArchitect+4 more
PermanentADR-001: Gateway → Identity DB Separation
UnknownMedium
PermanentADR-002: Outbox Pattern Adoption Review
UnknownMedium
Security & Secrets
Auth, ACL, and secret management decisions
Sprint
SSOT Backlog Resolution — Internal Key Naming Revision · Sprint-250 ADR Frontmatter · ADR Count · c-ares CVE
CompletedCritical
Sprint 251
OracleScribe
SprintAI Analysis Context Enrichment — Group Analysis Problem Injection + Programmers Crawler Module
CompletedHigh
Sprint 248
OracleScoutSensei+2 more
SprintCodebase-wide Security & Improvement Audit + Sprint Roadmap (ADR-030)
CompletedCritical
Sprint 238
Oracle
SprintSecurity quick wins — ADR-030 S-1/S-2/S-4/S-5/S-8/Q-5
CompletedCritical
Sprint 239
OracleGatekeeperSensei+1 more
SprintOperational procedure hardening — ADR-030 S-6/Q-3 (docs only)
CompletedCritical
Sprint 240
OracleArchitectPostman+1 more
SprintSupply chain, CSP spike, CI cleanup (ADR-030 roadmap item 5 — closure)
CompletedCritical
Sprint 243
OracleGatekeeperConductor+2 more
SprintCI Scanner Install Hardening (retry + auth + direct download) + ADR-028 read-only kubeconfig Groundwork
CompletedHigh
Sprint 233
OraclePostmanLibrarian+1 more
SprintRoot-Cause Fix for CI Trivy blog Failure (Unreferenced APK_CACHE_BUST Cache-Bust Bug)
CompletedHigh
Sprint 225
OraclePostmanLibrarian+1 more
SprintPhase 3 External-Work Re-verification + Two Deferred Items Resolved (commitlint oracle scope + Build Blog SSG required check)
CompletedCritical
Sprint 205
OracleArchitectScribe
SprintPhase 3 External Track Closure + PR #365 Close + Cumulative Carryover x2 (CI Python 3.13 + Harness Checkup Seed)
CompletedCritical
Sprint 206
OracleArchitectScribe
SprintDiscord Decommission + BOT_TOKEN Reclamation — Closing the `.claude-tools/` Cleanup Pipeline
CompletedCritical
Sprint 204
OracleArchitectScribe+1 more
PermanentADR-003: Redis/RabbitMQ ACL Separation Design
UnknownHigh
PermanentADR-024: Admin Server-side Authorization Guard — CSR → Server Component Migration
UnknownCritical
PermanentADR-025: Gateway OAuth Error Code Normalization
UnknownCritical
PermanentADR-030: Codebase-wide Security & Improvement Backlog and Remediation Roadmap (Sprint 238 Audit)
UnknownCritical
Product & Platform
User-facing features and platform migration decisions
Sprint
Blog home landing portfolio revamp + Engineering Editorial design system (Phase 1)
CompletedCritical
Sprint 185
OraclePaletteHerald+3 more
SprintBlog UI/UX revamp — Graph legend/filter + Category 7-class + ADR topic auto-classification (Phase 5)
CompletedCritical
Sprint 189
OracleHeraldArchitect+3 more
SprintFull Removal of the Blog ADR Graph Feature
CompletedHigh
Sprint 193
OracleHeraldCritic
TopicProgrammers Dataset Bundling + Gateway External Integration
ProposedCritical
Sprint 95
OracleScoutArchitect+4 more
Full ADR Archive
All 203 ADRs — stats, timeline, and lists by kind