Skip to main content

​
Architecture

Runlayer is built on a modern, scalable architecture designed for enterprise-grade performance, security, and reliability.

​
High-Level Architecture

Note: The OAuth Broker is optional and opt-in. Use it when vendor redirect URI allow-listing or centralized OAuth management is desired; otherwise you can integrate directly with providers.

​
Control Plane vs Data Plane Boundary

Runlayer’s MCP gateway sits in the request path between AI clients and MCP servers. The boundary between what the gateway controls and what your MCP servers do is explicit:
PlaneOwned byResponsibilities
Control planeRunlayer gatewayAuthentication and identity (SSO via OAuth 2.0 / SAML), authorization policies (RBAC / PBAC / ABAC), real-time security scanning (ToolGuard), rate limiting and throttling, audit logging
Data planeYour MCP serversTool execution, data access through tools, actual API calls to your upstream services, databases, and resources
AI Client (Claude/Cursor/etc)
    ↓
Runlayer Gateway — authentication + policies + security scanning + audit
    ↓
MCP Server — tool execution (protected backend)
    ↓
Your databases/APIs/resources
Every MCP request is authenticated, authorized, scanned, and logged by the gateway before it reaches the MCP server. The MCP server runs as-is — Runlayer works with any MCP-compliant server without code changes. Network reachability (e.g. via Anthropic MCP Tunnels) is separate from this boundary: the tunnel provides connectivity, while Runlayer still enforces application-layer authentication, connector permissions, policies, and audit logging. For connectors deployed via Runlayer Deploy, data-plane access is scoped by the permissions policy on your own IAM roles, not by the gateway. See Protecting MCP Servers for the full gateway security model and Policies for authorization configuration.

​
Core Components

​
Application Services

  • Gateway Service: Core API and business logic
  • Authentication Service: Identity and access management
  • OAuth Broker (opt-in): Centralized OAuth/OIDC broker providing a vendor allow-listed redirect URI, dual PKCE on MCP↔Broker and Broker↔Vendor, and optional Dynamic Client Registration (Initial Access Token) when supported. Use when redirect allow-listing is a concern; otherwise integrate directly.
  • Background Workers: Asynchronous task processing
  • Web UI: React-based user interface
  • Database Migration Service: Automated schema management and initialization

​
Data Services

  • PostgreSQL: Primary data store
  • Redis: Caching and session management
  • Object Storage: File and artifact storage

​
Infrastructure Services

  • Load Balancer: Traffic distribution and SSL termination
  • Container Orchestration: ECS Fargate with multi-container tasks
  • Networking: VPC with public/private subnets
  • Monitoring: CloudWatch and application metrics

​
Container Architecture

​
Backend Service Architecture

Container Execution Flow:
  1. Prestart Container: Runs database initialization tasks
    • Waits for database availability using connection retry logic
    • Executes Alembic migrations (alembic upgrade head)
    • Creates initial data and superuser accounts
    • Exits successfully when complete
  2. Backend Container: Starts only after prestart container completes
    • Depends on successful completion of prestart container
    • Runs the main FastAPI application
    • Serves API requests and business logic

​
Design Principles

  • Security-Focused OAuth (optional/opt-in): Dual-PKCE via an optional centralized OAuth Broker to mitigate redirect URI allow-list friction and standardize vendor OAuth flows. Flows can operate without the broker when redirect allow-lists are not a concern. See OAuth Broker.
  • Microservices Architecture: Loosely coupled, independently deployable services
  • Cloud-Native: Built for cloud environments with auto-scaling
  • Security-First: Zero-trust security model with encryption everywhere
  • High Availability: Multi-AZ deployment with automatic failover
  • Observability: Comprehensive logging, metrics, and tracing

​
Enterprise Architecture Consulting

For detailed architecture planning, including:
  • Custom Architecture Design - Tailored to your specific requirements
  • Performance Optimization - Architecture tuning for your workloads
  • Security Architecture - Comprehensive security design and review
  • Scalability Planning - Growth planning and capacity management
  • Integration Architecture - Enterprise system integration design
  • Compliance Architecture - Regulatory compliance and governance

Enterprise Architecture Services

Contact our architects for custom architecture design and consulting

​
Reference Architectures

Our team provides reference architectures for common deployment scenarios:
  • Multi-Region Deployment - Global deployment with regional failover
  • Hybrid Cloud - On-premises and cloud integration
  • High Security - Enhanced security for sensitive environments
  • High Performance - Optimized for high-throughput workloads
Contact our architecture team for detailed design documents and implementation guidance.