---
title: "Map the System"
url: "https://docs.caracal.run/architecture/system-topology/"
markdown_url: "https://docs.caracal.run/markdown/architecture/system-topology.md"
description: "Runtime topology for Caracal services, dependencies, and external clients."
page_type: "architecture"
concepts: []
requires: []
---

# Map the System

Canonical URL: https://docs.caracal.run/architecture/system-topology/
Markdown URL: https://docs.caracal.run/markdown/architecture/system-topology.md
Description: Runtime topology for Caracal services, dependencies, and external clients.
Page type: architecture
Concepts: none
Requires: none

---

Caracal has six primary HTTP services plus Postgres and Redis.

## Topology

```mermaid
flowchart TB
  subgraph Clients
    Console[Console]
    SDK[SDKs and caracal run]
    ResourceClient[Protected-resource clients]
    Automation[Control/Admin automation]
  end

  subgraph Caracal
    API[API :3000]
    STS[STS :8080]
    Gateway[Gateway :8081]
    Audit[Audit :9090]
    Coordinator[Coordinator :4000]
    Control[Control plugin in API, optional]
  end

  Postgres[(Postgres)]
  Redis[(Redis Streams)]
  Upstream[Protected upstreams]

  Console --> API
  Console --> Coordinator
  SDK --> STS
  ResourceClient --> Gateway
  Automation --> Control
  Control --> API
  Gateway --> Upstream
  API --> Postgres
  STS --> Postgres
  Gateway --> Postgres
  Audit --> Postgres
  Coordinator --> Postgres
  API --> Redis
  STS --> Redis
  Gateway --> Redis
  Audit --> Redis
  Coordinator --> Redis
```

## Service Responsibilities

| Service | Responsibility |
| --- | --- |
| API | Zones, applications, providers, resources, policies, policy sets, grants, step-up challenges, admin audit, and API outbox. |
| STS | OAuth token exchange, mandate issuance, policy evaluation, JWKS, step-up status, policy simulation, signing-key rotation internals. |
| Gateway | Protected reverse proxy, inbound mandate verification, per-request STS exchange, SSRF guard, revocation checks, audit replay. |
| Audit | Redis audit ingestion, DLQ, tamper checks, retention, search, metrics. |
| Coordinator | Agent sessions, agent services, delegations, invocations, sweeper jobs, Coordinator outbox. |
| Control | Optional remote management invoke endpoint gated by token auth, replay protection, rate limiting, and runtime gate file. |

## Deployment Shapes

| Shape | Source |
| --- | --- |
| Local development | `infra/docker/docker-compose.yml` through `caracal up`. |
| Self-hosted Compose | `infra/docker/runtime-compose.yml`. |
| Kubernetes | `infra/helm/caracal`. |

## Next Step

Use [Exchange Tokens](/architecture/token-exchange-flow/) to follow how workloads receive scoped mandates.

## Related Pages

- [Understand Services](/services/)
- [Deploy with Docker Compose](/operations/docker-compose/)
- [Deploy with Helm](/operations/kubernetes-helm/)