# timme33/sentinel architecture

> Architecture diagram of the GitHub repository timme33/sentinel, 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/timme33/sentinel
- Repository: https://github.com/timme33/sentinel

## Overview

Sentinel turns Prometheus alerts into service-centered incidents, schedules investigations after a quiet period, gathers telemetry evidence, and produces validated, evidence-cited reports. The CLI assembles the runtime; detection and investigation can run as separate processes. The README documents the end-to-end flow and major capabilities. Source excerpts confirm alert conversion, polling, incident reconciliation, and selected CLI wiring; investigation internals and the OpenTelemetry Demo integration are represented from README statements and the repository tree rather than inspected source.

Main entry points: [`src/investigation/worker.py`](https://github.com/timme33/sentinel/blob/main/src/investigation/worker.py) (Investigation worker), [`src/cli.py`](https://github.com/timme33/sentinel/blob/main/src/cli.py) (Sentinel CLI), [`src/investigation/repository.py`](https://github.com/timme33/sentinel/blob/main/src/investigation/repository.py) (Investigation jobs), [`src/detection/runner.py`](https://github.com/timme33/sentinel/blob/main/src/detection/runner.py) (Detection runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection"]
  node_alerts["Alert source"]
  node_runner["Detection runner<br/>[runner.py]"]
  node_redreader["RED metrics reader<br/>[red_reader.py]"]
  node_redqueries["RED query builder<br/>[red_queries.py]"]
  node_models["Domain records<br/>[models.py]"]
end

subgraph group_incidents["Incidents and state"]
  node_incidents[("Incident store<br/>[store.py]")]
  node_jobs[("Investigation jobs<br/>[repository.py]")]
  node_sqlite[("SQLite state")]
end

subgraph group_investigation["Investigation"]
  node_worker["Investigation worker<br/>[worker.py]"]
  node_evidence["Evidence collection"]
  node_context["Context builder<br/>[context_builder.py]"]
  node_codex["Codex agent<br/>[codex_agent.py]"]
  node_mcp["FastMCP tools<br/>[mcp_server.py]"]
  node_validator["Report validator"]
end

subgraph group_telemetry["Telemetry"]
  node_jaeger["Jaeger adapter<br/>[jaeger.py]"]
  node_opensearch["OpenSearch adapter<br/>[opensearch.py]"]
  node_promadapter["Prometheus adapter<br/>[prometheus.py]"]
end

node_operator(("Operator"))
node_cli["Sentinel CLI<br/>[cli.py]"]
node_prometheus["Prometheus"]
node_otel["OpenTelemetry Demo"]

node_operator -->|"operates"| node_cli
node_cli -->|"builds"| node_promadapter
node_cli -->|"starts detection"| node_runner
node_cli -->|"starts worker"| node_worker
node_cli -->|"reads and initializes"| node_incidents
node_cli -->|"reads and initializes"| node_jobs
node_runner -->|"polls"| node_alerts
node_alerts -->|"reads firing alerts"| node_promadapter
node_promadapter -->|"queries"| node_prometheus
node_alerts -->|"creates signals"| node_models
node_runner -->|"reconciles snapshot"| node_incidents
node_incidents -->|"persists lifecycle"| node_sqlite
node_runner -->|"schedules jobs"| node_jobs
node_jobs -->|"persists jobs"| node_sqlite
node_runner -.->|"reports metrics"| node_promadapter
node_cli -->|"builds snapshot"| node_redreader
node_redreader -->|"uses queries"| node_redqueries
node_redreader -->|"queries metrics"| node_promadapter
node_otel -->|"exports telemetry"| node_prometheus
node_prometheus -->|"provides alerts"| node_alerts
node_worker -->|"claims and updates"| node_jobs
node_worker -->|"loads incident"| node_incidents
node_worker -->|"collects evidence"| node_evidence
node_evidence -->|"queries traces"| node_jaeger
node_evidence -->|"queries logs"| node_opensearch
node_evidence -->|"stores evidence"| node_jobs
node_worker -->|"builds context"| node_context
node_worker -->|"invokes agent"| node_codex
node_codex -->|"requests evidence"| node_mcp
node_mcp -->|"searches traces"| node_jaeger
node_mcp -->|"searches logs"| node_opensearch
node_worker -->|"validates report"| node_validator
node_validator -->|"persists report"| node_jobs

click node_cli "https://github.com/timme33/sentinel/blob/main/src/cli.py"
click node_otel "https://github.com/timme33/sentinel/blob/main/integration/otel-demo/compose.sentinel.yaml"
click node_alerts "https://github.com/timme33/sentinel/blob/main/src/detection/prometheus_alerts.py"
click node_runner "https://github.com/timme33/sentinel/blob/main/src/detection/runner.py"
click node_redreader "https://github.com/timme33/sentinel/blob/main/src/telemetry/red_reader.py"
click node_redqueries "https://github.com/timme33/sentinel/blob/main/src/telemetry/red_queries.py"
click node_models "https://github.com/timme33/sentinel/blob/main/src/domain/models.py"
click node_incidents "https://github.com/timme33/sentinel/blob/main/src/incidents/store.py"
click node_jobs "https://github.com/timme33/sentinel/blob/main/src/investigation/repository.py"
click node_worker "https://github.com/timme33/sentinel/blob/main/src/investigation/worker.py"
click node_evidence "https://github.com/timme33/sentinel/blob/main/src/investigation/evidence_service.py"
click node_context "https://github.com/timme33/sentinel/blob/main/src/investigation/context_builder.py"
click node_codex "https://github.com/timme33/sentinel/blob/main/src/investigation/codex_agent.py"
click node_mcp "https://github.com/timme33/sentinel/blob/main/src/investigation/mcp_server.py"
click node_validator "https://github.com/timme33/sentinel/blob/main/src/investigation/report_validator.py"
click node_jaeger "https://github.com/timme33/sentinel/blob/main/src/telemetry/jaeger.py"
click node_opensearch "https://github.com/timme33/sentinel/blob/main/src/telemetry/opensearch.py"
click node_promadapter "https://github.com/timme33/sentinel/blob/main/src/telemetry/prometheus.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_alerts,node_runner,node_redreader,node_redqueries,node_models toneBlue
class node_incidents,node_jobs,node_sqlite toneAmber
class node_worker,node_evidence,node_context,node_codex,node_mcp,node_validator toneMint
class node_jaeger,node_opensearch,node_promadapter toneRose
class node_operator,node_prometheus toneIndigo
class node_cli,node_otel toneTeal
```

## Components

### Detection

- [Alert source](https://github.com/timme33/sentinel/blob/main/src/detection/prometheus_alerts.py): `src/detection/prometheus_alerts.py`
- [Detection runner](https://github.com/timme33/sentinel/blob/main/src/detection/runner.py): `src/detection/runner.py`
- [RED metrics reader](https://github.com/timme33/sentinel/blob/main/src/telemetry/red_reader.py): `src/telemetry/red_reader.py`
- [RED query builder](https://github.com/timme33/sentinel/blob/main/src/telemetry/red_queries.py): `src/telemetry/red_queries.py`
- [Domain records](https://github.com/timme33/sentinel/blob/main/src/domain/models.py): `src/domain/models.py`

### Incidents and state

- [Incident store](https://github.com/timme33/sentinel/blob/main/src/incidents/store.py): `src/incidents/store.py`
- [Investigation jobs](https://github.com/timme33/sentinel/blob/main/src/investigation/repository.py): `src/investigation/repository.py`
- **SQLite state**

### Investigation

- [Investigation worker](https://github.com/timme33/sentinel/blob/main/src/investigation/worker.py): `src/investigation/worker.py`
- [Evidence collection](https://github.com/timme33/sentinel/blob/main/src/investigation/evidence_service.py): `src/investigation/evidence_service.py`
- [Context builder](https://github.com/timme33/sentinel/blob/main/src/investigation/context_builder.py): `src/investigation/context_builder.py`
- [Codex agent](https://github.com/timme33/sentinel/blob/main/src/investigation/codex_agent.py): `src/investigation/codex_agent.py`
- [FastMCP tools](https://github.com/timme33/sentinel/blob/main/src/investigation/mcp_server.py): `src/investigation/mcp_server.py`
- [Report validator](https://github.com/timme33/sentinel/blob/main/src/investigation/report_validator.py): `src/investigation/report_validator.py`

### Telemetry

- [Jaeger adapter](https://github.com/timme33/sentinel/blob/main/src/telemetry/jaeger.py): `src/telemetry/jaeger.py`
- [OpenSearch adapter](https://github.com/timme33/sentinel/blob/main/src/telemetry/opensearch.py): `src/telemetry/opensearch.py`
- [Prometheus adapter](https://github.com/timme33/sentinel/blob/main/src/telemetry/prometheus.py): `src/telemetry/prometheus.py`

### Other components

- **Operator**
- [Sentinel CLI](https://github.com/timme33/sentinel/blob/main/src/cli.py): `src/cli.py`
- **Prometheus**
- [OpenTelemetry Demo](https://github.com/timme33/sentinel/blob/main/integration/otel-demo/compose.sentinel.yaml): `integration/otel-demo/compose.sentinel.yaml`

## Connections

- Operator → Sentinel CLI: operates (evidence: `README.md`)
- Sentinel CLI → Prometheus adapter: builds (evidence: `src/cli.py`)
- Sentinel CLI → Detection runner: starts detection (evidence: `src/cli.py`)
- Sentinel CLI → Investigation worker: starts worker (evidence: `src/cli.py`)
- Sentinel CLI → Incident store: reads and initializes (evidence: `src/cli.py`)
- Sentinel CLI → Investigation jobs: reads and initializes (evidence: `src/cli.py`)
- Detection runner → Alert source: polls (evidence: `src/detection/runner.py`)
- Alert source → Prometheus adapter: reads firing alerts (evidence: `src/detection/prometheus_alerts.py`)
- Prometheus adapter → Prometheus: queries (evidence: `src/telemetry/prometheus.py`)
- Alert source → Domain records: creates signals (evidence: `src/detection/prometheus_alerts.py`)
- Detection runner → Incident store: reconciles snapshot (evidence: `src/detection/runner.py`)
- Incident store → SQLite state: persists lifecycle (evidence: `src/incidents/store.py`)
- Detection runner → Investigation jobs: schedules jobs (evidence: `src/detection/runner.py`)
- Investigation jobs → SQLite state: persists jobs (evidence: `README.md`)
- Detection runner → Prometheus adapter: reports metrics
- Sentinel CLI → RED metrics reader: builds snapshot (evidence: `src/cli.py`)
- RED metrics reader → RED query builder: uses queries (evidence: `src/telemetry/red_reader.py`)
- RED metrics reader → Prometheus adapter: queries metrics (evidence: `src/telemetry/red_reader.py`)
- OpenTelemetry Demo → Prometheus: exports telemetry (evidence: `README.md`)
- Prometheus → Alert source: provides alerts (evidence: `README.md`)
- Investigation worker → Investigation jobs: claims and updates (evidence: `README.md`)
- Investigation worker → Incident store: loads incident (evidence: `README.md`)
- Investigation worker → Evidence collection: collects evidence (evidence: `README.md`)
- Evidence collection → Jaeger adapter: queries traces (evidence: `README.md`)
- Evidence collection → OpenSearch adapter: queries logs (evidence: `README.md`)
- Evidence collection → Investigation jobs: stores evidence (evidence: `README.md`)
- Investigation worker → Context builder: builds context (evidence: `README.md`)
- Investigation worker → Codex agent: invokes agent (evidence: `README.md`)
- Codex agent → FastMCP tools: requests evidence (evidence: `README.md`)
- FastMCP tools → Jaeger adapter: searches traces (evidence: `README.md`)
- FastMCP tools → OpenSearch adapter: searches logs (evidence: `README.md`)
- Investigation worker → Report validator: validates report (evidence: `README.md`)
- Report validator → Investigation jobs: persists report (evidence: `README.md`)
