Skip to main content

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

EXTERNAL ZONEClaude.aiAPI ConsumersWeb ConsoleDMZ — INGRESS LAYERNginx Ingress ControllerINTERNAL ZONE — KUBERNETES CLUSTERSTOA Control PlaneFastAPIAdmin APIUAC Contract ManagerREST • GraphQL • gRPC • KafkaMCP GatewayTool DiscoveryJWT Context InjectionwebMethods GatewayAPI ProxyingPolicy EnforcementKeycloakOAuth2/OIDCMulti-tenant RBACDATA LAYERPostgreSQLContracts • TenantsOpenSearchAPI Logs • AnalyticsRedisCache • SessionsKafka/RedpandaEvents • Audit🔒 INTERNAL ONLYVaultSecrets
Control Plane
MCP Gateway
Internal Only
Authentication

Overview​

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

Security Zones​

ZoneTrust LevelComponents
ExternalUntrustedAPI Clients, Claude.ai, Web Console
DMZSemi-trustedNginx Ingress, API Gateway, MCP Gateway
InternalTrustedControl 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:

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​