# chrismsmr-celcom/cerbere-ag architecture

> Architecture diagram of the GitHub repository chrismsmr-celcom/cerbere-ag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chrismsmr-celcom/cerbere-ag
- Repository: https://github.com/chrismsmr-celcom/cerbere-ag

## Overview

Cerbère is an AI-agent runtime security and observability control plane. Its principal workflow wraps an agent’s model and tool calls in the SDK, evaluates security and policy checks, then reports spans to the Collector for storage, APIs, and dashboard views. The graph also preserves identity and audit capabilities and the documented MCP integration. Detection details and some API routes are documented or indexed but not fully sampled, so those links are limited to supported references.

Main entry points: [`agentguard/policy.py`](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/policy.py) (SDK policy checks), [`agentguard/sdk.py`](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/sdk.py) (AgentGuard SDK), [`collector/app.py`](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/app.py) (Collector application), [`collector/db.py`](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/db.py) (Collector database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_sdk["AgentGuard SDK<br/>[sdk.py]"]
  node_runtime_checks["Runtime checks<br/>[runtime.py]"]
  node_taint["Taint tracking<br/>[taint.py]"]
  node_models["Security models<br/>[models.py]"]
end

subgraph group_decisions["Security decisions"]
  node_policy["SDK policy checks<br/>[policy.py]"]
  node_rules["Rules and patterns<br/>[patterns.py]"]
  node_normalizer["Input normalization<br/>[normalizer.py]"]
  node_ml["ML detection<br/>[agentguard_ml.py]"]
  node_judge["LLM judge<br/>[judges.py]"]
  node_decision_engine["Unified decision engine<br/>[decision_engine.py]"]
  node_risk["Risk scoring<br/>[risk_engine.py]"]
  node_policy_engine["Policy engine<br/>[engine.py]"]
end

subgraph group_collector["Collector and observability"]
  node_collector_app["Collector application<br/>[app.py]"]
  node_api["Collector API<br/>[__init__.py]"]
  node_span_ingest["Span ingestion<br/>[spans.py]"]
  node_db[("Collector database<br/>[db.py]")]
  node_dashboard["Dashboard views<br/>[dashboard.py]"]
  node_metrics["Metrics API<br/>[metrics.py]"]
end

subgraph group_identity["Identity and audit"]
  node_identity_routes["Identity management<br/>[identity_routes.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_audit_routes["Audit API<br/>[audit_routes.py]"]
  node_audit_log[("Immutable audit log<br/>[audit.py]")]
end

subgraph group_integrations["Agent integrations"]
  node_mcp_server["MCP server<br/>[mcp_server.py]"]
end

node_agent(("AI agent"))
node_collector_service["Collector service"]
node_dashboard_user(("Dashboard user"))

node_agent -->|"invokes"| node_sdk
node_sdk -->|"checks calls"| node_runtime_checks
node_sdk -->|"evaluates policy"| node_policy
node_sdk -->|"tracks taint"| node_taint
node_runtime_checks -->|"uses models"| node_models
node_policy -->|"uses models"| node_models
node_policy -->|"checks patterns"| node_rules
node_policy -->|"normalizes input"| node_normalizer
node_policy -->|"classifies input"| node_ml
node_policy -.->|"judges ambiguity"| node_judge
node_decision_engine -->|"scores risk"| node_risk
node_policy_engine -.->|"enforces capabilities"| node_policy
node_sdk -->|"sends spans"| node_collector_service
node_collector_service -.->|"serves requests"| node_collector_app
node_collector_app -->|"registers routes"| node_api
node_api -->|"routes spans"| node_span_ingest
node_span_ingest -->|"writes events"| node_db
node_dashboard -->|"reads data"| node_db
node_metrics -->|"reads metrics"| node_db
node_dashboard_user -.->|"views activity"| node_dashboard
node_collector_app -->|"registers auth"| node_auth
node_collector_app -->|"registers routes"| node_identity_routes
node_identity_routes -->|"resolves identity"| node_auth
node_identity_routes -->|"stores identities"| node_db
node_collector_app -->|"registers routes"| node_audit_routes
node_audit_routes -->|"requires auth"| node_auth
node_audit_routes -->|"queries audit"| node_audit_log
node_audit_routes -->|"checks database"| node_db
node_agent -.->|"uses MCP"| node_mcp_server
node_mcp_server -->|"imports SDK"| node_sdk

click node_sdk "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/sdk.py"
click node_runtime_checks "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/runtime.py"
click node_taint "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/taint.py"
click node_models "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/models.py"
click node_policy "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/policy.py"
click node_rules "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/patterns.py"
click node_normalizer "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/normalizer.py"
click node_ml "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard_ml.py"
click node_judge "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/judges.py"
click node_decision_engine "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/decision_engine.py"
click node_risk "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/risk_engine.py"
click node_policy_engine "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/policy/engine.py"
click node_collector_app "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/app.py"
click node_api "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/__init__.py"
click node_span_ingest "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/spans.py"
click node_db "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/db.py"
click node_dashboard "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/dashboard.py"
click node_metrics "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/metrics.py"
click node_identity_routes "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/identity_routes.py"
click node_auth "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/auth.py"
click node_audit_routes "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/audit_routes.py"
click node_audit_log "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/audit.py"
click node_mcp_server "https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/mcp/mcp_server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_runtime_checks,node_taint,node_models,node_dashboard_user toneBlue
class node_policy,node_rules,node_normalizer,node_ml,node_judge,node_decision_engine,node_risk,node_policy_engine toneAmber
class node_collector_app,node_api,node_span_ingest,node_db,node_dashboard,node_metrics toneMint
class node_identity_routes,node_auth,node_audit_routes,node_audit_log toneRose
class node_mcp_server,node_agent,node_collector_service toneIndigo
```

## Components

### Agent runtime

- [AgentGuard SDK](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/sdk.py): `agentguard/sdk.py`
- [Runtime checks](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/runtime.py): `agentguard/runtime.py`
- [Taint tracking](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/taint.py): `agentguard/taint.py`
- [Security models](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/models.py): `agentguard/models.py`

### Security decisions

- [SDK policy checks](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/policy.py): `agentguard/policy.py`
- [Rules and patterns](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/patterns.py): `agentguard/patterns.py`
- [Input normalization](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard/normalizer.py): `agentguard/normalizer.py`
- [ML detection](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/agentguard_ml.py): `agentguard_ml.py`
- [LLM judge](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/judges.py): `judges.py`
- [Unified decision engine](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/decision_engine.py): `decision_engine.py`
- [Risk scoring](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/risk_engine.py): `risk_engine.py`
- [Policy engine](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/policy/engine.py): `policy/engine.py`

### Collector and observability

- [Collector application](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/app.py): `collector/app.py`
- [Collector API](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/__init__.py): `collector/api/__init__.py`
- [Span ingestion](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/spans.py): `collector/api/spans.py`
- [Collector database](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/db.py): `collector/db.py`
- [Dashboard views](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/dashboard.py): `collector/api/dashboard.py`
- [Metrics API](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/api/metrics.py): `collector/api/metrics.py`

### Identity and audit

- [Identity management](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/identity_routes.py): `collector/identity_routes.py`
- [Authentication](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/auth.py): `collector/auth.py`
- [Audit API](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/collector/audit_routes.py): `collector/audit_routes.py`
- [Immutable audit log](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/audit.py): `audit.py`

### Agent integrations

- [MCP server](https://github.com/chrismsmr-celcom/cerbere-ag/blob/main/mcp/mcp_server.py): `mcp/mcp_server.py`

### Other components

- **AI agent**
- **Collector service**
- **Dashboard user**

## Connections

- AI agent → AgentGuard SDK: invokes (evidence: `README.md`)
- AgentGuard SDK → Runtime checks: checks calls (evidence: `agentguard/sdk.py`)
- AgentGuard SDK → SDK policy checks: evaluates policy (evidence: `agentguard/sdk.py`)
- AgentGuard SDK → Taint tracking: tracks taint (evidence: `agentguard/sdk.py`)
- Runtime checks → Security models: uses models (evidence: `agentguard/runtime.py`)
- SDK policy checks → Security models: uses models (evidence: `agentguard/policy.py`)
- SDK policy checks → Rules and patterns: checks patterns (evidence: `agentguard/policy.py`)
- SDK policy checks → Input normalization: normalizes input (evidence: `agentguard/policy.py`)
- SDK policy checks → ML detection: classifies input (evidence: `agentguard/policy.py`)
- SDK policy checks → LLM judge: judges ambiguity (evidence: `README.md`)
- Unified decision engine → Risk scoring: scores risk (evidence: `decision_engine.py`)
- Policy engine → SDK policy checks: enforces capabilities
- AgentGuard SDK → Collector service: sends spans (evidence: `agentguard/sdk.py`)
- Collector service → Collector application: serves requests
- Collector application → Collector API: registers routes (evidence: `collector/app.py`)
- Collector API → Span ingestion: routes spans (evidence: `collector/api/__init__.py`)
- Span ingestion → Collector database: writes events (evidence: `collector/api/spans.py`)
- Dashboard views → Collector database: reads data (evidence: `collector/api/dashboard.py`)
- Metrics API → Collector database: reads metrics (evidence: `collector/api/metrics.py`)
- Dashboard user → Dashboard views: views activity (evidence: `README.md`)
- Collector application → Authentication: registers auth (evidence: `collector/app.py`)
- Collector application → Identity management: registers routes (evidence: `collector/app.py`)
- Identity management → Authentication: resolves identity (evidence: `collector/identity_routes.py`)
- Identity management → Collector database: stores identities (evidence: `collector/identity_routes.py`)
- Collector application → Audit API: registers routes (evidence: `collector/app.py`)
- Audit API → Authentication: requires auth (evidence: `collector/audit_routes.py`)
- Audit API → Immutable audit log: queries audit (evidence: `collector/audit_routes.py`)
- Audit API → Collector database: checks database (evidence: `collector/audit_routes.py`)
- AI agent → MCP server: uses MCP (evidence: `README.md`)
- MCP server → AgentGuard SDK: imports SDK (evidence: `mcp/mcp_server.py`)
