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