Control Core Architecture

Audience: Solutions architects, platform engineers, and policy authors mapping how Control Core fits together.
Time: ~20 min for this page; linked guides vary.

This guide covers architecture, component interactions, data flows, and deployment patterns. For the interactive API surface on your own deployment, open the Developer Portal at GET /devdocs on your Control Plane API host — see API Reference — Developer Portal.

Troubleshooting: If /devdocs does not return the Scalar Developer Portal, reverse-proxy routing is often the cause. See Troubleshooting — Developer Portal quick checks.

Core components

Dual Environment Architecture (Default Model)

Control Core exclusively uses a dual environment deployment model with sandbox for development/testing and production for live enforcement. This is the foundational design, not an optional feature.

Default Deployment: One Control Plane, Multiple Bouncer Pairs

┌─────────────────────────────────────────────────────────────────┐
│                  CONTROL PLANE (Single Instance)                 │
│                  Manages Both Environments                       │
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ Admin UI    │  │   API       │  │ Policy Bridge│             │
│  │ (Frontend)  │  │  (Backend)  │  │   Server    │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                  │
│  • All policies managed here                                    │
│  • Tracks bouncer pairs                                         │
│  • Sandbox & Production separation                              │
└──────────────────────────────┬───────────────────────────────────┘
                               │
            ┌──────────────────┼──────────────────┐
            │ (REQUIRED)       │ (OPTIONAL)       │
            ▼                  ▼                  ▼
   ┌──────────────────┐    ┌──────────────────┐
   │ Sandbox Bouncer  │◄───│Production Bouncer│ 
   │  (START HERE)    │PAIR│   (Add Later)    │
   │                  │────│                  │
   │ ENVIRONMENT=     │    │  ENVIRONMENT=    │
   │   sandbox        │    │   production     │
   │                  │    │                  │
   │ RESOURCE_NAME=   │    │  RESOURCE_NAME=  │
   │ "Payment API"    │    │  "Payment API"   │ ◄ SAME (Paired)
   │                  │    │                  │
   │  Test Resources  │    │  Live Resources  │
   └──────────────────┘    └──────────────────┘
      CREATE POLICIES       ENFORCE PROMOTED
       TEST HERE            POLICIES HERE

   (One pair shown; deploy multiple such pairs—one per logical resource.)

Key Concepts

1. One Control Plane, Multiple Bouncers: A single Control Plane instance manages all bouncers; you deploy as many bouncer pairs as you have logical resources to protect.
2. Bouncers Come in Pairs: Each logical resource (e.g., "Payment API") has a sandbox bouncer and a production bouncer, paired by the same RESOURCE_NAME.
3. Resources Are in Pairs: The Control Plane creates or links a sandbox resource and a production resource per logical resource (one per bouncer); pairing is by RESOURCE_NAME and environment.
4. Sandbox is Required: All policy development happens in sandbox first.
5. Production Pairs with Sandbox: Deploy a production bouncer with the same RESOURCE_NAME as its sandbox pair when ready.
6. Policy Promotion: Policies created in sandbox, promoted to production.
7. API Key Separation: cc_sandbox_ for sandbox, cc_prod_ for production.

High-Level Architecture

Control Core uses a distributed architecture designed for scalability, performance, and reliability across any cloud provider or on-premises infrastructure.

Access Path Overview

Before any subject reaches a protected resource, Control Core places the Bouncer in the request path and evaluates policy first.

This is the core Control Core pattern: subject -> request -> Bouncer / PEP -> policy decision -> resource. A request is denied and logged before it can touch the resource unless policy explicitly allows it.

