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 | ✅ |
| 035 | Gateway Adapter Pattern — Multi-Gateway Orchestration | ✅ |
| 045 | stoa.yaml Declarative API Specification | ✅ |
Platform & Infrastructure
| # | Title | Status |
|---|---|---|
| 001 | Third-Party API Exposure Strategy — Public API Facade | ✅ |
| 002 | stoactl CLI Design | 📋 |
| 007 | GitOps with Argo CD | ✅ |
| 025 | Gateway Resilience — Anti-Zombie Node Pattern | 📋 |
| 031 | CI/CD Reusable Workflow Architecture | ✅ |
| 040 | Born GitOps — Multi-Environment Promotion Architecture | ✅ |
| 043 | Kafka → MCP Event Bridge Architecture | 📋 |
Security & Compliance
| # | Title | Status |
|---|---|---|
| 011 | API Security Mode Selection — mTLS / OAuth2 / Hybrid | ✅ |
| 015 | Token Optimization Architecture | 📋 |
| 018 | Security Hardening P0 — Team Coca Pentest | ✅ |
| 026 | Multi-IAM Federation Pattern — Zero User Storage | ✅ |
| 027 | X.509 Header Authentication | ✅ |
| 028 | RFC 8705 Certificate Binding | ✅ |
| 029 | mTLS Certificate Lifecycle | ✅ |
| 039 | Rust Gateway mTLS Cert-Bound Tokens | ✅ |
| 044 | MCP OAuth 2.1 Gateway Proxy Architecture | ✅ |
| 054 | RBAC Taxonomy v2 — Persona Roles & Display Names | ✅ |
| 056 | FAPI 2.0 Security Architecture | ✅ |
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 | ✅ |
| 046 | MCP Federation Architecture | 📋 |
| 047 | MCP Skills System — Context Injection | 📋 |
| 048 | Integrated Chat Agent Architecture | 📋 |
| 051 | Lazy MCP Discovery with Cache-First Pattern | ✅ |
Performance & Observability
| # | Title | Status |
|---|---|---|
| 008 | Semantic Response Caching — pgvector Strategy | ✅ |
| 009 | Error Snapshots — Time-Travel Debugging | ✅ |
| 049 | Enterprise AI-Native Gateway Benchmark | ✅ |
| 050 | Guardrails V2 — Token Budget State Management | ✅ |
| 052 | Benchmark OpenSearch Persistence & LLM Routing | ✅ |
| 053 | LLM Cost-Aware Routing | ✅ |
Gateway & Deployment
| # | Title | Status |
|---|---|---|
| 034 | Python to Rust Migration Strategy | ✅ |
| 036 | Gateway Auto-Registration — Zero-Config Onboarding | ✅ |
| 037 | Deployment Modes — Sovereign First Strategy | ✅ |
| 038 | Sidecar Deployment on VM Infrastructure | 📋 |
| 057 | Product Lineup — STOA Gateway, STOA Link, STOA Connect | ✅ |
| 058 | Pingora Integration — Embedded Connection Pool | ✅ |
Frontend & UX
| # | Title | Status |
|---|---|---|
| 032 | Response Transformation — Pluggable Adapters | ✅ |
| 033 | Shared UI Components — Theme Abstraction | ✅ |
| 055 | Portal/Console Governance — Clear Separation of Concerns | ✅ |
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 | ✅ |
| 065 | STOA PR Guardian — Advisory AI Review on GitHub Actions | ✅ |
Planned ADRs
| # | Title | Priority |
|---|---|---|
| 010 | Blockchain Decision — Digital Euro 2027+ | Low |
| 013 | Idempotency & Saga Patterns — Exactly-Once for B2B | Medium |
| 014 | Delivery Guardrails — Canary & SLO Auto-Freeze | Medium |
| 016 | Release Engineering — Git Workflow & Versioning | High |
| 017 | Kafka/Redpanda Internal-Only — Zero External Exposure | Medium |
Legend: ✅ Accepted · 📋 Draft/Proposed
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 (Pingora) | 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