Architecture Decision Records (ADRs)
"Each tool to its purpose" — No one-size-fits-all
This directory contains important architectural decisions for STOA Platform.
📚 ADR Index
🏛️ Core Architecture
| # | Title | Status |
|---|---|---|
| 003 | Monorepo Architecture — Multi-Service Polyglot | ✅ |
| 004 | Gateway Adapter Pattern — Multi-Gateway Orchestration | ✅ |
| 005 | Event-Driven Architecture — Kafka Topics Design | ✅ |
| 006 | Tool Registry Architecture — 7-Module Design | ✅ |
⚡ Performance & Reliability
| # | Title | Status |
|---|---|---|
| 008 | Semantic Response Caching — pgvector Strategy | ✅ |
| 009 | Error Snapshots — Time-Travel Debugging | ✅ |
🏗️ Platform & Infrastructure
| # | Title | Status |
|---|---|---|
| 001 | Third-Party API Exposure Strategy — Public API Façade | ✅ |
| 002 | stoactl CLI Design | 📋 |
| 007 | GitOps with Argo CD | ✅ |
| 025 | Gateway Resilience — Anti-Zombie Node Pattern | 📋 |
| 026 | Multi-IAM Federation Pattern — Zero User Storage | ✅ |
🔐 Security & Compliance
| # | Title | Status |
|---|---|---|
| 011 | API Security Mode Selection — mTLS / OAuth2 / Hybrid | ✅ |
| 018 | Security Hardening P0 — Team Coca Pentest | ✅ |
🤖 MCP & AI Gateway
| # | Title | Status |
|---|---|---|
| 012 | MCP Tools Architecture — RBAC & Multi-Tenant Governance | ✅ |
| 020 | Runtime Data Governance | ✅ |
| 021 | UAC-Driven Observability | 📋 |
| 022 | UAC Tenant Architecture | ✅ |
| 023 | Zero Blind Spot Observability | ✅ |
| 024 | Unified Gateway Architecture — 4 Deployment Modes | ✅ |
💼 Business & Strategy
| # | Title | Status |
|---|---|---|
| 019 | Business Model & Moat Strategy | ✅ |
| 041 | Plugin Architecture — Community Core vs Enterprise Extensions | ✅ |
🛠️ Developer Experience & AI Workflow
| # | Title | Status |
|---|---|---|
| 030 | AI-Native Context Management Architecture | ✅ |
| 031 | CI/CD Reusable Workflow Architecture | ✅ |
| 032 | Response Transformation — Pluggable Adapters | ✅ |
🎨 Frontend & UX
| # | Title | Status |
|---|---|---|
| 033 | Shared UI Components — Theme Abstraction | ✅ |
🦀 Evolution
| # | Title | Status |
|---|---|---|
| 034 | Python to Rust Migration Strategy | ✅ |
🌐 Gateway & Deployment
| # | Title | Status |
|---|---|---|
| 035 | Gateway Adapter Pattern — Multi-Gateway Orchestration | ✅ |
| 036 | Gateway Auto-Registration — Zero-Config Onboarding | ✅ |
| 037 | Deployment Modes — Sovereign First Strategy | ✅ |
🔮 Planned ADRs
| # | Title | Priority |
|---|---|---|
| 010 | Blockchain Decision — Digital Euro 2027+ | 🔵 |
| 013 | Idempotency & Saga Patterns — Exactly-Once for B2B | 🟡 |
| 014 | Delivery Guardrails — Canary & SLO Auto-Freeze | 🟡 |
| 015 | Sender-Constrained Tokens — mTLS Binding, DPoP & DCR | 🟡 |
| 016 | Release Engineering — Git Workflow & Versioning | 🟢 |
| 017 | Kafka/Redpanda Internal-Only — Zero External Exposure | 🟡 |
Legend: ✅ Accepted · 📋 Draft · 🟢 High · 🟡 Medium · 🔵 Low
Technology Choices Overview
| Category | STOA Choice | Alternatives | Rationale |
|---|---|---|---|
| Messaging | Kafka (Redpanda) | RabbitMQ, NATS | Event sourcing, replay, scale |
| Database | PostgreSQL | MySQL, MongoDB | ACID, JSON, extensions |
| Auth | Keycloak | Auth0, Okta | Self-hosted, full OIDC |
| Observability | Prometheus + Grafana + Loki | Datadog, ELK | Open source, K8s-native |
| GitOps | ArgoCD | Flux, Jenkins | UI, multi-cluster |
| Automation | ArgoCD + Gateway Adapters | Terraform | Idempotent, auditable |
| Gateway v1 | webMethods | Kong, APISIX | Legacy expertise |
| Gateway v2 | Rust + eBPF | Go, C++ | Performance, safety |
| Search | OpenSearch | Elasticsearch | Apache 2.0, AWS-free |
Guiding Principles
| Principle | Application |
|---|---|
| Open Source first | Avoid lock-in, contribute upstream |
| K8s-native | Operators, CRDs, GitOps |
| Right tool for the job | Kafka for events, PostgreSQL for ACID |
| Self-hosted possible | No mandatory SaaS dependency |
| Permissive license | Apache 2.0, MIT — avoid GPL, SSPL |
| Cloud-agnostic | No mandatory managed service |
ADR Template
Use the template below to create new ADRs.
# ADR-XXX: [Title]
## Metadata
| Field | Value |
|-------|-------|
| **Status** | 📋 Draft / ✅ Accepted / ❌ Rejected / 🔄 Superseded |
| **Date** | YYYY-MM-DD |
| **Linear** | [CAB-XXX](link) |
## Context
[Why is this decision needed?]
## Decision
[What was decided?]
## Consequences
### Positive
### Negative
### Mitigations
## References