┌─────────────────────────────────────────────────────────────────┐
│                    CLIENT APPLICATIONS                          │
│         (Web Apps, Mobile Apps, APIs, AI Agents)                │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ HTTPS/API Calls
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              POLICY ENFORCEMENT POINT (BOUNCER)                 │
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    │
│  │   Reverse    │ →  │   Policy     │ →  │   Forward    │    │
│  │   Proxy      │    │   Decision   │    │   to Target  │    │
│  └──────────────┘    │   Point      │    └──────────────┘    │
│                      └──────┬───────┘                         │
│                             │                                  │
│                      ┌──────▼───────┐                         │
│                      │ Policy Cache │                         │
│                      │Decision Cache│                         │
│                      └──────────────┘                         │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Policy Sync (WebSocket)
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│          POLICY BRIDGE (Policy Distribution)                    │
│                                                                 │
│  - Monitors policy repositories (Git)                           │
│  - Distributes policies to all Bouncers                         │
│  - Publishes data from integrations                             │
│  - Real-time updates via WebSocket                              │
└────────────────────────────┬────────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Policy     │    │ External     │    │  Protected   │
│ Repository   │    │ Data Sources │    │   Target     │
│ (Git/GitHub) │    │ (PIP)        │    │ Application  │
└──────────────┘    └──────────────┘    └──────────────┘
                             ▲
                             │
                             │ API Calls
                             │
┌─────────────────────────────────────────────────────────────────┐
│         POLICY ADMINISTRATION POINT (CONTROL PLANE)             │
│                                                                 │
│  ┌──────────────────────┐    ┌──────────────────────┐         │
│  │  Administration      │    │  Administration      │         │
│  │  Console (UI)        │    │  API (Backend)       │         │
│  │                      │    │                      │         │
│  │ - Policy Management  │    │ - Policy CRUD        │         │
│  │ - User Management    │    │ - Authentication     │         │
│  │ - Resource Config    │    │ - Decision Logging   │         │
│  │ - Monitoring         │    │ - Integration Mgmt   │         │
│  └──────────────────────┘    └──────────┬───────────┘         │
│                                          │                      │
│              ┌───────────────────────────┼──────────┐          │
│              ▼                           ▼          ▼          │
│      ┌──────────────┐         ┌──────────────┐  ┌────────┐   │
│      │   Database   │         │    Cache     │  │ Policy │   │
│      │              │         │              │  │ Editor │   │
│      └──────────────┘         └──────────────┘  └────────┘   │
└─────────────────────────────────────────────────────────────────┘

Data Flow

Policy Bridge Flow (Policy Distribution)

The following diagram shows how policies and integration data flow from the Control Plane to all bouncers via the Policy Bridge.

The Policy Bridge (Control Bridge) operates between the Control Plane, Git/GitHub (policy repository), and Bouncers: it monitors the policy repo (and/or receives updates from the Control Plane API), and distributes policies and PIP data to bouncers. Policy–bouncer linking: When a policy or control is created in the Policy Builder (page 1), it is linked to a Resource and Bouncer. The Policy Bridge (Policy Bridge) syncs that policy only to the selected bouncer(s) for that resource—each bouncer receives only the policies linked to its resource(s). The Git/GitHub connection is part of this flow, not optional.

Draft, activated, and archived storage: The same policy–resource linking affects where policies live and who receives them:

• GitHub: Policies are stored under resource-scoped paths: policies/{resource_slug}/sandbox/draft, policies/{resource_slug}/sandbox/enabled, policies/{resource_slug}/sandbox/disabled, policies/{resource_slug}/sandbox/archived, and the same under production/. So each resource (and thus each bouncer’s Policy Bridge folder_path) has its own draft, enabled, disabled, and archived folders.
• Control Plane: Policy status (draft, enabled, disabled, archived), environment (sandbox/production/both), and resource_id are stored in the database. The Control Plane is the source of truth for status; GitHub paths are updated when you save, enable, disable, promote, or archive.
• Bouncers: Each bouncer’s Policy Bridge client is configured with a folder_path like policies/{resource_slug}/{environment}. It receives only enabled policies for that resource (and environment). Draft and archived policies are not synced to bouncers.

Policy Creation and Deployment Flow

1. Policy Developer writes policy in Console
   ↓
2. Policy validated (syntax, semantics)
   ↓
3. Policy tested with test cases
   ↓
4. Policy saved to database
   ↓
5. Policy committed to Git repository (when using Git-backed workflow)
   ↓
6. Policy Bridge (Control Bridge) detects policy change from Git and/or Control Plane
   ↓
