# secureagentics/adrian architecture

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

- Interactive diagram: https://gitdiagram.com/secureagentics/adrian
- Repository: https://github.com/secureagentics/adrian

## Overview

Adrian is a runtime security monitor and control layer for AI agents. Its principal flow instruments agent activity and reasoning, sends captured events to a backend classifier, and returns verdicts that can notify, block, or pause execution for human review. The repository also includes a dashboard, persistent event and review data, alerting, Python and TypeScript SDKs, and a Claude Code integration. The README documents the overall stack and capabilities; sampled source confirms selected event, review, and SDK behaviors, while several subsystem links remain documented rather than source-verified.

Main entry points: [`backend/internal/ws/handler.go`](https://github.com/secureagentics/adrian/blob/main/backend/internal/ws/handler.go) (WebSocket intake), [`backend/internal/api/routes.go`](https://github.com/secureagentics/adrian/blob/main/backend/internal/api/routes.go) (Dashboard API), [`sdk/python/adrian/handler.py`](https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/handler.py) (Python instrumentation), [`backend/internal/engine/engine.go`](https://github.com/secureagentics/adrian/blob/main/backend/internal/engine/engine.go) (Runtime classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Agent capture"]
  node_py_instrument["Python instrumentation<br/>[handler.py]"]
  node_py_context["Agent context<br/>[context.py]"]
  node_paired_event["Paired events<br/>[types.py]"]
  node_py_transport["Python transport<br/>[ws.py]"]
  node_ts_sdk["TypeScript SDK<br/>[handler.ts]"]
end

subgraph group_analysis["Classification"]
  node_classifier["Runtime classifier<br/>[engine.go]"]
end

subgraph group_backend["Backend services"]
  node_backend_ws["WebSocket intake<br/>[handler.go]"]
  node_api["Dashboard API<br/>[routes.go]"]
  node_store[("Persistent state<br/>[store.go]")]
  node_database[("SQLite database<br/>[db.go]")]
  node_reviews["Human review queue"]
  node_notifications["Alert dispatch<br/>[dispatcher.go]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Security dashboard<br/>[page.tsx]"]
  node_review_ui["Review controls<br/>[page.tsx]"]
end

subgraph group_integrations["SDK integrations"]
  node_claude_plugin["Claude Code plugin<br/>[agent.py]"]
  node_pii_redaction["PII redaction<br/>[_engine.py]"]
end

node_agent(("AI agent"))
node_human(("Security operator"))
node_model_service["LLM classifier service"]

node_agent -->|"emits activity"| node_py_instrument
node_py_instrument -->|"tracks context"| node_py_context
node_py_instrument -->|"pairs events"| node_paired_event
node_paired_event -.->|"sends events"| node_py_transport
node_agent -->|"captures behavior"| node_ts_sdk
node_agent -->|"captures tool calls"| node_claude_plugin
node_py_instrument -.->|"redacts sensitive data"| node_pii_redaction
node_py_transport -->|"streams events"| node_backend_ws
node_backend_ws -->|"classifies activity"| node_classifier
node_classifier -->|"queries model"| node_model_service
node_backend_ws -->|"records events"| node_store
node_store -.->|"persists state"| node_database
node_classifier -.->|"returns verdicts"| node_backend_ws
node_backend_ws -.->|"delivers verdicts"| node_py_transport
node_api -->|"queries state"| node_store
node_api -->|"resolves reviews"| node_reviews
node_reviews -->|"publishes resolution"| node_backend_ws
node_api -.->|"dispatches alerts"| node_notifications
node_dashboard_ui -.->|"requests data"| node_api
node_human -->|"reviews decisions"| node_review_ui
node_review_ui -.->|"submits decisions"| node_api

click node_py_instrument "https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/handler.py"
click node_py_context "https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/context.py"
click node_paired_event "https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/format/types.py"
click node_py_transport "https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/ws.py"
click node_ts_sdk "https://github.com/secureagentics/adrian/blob/main/sdk/typescript/packages/core/src/handler.ts"
click node_claude_plugin "https://github.com/secureagentics/adrian/blob/main/integrations/claude-code/adrian_cc/agent.py"
click node_pii_redaction "https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/pii/_engine.py"
click node_backend_ws "https://github.com/secureagentics/adrian/blob/main/backend/internal/ws/handler.go"
click node_classifier "https://github.com/secureagentics/adrian/blob/main/backend/internal/engine/engine.go"
click node_api "https://github.com/secureagentics/adrian/blob/main/backend/internal/api/routes.go"
click node_store "https://github.com/secureagentics/adrian/blob/main/backend/internal/store/store.go"
click node_database "https://github.com/secureagentics/adrian/blob/main/backend/internal/db/db.go"
click node_reviews "https://github.com/secureagentics/adrian/blob/main/backend/internal/api/handlers_reviews.go"
click node_notifications "https://github.com/secureagentics/adrian/blob/main/backend/internal/notifications/dispatcher.go"
click node_dashboard_ui "https://github.com/secureagentics/adrian/blob/main/frontend/app/(dashboard)/page.tsx"
click node_review_ui "https://github.com/secureagentics/adrian/blob/main/frontend/app/(dashboard)/reviews/page.tsx"

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_py_instrument,node_py_context,node_paired_event,node_py_transport,node_ts_sdk toneBlue
class node_classifier toneAmber
class node_backend_ws,node_api,node_store,node_database,node_reviews,node_notifications toneMint
class node_dashboard_ui,node_review_ui toneRose
class node_claude_plugin,node_pii_redaction,node_agent,node_human,node_model_service toneIndigo
```

## Components

### Agent capture

- [Python instrumentation](https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/handler.py): `sdk/python/adrian/handler.py`
- [Agent context](https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/context.py): `sdk/python/adrian/context.py`
- [Paired events](https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/format/types.py): `sdk/python/adrian/format/types.py`
- [Python transport](https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/ws.py): `sdk/python/adrian/ws.py`
- [TypeScript SDK](https://github.com/secureagentics/adrian/blob/main/sdk/typescript/packages/core/src/handler.ts): `sdk/typescript/packages/core/src/handler.ts`

### Classification

- [Runtime classifier](https://github.com/secureagentics/adrian/blob/main/backend/internal/engine/engine.go): `backend/internal/engine/engine.go`

### Backend services

- [WebSocket intake](https://github.com/secureagentics/adrian/blob/main/backend/internal/ws/handler.go): `backend/internal/ws/handler.go`
- [Dashboard API](https://github.com/secureagentics/adrian/blob/main/backend/internal/api/routes.go): `backend/internal/api/routes.go`
- [Persistent state](https://github.com/secureagentics/adrian/blob/main/backend/internal/store/store.go): `backend/internal/store/store.go`
- [SQLite database](https://github.com/secureagentics/adrian/blob/main/backend/internal/db/db.go): `backend/internal/db/db.go`
- [Human review queue](https://github.com/secureagentics/adrian/blob/main/backend/internal/api/handlers_reviews.go): `backend/internal/api/handlers_reviews.go`
- [Alert dispatch](https://github.com/secureagentics/adrian/blob/main/backend/internal/notifications/dispatcher.go): `backend/internal/notifications/dispatcher.go`

### Dashboard

- [Security dashboard](https://github.com/secureagentics/adrian/blob/main/frontend/app/(dashboard)/page.tsx): `frontend/app/(dashboard)/page.tsx`
- [Review controls](https://github.com/secureagentics/adrian/blob/main/frontend/app/(dashboard)/reviews/page.tsx): `frontend/app/(dashboard)/reviews/page.tsx`

### SDK integrations

- [Claude Code plugin](https://github.com/secureagentics/adrian/blob/main/integrations/claude-code/adrian_cc/agent.py): `integrations/claude-code/adrian_cc/agent.py`
- [PII redaction](https://github.com/secureagentics/adrian/blob/main/sdk/python/adrian/pii/_engine.py): `sdk/python/adrian/pii/_engine.py`

### Other components

- **AI agent**
- **Security operator**
- **LLM classifier service**

## Connections

- AI agent → Python instrumentation: emits activity
- Python instrumentation → Agent context: tracks context (evidence: `sdk/python/adrian/handler.py`)
- Python instrumentation → Paired events: pairs events (evidence: `sdk/python/adrian/format/types.py`)
- Paired events → Python transport: sends events (evidence: `sdk/python/adrian/ws.py`)
- AI agent → TypeScript SDK: captures behavior
- AI agent → Claude Code plugin: captures tool calls
- Python instrumentation → PII redaction: redacts sensitive data
- Python transport → WebSocket intake: streams events
- WebSocket intake → Runtime classifier: classifies activity (evidence: `backend/internal/ws/handler.go`)
- Runtime classifier → LLM classifier service: queries model
- WebSocket intake → Persistent state: records events (evidence: `backend/internal/ws/handler.go`)
- Persistent state → SQLite database: persists state
- Runtime classifier → WebSocket intake: returns verdicts
- WebSocket intake → Python transport: delivers verdicts
- Dashboard API → Persistent state: queries state
- Dashboard API → Human review queue: resolves reviews (evidence: `backend/internal/api/handlers_reviews.go`)
- Human review queue → WebSocket intake: publishes resolution (evidence: `backend/internal/api/handlers_reviews.go`)
- Dashboard API → Alert dispatch: dispatches alerts
- Security dashboard → Dashboard API: requests data
- Security operator → Review controls: reviews decisions
- Review controls → Dashboard API: submits decisions