> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> System architecture and design principles for Runlayer

# Architecture

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

## High-Level Architecture

```mermaid theme={null}
graph TB
    subgraph "Client Layer"
        UI[Web UI]
        API[API Clients]
        MCP[MCP Clients]
    end

    subgraph "Application Layer"
        ALB[Application Load Balancer]
        Gateway[Gateway Service]
        Auth[Authentication Service]
        OAuthBroker[OAuth Broker Service]
        Worker[Background Workers]
    end

    subgraph "Data Layer"
        PG[(PostgreSQL)]
        Redis[(Redis Cache)]
        S3[(Object Storage)]
    end

    subgraph "Infrastructure"
        VPC[VPC Network]
        ECS[ECS Fargate]
        RDS[RDS PostgreSQL]
        ElastiCache[ElastiCache Redis]
    end

    UI --> ALB
    API --> ALB
    MCP --> ALB
    ALB --> Gateway
    ALB --> Auth
    ALB --> OAuthBroker
    Gateway --> Worker
    Gateway --> PG
    Gateway --> Redis
    Gateway -->|OAuth Tokens| OAuthBroker
    OAuthBroker -->|Vendor OAuth| Vendor[(3rd-Party OAuth Providers)]
    Auth --> PG
    Worker --> S3
```

> 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:

| Plane             | Owned by         | Responsibilities                                                                                                                                                                                                 |
| ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Control plane** | Runlayer gateway | Authentication and identity (SSO via OAuth 2.0 / SAML), authorization policies (RBAC / PBAC / ABAC), real-time security scanning ([ToolGuard](/runlayer-toolguard)), rate limiting and throttling, audit logging |
| **Data plane**    | Your MCP servers | Tool 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](/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](/platform-deploy), data-plane access is scoped by the permissions policy on your own IAM roles, not by the gateway.

See [Protecting MCP Servers](/reverse-proxy) for the full gateway security model and [Policies](/platform-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, PKCE on MCP↔Broker and on Broker↔Vendor when supported, 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

```mermaid theme={null}
graph LR
    subgraph "ECS Task Definition"
        subgraph "Init Container"
            Prestart[Prestart Container]
        end
        subgraph "Main Container"
            Backend[Backend API]
        end
    end

    subgraph "Database"
        DB[(PostgreSQL)]
    end

    Prestart -->|1. Check DB Connection| DB
    Prestart -->|2. Run Migrations| DB
    Prestart -->|3. Create Initial Data| DB
    Prestart -->|4. Exit Successfully| Backend
    Backend -->|5. Start Application| DB
```

**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)**: PKCE via an optional centralized OAuth Broker, with upstream PKCE when supported, 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](../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

<Card title="Enterprise Architecture Services" icon="building" href="mailto:support@runlayer.com">
  Contact our architects for custom architecture design and consulting
</Card>

## 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.