7. Policy Bridge distributes to the relevant Bouncer(s) via WebSocket (only bouncers linked to that policy’s resource receive it)
   ↓
8. Bouncers receive and compile policy
   ↓
9. Policy active (typically < 30 seconds)
   ↓
10. Requests evaluated against new policy

Authorization Request Flow

When a client sends a request, the bouncer evaluates policy and either forwards the request or returns 403.

Step-by-step:

1. Client sends request to protected application
   ↓
2. Bouncer intercepts request
   ↓
3. Bouncer extracts context (user, resource, action)
   ↓
4. Check decision cache
   ├─ If cached → Return cached decision (5-10ms)
   └─ If not cached ↓
5. Evaluate policy
   ├─ Load policy from cache
   ├─ Load integration data (if needed)
   ├─ Evaluate policy rules
   └─ Generate decision (20-50ms)
   ↓
6. Cache decision (if cacheable)
   ↓
7. Log decision for audit
   ↓
8. If PERMIT: Forward request to target application
   If DENY: Return 403 Forbidden
   ↓
9. Return response to client

PIP Integration Data Flow

Data from external sources (identity providers, HR, databases) is synced into the Control Plane, then distributed to bouncers so policies can use it at evaluation time.

Step-by-step:

1. Admin configures data source in Console
   ↓
2. Control Plane tests connection
   ↓
3. Attributes mapped to policy schema
   ↓
4. Sync scheduled (hourly, daily, real-time)
   ↓
5. At sync time: Fetch data from source
   ↓
6. Transform data to standard format
   ↓
7. Publish to Policy Bridge
   ↓
8. Policy Bridge distributes to all Bouncers
   ↓
9. Bouncers update local policy cache
   ↓
10. Data available in policies immediately
    (data.policy_data.source.type.*)

AI Governance

When the bouncer is configured with LLM routes (AI Pilot), it acts as a Unified Bouncer for both standard API and GenAI traffic:

• Real-time PII redaction: ext_proc masks PII in LLM request bodies (prompts) before sending to OpenAI/Azure, and continues to mask PII in responses for standard API and optionally for LLM responses.
• Model-agnostic routing: The bouncer routes by path and model to OpenAI or Azure OpenAI; OPA controls who can use which model.
• Cost and token tracking: Token rate limiting (e.g. 1k tokens/day per user) via AI Pilot policies; Redis is required for global rate limiting across replicas; an optional local fallback can be documented.
• Prompt guard: Blocking or sanitizing prompts that contain jailbreak phrases (e.g. "ignore all instructions") is implemented in ext_proc.

Traffic flow: Client → Bouncer → (OPA check → PII masking [request for LLM, response for API] → token count / prompt guard for LLM) → LLM provider or target service.

For configuration and AI Pilot settings, see AI Governance.

Deployment Architecture Patterns

Pattern 1: Self-Hosted (Kickstart / Enterprise)

Your Infrastructure (Cloud or On-Premises)
┌───────────────────────────────────────────────┐
│  ┌─────────────┐                              │
│  │   Console   │ ← Users manage policies      │
│  └──────┬──────┘                              │
│         │                                      │
│         ▼                                      │
│  ┌─────────────┐    ┌──────────┐             │
│  │     API     │ ←→ │ Database │             │
│  └──────┬──────┘    └──────────┘             │
│         │                                      │
│         ▼                                      │
│  ┌─────────────┐                              │
│  │ Policy Bridge│                             │
│  └──────┬──────┘                              │
│         │                                      │
│         ▼                                      │
│  ┌─────────────┐    ┌──────────────┐         │
│  │ Bouncer(s)  │ →  │ Your Apps    │         │
│  └─────────────┘    └──────────────┘         │
└───────────────────────────────────────────────┘

Use Case: Complete control, data sovereignty, on-premises Benefits: Full control, no external dependencies Deployment: Docker Compose or Kubernetes

Pattern 2: High-availability Control Plane (single organization)

Use the same customer-hosted model as Pattern 1 with multiple availability zones, replicated data stores, and regional Bouncer fleets. There is no vendor-operated Control Plane product tier—the Control Plane always runs in infrastructure you operate.

