# rayen-mansouri/indaba architecture

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

- Interactive diagram: https://gitdiagram.com/rayen-mansouri/indaba
- Repository: https://github.com/rayen-mansouri/indaba

## Overview

SENTINEL is an offline simulator defense that intercepts agent-proposed tool actions at a guarded boundary. The principal workflow runs a scenario through an agent and model, evaluates proposed actions with a defense, executes permitted actions against synthetic domain tools and world state, then records and grades the run. The graph also preserves the documented baseline defenses, domain capabilities, replay/evaluation, and optional HTTP defense surface. Relationships are limited to README statements and indexed or excerpted references; domain-tool wiring and several supporting subsystem internals were not sampled.

Main entry points: [`src/sentinel/evaluator/runner.py`](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/evaluator/runner.py) (Run evaluator), [`src/sentinel/cli.py`](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/cli.py) (CLI), [`src/sentinel/agent/reference.py`](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/agent/reference.py) (Reference agent), [`src/sentinel/firewall/runtime.py`](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/firewall/runtime.py) (Guarded firewall)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run orchestration"]
  node_cli["CLI<br/>[cli.py]"]
  node_scenario["Scenario loader<br/>[scenario.py]"]
  node_runner["Run evaluator<br/>[runner.py]"]
  node_agent["Reference agent<br/>[reference.py]"]
  node_actions["Action contract<br/>[actions.py]"]
end

subgraph group_guard["Action defense"]
  node_firewall["Guarded firewall<br/>[runtime.py]"]
  node_firewallrules["Firewall policy gates<br/>[gates.py]"]
  node_manifest["Tool manifest<br/>[toolspecs.py]"]
  node_provenance["Provenance lineage<br/>[provenance.py]"]
end

subgraph group_sim["Synthetic simulator"]
  node_gateway["Tool gateway<br/>[gateway.py]"]
  node_tools["Tool implementations<br/>[base.py]"]
  node_domains["Domain tools"]
  node_state[("World state<br/>[state.py]")]
end

subgraph group_eval["Evaluation and evidence"]
  node_events["Event trace<br/>[events.py]"]
  node_storage[("Run artifacts<br/>[runs.py]")]
  node_grading["Metrics and graders"]
  node_replay["Trace replay<br/>[replay.py]"]
  node_attackers["Attack baselines"]
end

subgraph group_integrations["Model and defense adapters"]
  node_model["Model adapters<br/>[base.py]"]
  node_defense["Defense interface<br/>[interface.py]"]
  node_httpdefense["HTTP defense client<br/>[client.py]"]
  node_baselines["Defense baselines"]
end

node_user(("Operator"))
node_service["Defense service"]

node_user -->|"runs"| node_cli
node_cli -->|"loads"| node_scenario
node_cli -->|"starts"| node_runner
node_runner -->|"uses"| node_scenario
node_runner -->|"constructs"| node_agent
node_agent -->|"queries"| node_model
node_agent -->|"requests decision"| node_defense
node_agent -->|"executes via"| node_gateway
node_agent -->|"proposes"| node_actions
node_httpdefense -->|"posts decisions"| node_service
node_firewall -->|"evaluates gates"| node_firewallrules
node_firewall -->|"reads manifest"| node_manifest
node_firewall -->|"tracks lineage"| node_provenance
node_firewall -->|"guards execution"| node_gateway
node_gateway -->|"dispatches tools"| node_tools
node_tools -->|"reads and writes"| node_state
node_runner -->|"records run"| node_events
node_storage -->|"stores traces"| node_events
node_runner -->|"writes artifacts"| node_storage
node_runner -->|"grades outcomes"| node_grading
node_cli -->|"replays traces"| node_replay
node_runner -->|"schedules attacks"| node_attackers
node_cli -->|"selects defense"| node_baselines
node_domains -.->|"registered tools"| node_gateway

