Architecture Overview
STOA Platform is designed as a cloud-native, multi-tenant gateway platform built for both traditional APIs and AI agents.
High-Level Architecture
STOA follows a Control Plane / Data Plane separation pattern, similar to Kubernetes and Istio.
Control Plane vs Data Plane
| Aspect | Control Plane | Data Plane |
|---|---|---|
| Role | Configuration & Management | Traffic Execution |
| Components | Core API, Portal, Console | MCP Gateway, webMethods |
| Latency | Human-scale (ms OK) | Machine-scale (sub-ms) |
| Scaling | Moderate | High (per-request) |
This separation is documented in ADR-001: API Exposure Strategy.
Core Components
Control Plane API
The central management API built with Python and FastAPI.
| Aspect | Details |
|---|---|
| Language | Python 3.12+ |
| Framework | FastAPI (async) |
| Database | PostgreSQL + SQLAlchemy |
| Event Streaming | Kafka/Redpanda |
| Auth | Keycloak (OIDC) |
Responsibilities:
- Subscription management
- Tenant provisioning
- Tool catalog
- Usage tracking
- Policy enforcement
MCP Gateway
The MCP Gateway handles Model Context Protocol interactions, enabling AI agents to securely consume enterprise tools.
| Aspect | Current Implementation |
|---|---|
| Language | Python 3.12+ |
| Framework | FastAPI (async) |
| Policy Engine | OPA (Open Policy Agent) |
| Protocol | MCP (Model Context Protocol) |
Responsibilities:
- MCP protocol handling
- Request routing
- Authentication validation
- Rate limiting
- Metrics collection
A high-performance Rust + Tokio implementation is planned for Q4 2026, bringing kernel-level eBPF acceleration. See our Roadmap for details.
API Gateway
Traditional API traffic is handled by webMethods Gateway (current implementation).
| Aspect | Details |
|---|---|
| Product | Software AG webMethods |
| Features | Rate limiting, transformations, policies |
| Protocol | REST, SOAP |
Migration to a native Rust/eBPF gateway is planned for Phase 16+, providing improved performance and reduced operational overhead.
Portal UI
Self-service developer portal built with React and TypeScript.
Features:
- API/Tool catalog browsing
- Subscription management
- API key generation
- Usage dashboards
- Documentation access
Console UI
Admin management console built with React and TypeScript.
Features:
- Tenant management
- User administration
- Policy configuration
- System monitoring
- Audit logs
Security Layer
Keycloak
Identity and access management providing:
- OIDC/OAuth2 authentication
- SSO (Single Sign-On)
- RBAC (Role-Based Access Control)
- Multi-factor authentication
- User federation
HashiCorp Vault
Secrets management for:
- API key encryption
- Database credentials
- TLS certificates
- Service tokens
Data Layer
PostgreSQL
Primary database storing:
- Subscriptions
- Tenants
- Users
- Tool definitions
- Audit logs
Kafka/Redpanda
Event streaming for:
- Audit events
- Usage metrics
- Cross-service communication
Kafka is strictly internal with zero external exposure (ADR-017). All external integrations use REST APIs.
Observability Stack
| Component | Purpose |
|---|---|
| Prometheus | Metrics collection |
| Grafana | Dashboards & visualization |
| Loki | Log aggregation |
| Alertmanager | Alert routing |
Request Flow
- AI Agent sends a tool invocation request with an API key
- MCP Gateway validates the API key against Keycloak
- Gateway checks subscription status with Control Plane API
- Control Plane verifies the subscription is active
- Gateway forwards the request to the appropriate MCP Server
- MCP Server executes the tool and returns the response
- Gateway returns the response to the AI Agent
Deployment
STOA Platform runs on Kubernetes and can be deployed using:
- Helm Charts: Available in
stoa-infra/charts/ - GitOps: ArgoCD compatible
- IaC: Terraform modules available
Kubernetes Namespace
All components run in the stoa-system namespace:
kubectl get pods -n stoa-system
Ingress Endpoints
| Service | URL Pattern |
|---|---|
| Portal | portal.<domain> |
| Console | console.<domain> |
| API | api.<domain> |
| Gateway | gateway.<domain> |
| Auth | auth.<domain> |
Technology Stack Summary
| Layer | Technology | Notes |
|---|---|---|
| Control Plane | Python, FastAPI | Management API |
| MCP Gateway | Python, FastAPI, OPA | MCP protocol handling |
| API Gateway | webMethods | Traditional API traffic |
| Frontend | React, TypeScript, Tailwind | Portal & Console |
| Database | PostgreSQL | Primary data store |
| Event Streaming | Kafka/Redpanda | Internal events |
| Streaming | Kafka/Redpanda | Internal events |
| Auth | Keycloak | OIDC/OAuth2 |
| Secrets | HashiCorp Vault | Encryption, credentials |
| Observability | Prometheus, Grafana, Loki | Metrics, logs |
| Infrastructure | Kubernetes, Helm, ArgoCD | Deployment |
Next Steps
- Quick Start Guide - Get STOA running locally
- API Reference - Explore the Control Plane API
- MCP Gateway - Deep dive into MCP integration