Use Case: Production HA within your estate
Deployment: Kubernetes + Helm (see Custom deployment)

(Historical diagrams that showed a hosted “hybrid” console are retired; all current SKUs are documented under Licensing and deployment options.)

Pattern 3: Multi-Region Enterprise

Region 1 (Primary)        Region 2 (Replica)       Region 3 (Replica)
┌──────────────────┐      ┌──────────────────┐     ┌──────────────────┐
│ Control Plane    │      │ Control Plane    │     │ Control Plane    │
│ - Console x3     │      │ - Console x3     │     │ - Console x3     │
│ - API x5         │◄────►│ - API x5         │◄───►│ - API x5         │
│ - Policy Bridge x3│Sync │ - Policy Bridge x3│Sync │ - Policy Bridge x3│
│ - DB Primary     │      │ - DB Replica     │     │ - DB Replica     │
│ - Bouncer x10    │      │ - Bouncer x10    │     │ - Bouncer x10    │
└──────────────────┘      └──────────────────┘     └──────────────────┘

Use Case: Global deployment, low latency, disaster recovery Benefits: Geographic distribution, fault tolerance Deployment: Kubernetes multi-cluster

Security Architecture

Defense in Depth

Layer 1: Network Security
├─ Firewall rules
├─ VPC/VNET isolation
├─ Security groups
└─ DDoS protection

Layer 2: Transport Security
├─ TLS 1.3 encryption
├─ Certificate management
├─ mTLS (optional)
└─ Perfect forward secrecy

Layer 3: Authentication
├─ SAML/SSO
├─ OAuth 2.0
├─ MFA
└─ Session management

Layer 4: Authorization
├─ Policy-based access control
├─ Context-aware decisions
├─ Real-time enforcement
└─ Audit logging

Layer 5: Data Security
├─ Encryption at rest
├─ Encryption in transit
├─ Secrets management
└─ Data minimization

Layer 6: Application Security
├─ Input validation
├─ SQL injection prevention
├─ XSS protection
└─ CSRF protection

Layer 7: Monitoring
├─ Security event detection
├─ Anomaly detection
├─ Audit logging
└─ Incident response

Network Architecture

Cloud-Agnostic Network Design:

┌─────────────────────────────────────────────────────────────┐
│                     Public Zone                             │
│                                                             │
│  ┌────────────────┐        ┌────────────────┐              │
│  │ Load Balancer  │        │ Load Balancer  │              │
│  │ (Console/API)  │        │ (Bouncer)      │              │
│  └───────┬────────┘        └───────┬────────┘              │
└──────────┼─────────────────────────┼─────────────────────────┘
           │                         │
┌──────────┼─────────────────────────┼─────────────────────────┐
│          │    Application Zone     │                         │
│          ▼                         ▼                         │
│  ┌──────────────┐         ┌──────────────┐                  │
│  │   Console    │         │  Bouncer(s)  │                  │
│  │   API        │         │              │                  │
│  │ Policy Bridge │        │              │                  │
│  └──────┬───────┘         └──────┬───────┘                  │
└─────────┼──────────────────────────┼──────────────────────────┘
          │                          │
┌─────────┼──────────────────────────┼──────────────────────────┐
│         │      Data Zone           │                          │
│         ▼                          ▼                          │
│  ┌──────────────┐         ┌──────────────┐                   │
│  │  Database    │         │  Target      │                   │
│  │  (PostgreSQL)│         │  Application │                   │
│  │              │         │              │                   │
│  │  Cache       │         │              │                   │
│  │  (Redis)     │         │              │                   │
│  └──────────────┘         └──────────────┘                   │
└──────────────────────────────────────────────────────────────┘

Component Interaction

Component Communication

Control Plane (Console ↔ API):

• Protocol: HTTPS
• Auth: JWT tokens
• Pattern: REST API
• Latency: < 100ms

API ↔ Database:

• Protocol: PostgreSQL wire protocol (TLS)
• Auth: Username/password
• Connection pool: 20-50 per API instance
• Latency: < 10ms