click node_cli "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/cli.py"
click node_scenario "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/scenario.py"
click node_runner "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/evaluator/runner.py"
click node_agent "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/agent/reference.py"
click node_actions "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/actions.py"
click node_model "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/models/base.py"
click node_defense "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/defenses/interface.py"
click node_httpdefense "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/defenses/client.py"
click node_firewall "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/firewall/runtime.py"
click node_firewallrules "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/firewall/gates.py"
click node_manifest "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/firewall/toolspecs.py"
click node_provenance "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/provenance.py"
click node_gateway "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/tools/gateway.py"
click node_tools "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/tools/base.py"
click node_domains "https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/domains"
click node_state "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/state.py"
click node_events "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/events.py"
click node_storage "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/storage/runs.py"
click node_grading "https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/evaluator"
click node_replay "https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/evaluator/replay.py"
click node_baselines "https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/defenses/baselines"
click node_attackers "https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/attackers"

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_cli,node_scenario,node_runner,node_agent,node_actions toneBlue
class node_firewall,node_firewallrules,node_manifest,node_provenance toneAmber
class node_gateway,node_tools,node_domains,node_state toneMint
class node_events,node_storage,node_grading,node_replay,node_attackers toneRose
class node_model,node_defense,node_httpdefense,node_baselines,node_user,node_service toneIndigo
```

## Components

### Run orchestration

- [CLI](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/cli.py): `src/sentinel/cli.py`
- [Scenario loader](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/scenario.py): `src/sentinel/core/scenario.py`
- [Run evaluator](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/evaluator/runner.py): `src/sentinel/evaluator/runner.py`
- [Reference agent](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/agent/reference.py): `src/sentinel/agent/reference.py`
- [Action contract](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/actions.py): `src/sentinel/core/actions.py`

### Action defense

- [Guarded firewall](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/firewall/runtime.py): `src/sentinel/firewall/runtime.py`
- [Firewall policy gates](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/firewall/gates.py): `src/sentinel/firewall/gates.py`
- [Tool manifest](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/firewall/toolspecs.py): `src/sentinel/firewall/toolspecs.py`
- [Provenance lineage](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/provenance.py): `src/sentinel/core/provenance.py`

### Synthetic simulator

- [Tool gateway](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/tools/gateway.py): `src/sentinel/tools/gateway.py`
- [Tool implementations](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/tools/base.py): `src/sentinel/tools/base.py`
- [Domain tools](https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/domains): `src/sentinel/domains`
- [World state](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/state.py): `src/sentinel/core/state.py`

### Evaluation and evidence

- [Event trace](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/core/events.py): `src/sentinel/core/events.py`
- [Run artifacts](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/storage/runs.py): `src/sentinel/storage/runs.py`
- [Metrics and graders](https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/evaluator): `src/sentinel/evaluator`
- [Trace replay](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/evaluator/replay.py): `src/sentinel/evaluator/replay.py`
- [Attack baselines](https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/attackers): `src/sentinel/attackers`

### Model and defense adapters

- [Model adapters](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/models/base.py): `src/sentinel/models/base.py`
- [Defense interface](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/defenses/interface.py): `src/sentinel/defenses/interface.py`
- [HTTP defense client](https://github.com/rayen-mansouri/indaba/blob/main/src/sentinel/defenses/client.py): `src/sentinel/defenses/client.py`
- [Defense baselines](https://github.com/rayen-mansouri/indaba/tree/main/src/sentinel/defenses/baselines): `src/sentinel/defenses/baselines`

### Other components

- **Operator**
- **Defense service**

## Connections

- Operator → CLI: runs (evidence: `README.md`)
- CLI → Scenario loader: loads (evidence: `src/sentinel/cli.py`)
- CLI → Run evaluator: starts (evidence: `src/sentinel/cli.py`)
- Run evaluator → Scenario loader: uses (evidence: `src/sentinel/evaluator/runner.py`)
- Run evaluator → Reference agent: constructs (evidence: `src/sentinel/evaluator/runner.py`)
- Reference agent → Model adapters: queries (evidence: `src/sentinel/agent/reference.py`)
- Reference agent → Defense interface: requests decision (evidence: `src/sentinel/agent/reference.py`)
- Reference agent → Tool gateway: executes via (evidence: `src/sentinel/agent/reference.py`)
- Reference agent → Action contract: proposes (evidence: `src/sentinel/agent/reference.py`)
- HTTP defense client → Defense service: posts decisions (evidence: `src/sentinel/defenses/client.py`)
- Guarded firewall → Firewall policy gates: evaluates gates (evidence: `src/sentinel/firewall/runtime.py`)
- Guarded firewall → Tool manifest: reads manifest (evidence: `src/sentinel/firewall/runtime.py`)
- Guarded firewall → Provenance lineage: tracks lineage (evidence: `src/sentinel/firewall/runtime.py`)
- Guarded firewall → Tool gateway: guards execution (evidence: `src/sentinel/firewall/runtime.py`)
- Tool gateway → Tool implementations: dispatches tools (evidence: `src/sentinel/tools/gateway.py`)
- Tool implementations → World state: reads and writes (evidence: `src/sentinel/tools/base.py`)
- Run evaluator → Event trace: records run (evidence: `src/sentinel/evaluator/runner.py`)
- Run artifacts → Event trace: stores traces (evidence: `src/sentinel/storage/runs.py`)
- Run evaluator → Run artifacts: writes artifacts (evidence: `src/sentinel/cli.py`)
- Run evaluator → Metrics and graders: grades outcomes (evidence: `src/sentinel/evaluator/runner.py`)
- CLI → Trace replay: replays traces (evidence: `src/sentinel/cli.py`)
- Run evaluator → Attack baselines: schedules attacks (evidence: `src/sentinel/evaluator/runner.py`)
- CLI → Defense baselines: selects defense (evidence: `src/sentinel/cli.py`)
- Domain tools → Tool gateway: registered tools