Architecture

This section presents the architecture diagrams of STOA Platform, illustrating the different components, data flows and security decisions.

Interactive Diagrams

Architecture Globale

Vue d'ensemble des composants et flux de données

Control Plane

MCP Gateway

Internal Only

Authentication

Overview

STOA Platform follows a cloud-native architecture deployed on Kubernetes with the following principles:

Security Zones

Zone	Trust Level	Components
External	Untrusted	API Clients, Claude.ai, Web Console
DMZ	Semi-trusted	Nginx Ingress, API Gateway, MCP Gateway
Internal	Trusted	Control Plane, Keycloak, Data Layer

Main Components

• STOA Control Plane — FastAPI, UAC contract management, multi-protocol APIs
• MCP Gateway — Claude.ai integration, tool discovery, JWT context injection
• webMethods Gateway — API proxy, policy enforcement
• Keycloak — OAuth2/OIDC, multi-tenant RBAC

Data Layer

• PostgreSQL — Contracts, tenants, subscriptions
• OpenSearch — API logs, analytics
• Redis — Cache, sessions, rate limiting
• Kafka/Redpanda — Events, audit (🔒 Internal Only)
• Vault — Secrets, certificates

Architecture Decision Records (ADRs)

Important architectural decisions are documented via ADRs:

• ADR-019: Business Model & Moat Strategy — Trademark, Velocity, Ecosystem
• ADR-018: Security Hardening P0 — Team Coca Pentest Fixes
• ADR-017: Kafka Internal-Only — Zero External Exposure
• ADR-016: Multi-tenant RBAC — Isolation via JWT Context
• ADR-015: GitOps with Argo CD — Continuous Deployment

CI/CD Pipeline

The pipeline follows a GitOps approach with:

1. Code — GitLab with Helm Charts
2. Build & Test — Lint, Tests, Security Scan, Build Image
3. Package — Container Registry (signed), Helm Repository
4. Deploy — Argo CD with continuous sync

Supply Chain Security

• SBOM — Software Bill of Materials generated automatically
• Cosign — Container image signing
• SLSA — Provenance attestations

MCP Gateway

The MCP (Model Context Protocol) Gateway enables integration with Claude.ai:

Execution Flow

1. Claude.ai sends a tools/call with JWT
2. MCP Gateway decodes the JWT and extracts the tenant
3. Keycloak validates the token and verifies RBAC permissions
4. Control Plane executes business logic and validates UAC contract
5. Backend API processes the request
6. Response returned with Trace ID

Multi-Tenant Isolation

Each tenant only sees their own tools:

• Parzival (IOI) — stoa_*, ioi:billing:*, ioi:inventory:*
• Sorrento (Gregarious) — stoa_*, greg:oasis:*, greg:sixers:*
• Halliday (Admin) — Full cross-tenant visibility

Additional Resources

• Quick Start Guide
• API Reference