API ↔ Redis:

• Protocol: Redis protocol (TLS optional)
• Auth: Password
• Connection pool: 10-20 per API instance
• Latency: < 5ms

Policy Bridge ↔ Bouncers:

• Protocol: WebSocket (WSS)
• Auth: Client tokens
• Pattern: Pub/Sub
• Latency: < 100ms for updates

Bouncer ↔ Target App:

• Protocol: HTTP/HTTPS
• Auth: Preserves original auth
• Pattern: Reverse proxy
• Latency: Minimal overhead (< 10ms)

Scalability Architecture

Horizontal Scaling

Stateless Components (scale easily):

• Policy Administration Console: 3-10 replicas
• Policy Administration API: 5-20 replicas
• Bouncer/PEP: 10-100+ replicas
• Policy Bridge: 2-3 replicas (leader election)

Stateful Components (scale with replication):

• PostgreSQL: Primary + 1-2 read replicas
• Redis: Cluster mode (6+ nodes) or Sentinel (3+ nodes)

Vertical Scaling

Resource Recommendations:

Cloud-Agnostic Design

Control Core is designed to run on any infrastructure:

Supported Platforms

Public Cloud:

• AWS (EKS, ECS, EC2)
• Google Cloud (GKE, Cloud Run, GCE)
• Microsoft Azure (AKS, Container Instances, VMs)
• DigitalOcean (Kubernetes, Droplets)
• Linode (LKE, Compute Instances)
• Oracle Cloud
• IBM Cloud
• Alibaba Cloud

Private Cloud:

• VMware vSphere
• OpenStack
• Proxmox

On-Premises:

• Bare metal servers
• Virtual machines
• Private Kubernetes clusters

Hybrid:

• Mix of cloud and on-premises
• Multi-cloud deployments
• Edge computing

Cloud Provider Services

Equivalent Services Across Clouds:

Control Core works with all of these or self-hosted alternatives.

High Availability Architecture

Component Redundancy

For 99.9% uptime:

• Console: 3 replicas across availability zones
• API: 3+ replicas with load balancing
• Bouncer: 5+ replicas with health checks
• Policy Bridge: 3 replicas with leader election
• Database: Primary + 2 read replicas with auto-failover
• Redis: 6-node cluster or Sentinel with 3 nodes

For 99.99% uptime:

• Multi-region deployment
• Cross-region database replication
• Global load balancing
• Automated failover

Failure Scenarios

Bouncer Failure:

• Impact: Requests to that Bouncer fail
• Mitigation: Load balancer routes to healthy Bouncers
• Recovery Time: Immediate (< 1 second)

API Failure:

• Impact: Cannot create/modify policies (enforcement continues)
• Mitigation: Multiple API replicas
• Recovery Time: Immediate (< 1 second)

Policy Bridge Failure:

• Impact: Policy updates delayed (enforcement continues with cached policies; bouncers use last-known policies)
• Mitigation: Leader election, automatic failover
• Recovery Time: 10-30 seconds

Database Failure:

• Impact: Cannot modify policies (enforcement continues)
• Mitigation: Automatic failover to replica
• Recovery Time: 30-60 seconds

Complete Region Failure:

• Impact: Regional services unavailable
• Mitigation: DNS failover to secondary region
• Recovery Time: 2-5 minutes

Performance Architecture

Caching Strategy

Three-Level Caching:

Level 1: Bouncer Policy Cache
├─ What: Compiled policies
├─ TTL: 5-15 minutes
├─ Hit Rate: 90-95%
└─ Impact: Fastest evaluation

Level 2: Bouncer Decision Cache
├─ What: Authorization decisions
├─ TTL: 1-5 minutes
├─ Hit Rate: 80-90%
└─ Impact: No policy evaluation needed

Level 3: PIP Data Cache (Redis)
├─ What: External data from integrations
├─ TTL: 5-60 minutes (based on sensitivity)
├─ Hit Rate: 85-95%
└─ Impact: No external API calls

Performance Optimization

Latency Targets:

