# broc0des/argus architecture

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

- Interactive diagram: https://gitdiagram.com/broc0des/argus
- Repository: https://github.com/broc0des/argus

## Overview

ARGUS is a live incident investigation console. An engineer views service health and logs, then submits a question; the backend combines recent log anomalies with indexed code and service dependencies, asks a local Ollama model for a structured diagnosis, validates its evidence, and returns a report for the console. Separate workflows expose the live dependency graph and log stream, and replay named scenarios into the watched log. The graph follows documented API behavior and sampled call sites; frontend rendering details and several backend internals were not sampled.

Main entry points: [`backend/main.py`](https://github.com/broc0des/argus/blob/main/backend/main.py) (FastAPI routes), [`backend/query_pipeline.py`](https://github.com/broc0des/argus/blob/main/backend/query_pipeline.py) (Query pipeline), [`backend/scenario_sim.py`](https://github.com/broc0des/argus/blob/main/backend/scenario_sim.py) (Scenario replay), [`backend/code_indexer.py`](https://github.com/broc0des/argus/blob/main/backend/code_indexer.py) (Code indexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Incident console"]
  node_console_app["Console UI<br/>[ConsoleApp.jsx]"]
  node_frontend_api["API client<br/>[api.js]"]
end

subgraph group_backend["ARGUS API"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_scenario_replay["Scenario replay<br/>[scenario_sim.py]"]
end

subgraph group_investigation["Investigation engine"]
  node_code_indexer["Code indexer<br/>[code_indexer.py]"]
  node_log_analyzer["Log analyzer<br/>[log_analyzer.py]"]
  node_query_pipeline["Query pipeline<br/>[query_pipeline.py]"]
end

subgraph group_inputs["Incident inputs"]
  node_traffic_simulator["Traffic simulator<br/>[traffic_sim.py]"]
  node_indexed_repo["Service repository"]
  node_log_file["Watched log"]
  node_scenario_fixtures["Scenario fixtures"]
end

node_engineer(("Engineer"))
node_ollama["Local Ollama"]

node_engineer -->|"uses"| node_console_app
node_console_app -->|"requests"| node_frontend_api
node_frontend_api -->|"calls API"| node_api
node_api -->|"builds graph"| node_code_indexer
node_api -->|"reads status"| node_log_analyzer
node_api -->|"runs diagnosis"| node_query_pipeline
node_query_pipeline -->|"reads anomalies"| node_log_analyzer
node_query_pipeline -->|"searches code"| node_code_indexer
node_query_pipeline -->|"requests diagnosis"| node_ollama
node_indexed_repo -->|"indexed by"| node_code_indexer
node_log_file -->|"read on request"| node_log_analyzer
node_traffic_simulator -.->|"writes logs"| node_log_file
node_api -->|"replays scenario"| node_scenario_replay
node_scenario_replay -->|"reads fixture"| node_scenario_fixtures
node_scenario_replay -->|"writes replay"| node_log_file

click node_console_app "https://github.com/broc0des/argus/blob/main/frontend/src/ConsoleApp.jsx"
click node_frontend_api "https://github.com/broc0des/argus/blob/main/frontend/src/api.js"
click node_api "https://github.com/broc0des/argus/blob/main/backend/main.py"
click node_code_indexer "https://github.com/broc0des/argus/blob/main/backend/code_indexer.py"
click node_log_analyzer "https://github.com/broc0des/argus/blob/main/backend/log_analyzer.py"
click node_query_pipeline "https://github.com/broc0des/argus/blob/main/backend/query_pipeline.py"
click node_scenario_replay "https://github.com/broc0des/argus/blob/main/backend/scenario_sim.py"
click node_traffic_simulator "https://github.com/broc0des/argus/blob/main/backend/traffic_sim.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_console_app,node_frontend_api toneBlue
class node_api,node_scenario_replay toneAmber
class node_code_indexer,node_log_analyzer,node_query_pipeline toneMint
class node_traffic_simulator,node_indexed_repo,node_log_file,node_scenario_fixtures toneRose
class node_engineer,node_ollama toneIndigo
```

## Components

### Incident console

- [Console UI](https://github.com/broc0des/argus/blob/main/frontend/src/ConsoleApp.jsx): `frontend/src/ConsoleApp.jsx`
- [API client](https://github.com/broc0des/argus/blob/main/frontend/src/api.js): `frontend/src/api.js`

### ARGUS API

- [FastAPI routes](https://github.com/broc0des/argus/blob/main/backend/main.py): `backend/main.py`
- [Scenario replay](https://github.com/broc0des/argus/blob/main/backend/scenario_sim.py): `backend/scenario_sim.py`

### Investigation engine

- [Code indexer](https://github.com/broc0des/argus/blob/main/backend/code_indexer.py): `backend/code_indexer.py`
- [Log analyzer](https://github.com/broc0des/argus/blob/main/backend/log_analyzer.py): `backend/log_analyzer.py`
- [Query pipeline](https://github.com/broc0des/argus/blob/main/backend/query_pipeline.py): `backend/query_pipeline.py`

### Incident inputs

- [Traffic simulator](https://github.com/broc0des/argus/blob/main/backend/traffic_sim.py): `backend/traffic_sim.py`
- **Service repository**
- **Watched log**
- **Scenario fixtures**

### Other components

- **Engineer**
- **Local Ollama**

## Connections

- Engineer → Console UI: uses
- Console UI → API client: requests
- API client → FastAPI routes: calls API
- FastAPI routes → Code indexer: builds graph
- FastAPI routes → Log analyzer: reads status
- FastAPI routes → Query pipeline: runs diagnosis
- Query pipeline → Log analyzer: reads anomalies
- Query pipeline → Code indexer: searches code
- Query pipeline → Local Ollama: requests diagnosis
- Service repository → Code indexer: indexed by
- Watched log → Log analyzer: read on request
- Traffic simulator → Watched log: writes logs
- FastAPI routes → Scenario replay: replays scenario
- Scenario replay → Scenario fixtures: reads fixture
- Scenario replay → Watched log: writes replay