• Policy evaluation: < 50ms (P95)
• Total request overhead: < 100ms (P95)
• Policy sync propagation: < 30 seconds
• PIP data sync: < 60 seconds

Throughput Targets:

• Per Bouncer: 500-1,000 req/sec
• 10 Bouncers: 5,000-10,000 req/sec
• 100 Bouncers: 50,000-100,000 req/sec

Disaster Recovery Architecture

Backup Strategy

What to Backup:

• PostgreSQL database (policies, users, audit logs)
• Configuration files
• Secrets (encrypted)
• Custom policies from Git

Backup Frequency:

• Database: Every 6 hours
• Configuration: Daily
• Full system: Weekly
• Continuous: Transaction logs

Retention:

• Daily backups: 30 days
• Weekly backups: 90 days
• Monthly backups: 7 years (compliance)

Recovery Objectives

RTO (Recovery Time Objective):

• Kickstart (single footprint): < 4 hours
• Custom (HA deployment): < 1 hour with proper redundancy and runbooks

RPO (Recovery Point Objective):

• Kickstart (single footprint): < 6 hours
• Custom (HA deployment): < 15 minutes with WAL archiving and replicated state

Integration Architecture

PIP Integration Pattern

External Systems           Control Core
┌──────────────┐          ┌─────────────────┐
│   Okta       │          │                 │
│   (OAuth)    │ ←───────→│  PIP Service    │
└──────────────┘          │  (API Layer)    │
                          └────────┬────────┘
┌──────────────┐                  │
│  Workday     │                  │
│  (API Key)   │ ←────────────────┤
└──────────────┘                  │
                                  ▼
┌──────────────┐          ┌─────────────────┐
│  Database    │          │  Transform &    │
│  (PostgreSQL)│ ←───────→│  Normalize      │
└──────────────┘          └────────┬────────┘
                                  │
                                  ▼
                          ┌─────────────────┐
                          │  Policy Bridge  │
                          │  (Distribute)   │
                          └────────┬────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
              ┌─────────┐   ┌─────────┐   ┌─────────┐
              │Bouncer 1│   │Bouncer 2│   │Bouncer N│
              └─────────┘   └─────────┘   └─────────┘

Webhook Integration Pattern

External Event             Control Core              Action
┌──────────────┐          ┌─────────────────┐     ┌──────────────┐
│  Okta        │          │                 │     │              │
│ User updated │ ────────→│ Webhook Handler │────→│ Update User  │
└──────────────┘  POST    └─────────┬───────┘     │ Context      │
                                    │             └──────────────┘
┌──────────────┐                    │             ┌──────────────┐
│ Policy       │                    │             │ Send to      │
│ Decision Made│ ←───────────────── ┤             │ External     │
└──────────────┘  Trigger Action    │             │ System       │
                                    │             └──────────────┘
                                    ▼
                          ┌─────────────────┐
                          │ Policy Bridge   │
                          └─────────────────┘

Deployment Considerations

Choosing Cloud Provider

Considerations:

• Cost: Compare pricing across providers
• Existing Infrastructure: Use where you already have presence
• Geographic Requirements: Data residency, latency
• Compliance: Provider certifications
• Features: Specific cloud services needed

Control Core works equally well on all major clouds - choose based on your needs, not limitations.

Kubernetes vs Docker Compose

Use Kubernetes when:

• Production deployments
• Need auto-scaling
• Multi-region requirements
• High availability required
• Enterprise scale (> 100 users)

Use Docker Compose when:

• Development/testing
• Small deployments (< 50 users)
• Simple infrastructure
• Quick setup needed
• Learning/evaluation

Troubleshooting

For detailed steps, see the Troubleshooting Guide.

Next Steps

• Kickstart Deployment: Pilot stack with Docker Compose (customer infrastructure)
• Licensing and deployment options: Kickstart vs Custom commercial model
• Enterprise Deployment: Production Kubernetes (Custom tier operations)
• Enterprise Architecture: Advanced enterprise patterns
• Security Best Practices: Secure your deployment

Control Core's cloud-agnostic architecture ensures you're never locked into a single provider and can deploy wherever your business requires.