# usv240/argus-detection-evolution architecture

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

- Interactive diagram: https://gitdiagram.com/usv240/argus-detection-evolution
- Repository: https://github.com/usv240/argus-detection-evolution

## Overview

ARGUS is a live Splunk-backed adversarial detection-evolution product. A user launches an arena run; the backend repeatedly generates synthetic attack variants, evaluates the current detection against Splunk, and evolves the rule, then presents measured coverage and review artifacts. The graph preserves scenario definitions, provider integrations, scoring, export, and the human-approval path. Some subsystem details are documented in the README or source index rather than shown in excerpts, so those links cite that evidence and uncertain wiring is omitted.

Main entry points: [`backend/arena_orchestrator.py`](https://github.com/usv240/argus-detection-evolution/blob/main/backend/arena_orchestrator.py) (Arena orchestrator), [`backend/api.py`](https://github.com/usv240/argus-detection-evolution/blob/main/backend/api.py) (HTTP API), [`backend/agents/red_synthesizer.py`](https://github.com/usv240/argus-detection-evolution/blob/main/backend/agents/red_synthesizer.py) (Red synthesizer), [`backend/splunk/search.py`](https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/search.py) (Search provider selector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Application shell<br/>[App.tsx]"]
  node_landing["Landing view<br/>[Landing.tsx]"]
  node_arena["Arena view<br/>[Arena.tsx]"]
  node_stream["Live event stream<br/>[stream.ts]"]
end

subgraph group_engine["Evolution engine"]
  node_api["HTTP API<br/>[api.py]"]
  node_orchestrator["Arena orchestrator"]
  node_scenarios["Scenario definitions<br/>[scenarios.py]"]
  node_red["Red synthesizer<br/>[red_synthesizer.py]"]
  node_evaluator["Detection evaluator<br/>[evaluator.py]"]
  node_blue["Blue evolver<br/>[blue_evolver.py]"]
  node_llm["Reasoning model<br/>[llm.py]"]
end

subgraph group_splunk["Splunk integration"]
  node_search["Search provider selector<br/>[search.py]"]
  node_mcp["MCP search client<br/>[mcp_client.py]"]
  node_sdk["SDK search client<br/>[sdk_client.py]"]
  node_hec["Synthetic event writer<br/>[hec.py]"]
end

subgraph group_results["Results and review"]
  node_scorer["Anomaly scorer<br/>[scorer.py]"]
  node_export["Splunk app export<br/>[app_export.py]"]
  node_approval["Saved-search approval<br/>[sdk_client.py]"]
  node_slack["Slack notifications<br/>[slack_notifier.py]"]
end

node_user(("Security analyst"))
node_splunk[("Splunk instance")]

node_user -->|"opens"| node_app
node_app -->|"renders"| node_landing
node_app -->|"renders"| node_arena
node_arena -->|"receives updates"| node_stream
node_arena -->|"requests runs"| node_api
node_api -->|"starts runs"| node_orchestrator
node_orchestrator -->|"uses scenario"| node_scenarios
node_orchestrator -->|"requests variants"| node_red
node_orchestrator -->|"scores detection"| node_evaluator
node_orchestrator -->|"evolves rule"| node_blue
node_red -->|"proposes evasions"| node_llm
node_blue -->|"rewrites rule"| node_llm
node_red -->|"builds events"| node_scenarios
node_red -->|"writes variants"| node_hec
node_evaluator -->|"runs SPL"| node_search
node_scenarios -->|"queries distributions"| node_search
node_search -->|"selects MCP"| node_mcp
node_search -->|"selects SDK"| node_sdk
node_mcp -->|"runs live searches"| node_splunk
node_sdk -->|"runs live searches"| node_splunk
node_hec -->|"ingests events"| node_splunk
node_orchestrator -->|"scores variants"| node_scorer
node_api -->|"exports app"| node_export
node_api -->|"approves deployment"| node_approval
node_approval -->|"creates saved search"| node_splunk
node_api -->|"notifies"| node_slack

click node_app "https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/App.tsx"
click node_landing "https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/views/Landing.tsx"
click node_arena "https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/views/Arena.tsx"
click node_stream "https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/api/stream.ts"
click node_api "https://github.com/usv240/argus-detection-evolution/blob/main/backend/api.py"
click node_orchestrator "https://github.com/usv240/argus-detection-evolution/blob/main/backend/arena_orchestrator.py"
click node_scenarios "https://github.com/usv240/argus-detection-evolution/blob/main/backend/scenarios.py"
click node_red "https://github.com/usv240/argus-detection-evolution/blob/main/backend/agents/red_synthesizer.py"
click node_evaluator "https://github.com/usv240/argus-detection-evolution/blob/main/backend/agents/evaluator.py"
click node_blue "https://github.com/usv240/argus-detection-evolution/blob/main/backend/agents/blue_evolver.py"
click node_llm "https://github.com/usv240/argus-detection-evolution/blob/main/backend/models/llm.py"
click node_search "https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/search.py"
click node_mcp "https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/mcp_client.py"
click node_sdk "https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/sdk_client.py"
click node_hec "https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/hec.py"
click node_scorer "https://github.com/usv240/argus-detection-evolution/blob/main/backend/models/scorer.py"
click node_export "https://github.com/usv240/argus-detection-evolution/blob/main/backend/app_export.py"
click node_approval "https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/sdk_client.py"
click node_slack "https://github.com/usv240/argus-detection-evolution/blob/main/backend/slack_notifier.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_app,node_landing,node_arena,node_stream toneBlue
class node_api,node_orchestrator,node_scenarios,node_red,node_evaluator,node_blue,node_llm,node_splunk toneAmber
class node_search,node_mcp,node_sdk,node_hec toneMint
class node_scorer,node_export,node_approval,node_slack toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Application shell](https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Landing view](https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/views/Landing.tsx): `frontend/src/views/Landing.tsx`
- [Arena view](https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/views/Arena.tsx): `frontend/src/views/Arena.tsx`
- [Live event stream](https://github.com/usv240/argus-detection-evolution/blob/main/frontend/src/api/stream.ts): `frontend/src/api/stream.ts`

### Evolution engine

- [HTTP API](https://github.com/usv240/argus-detection-evolution/blob/main/backend/api.py): `backend/api.py`
- [Arena orchestrator](https://github.com/usv240/argus-detection-evolution/blob/main/backend/arena_orchestrator.py): `backend/arena_orchestrator.py`
- [Scenario definitions](https://github.com/usv240/argus-detection-evolution/blob/main/backend/scenarios.py): `backend/scenarios.py`
- [Red synthesizer](https://github.com/usv240/argus-detection-evolution/blob/main/backend/agents/red_synthesizer.py): `backend/agents/red_synthesizer.py`
- [Detection evaluator](https://github.com/usv240/argus-detection-evolution/blob/main/backend/agents/evaluator.py): `backend/agents/evaluator.py`
- [Blue evolver](https://github.com/usv240/argus-detection-evolution/blob/main/backend/agents/blue_evolver.py): `backend/agents/blue_evolver.py`
- [Reasoning model](https://github.com/usv240/argus-detection-evolution/blob/main/backend/models/llm.py): `backend/models/llm.py`

### Splunk integration

- [Search provider selector](https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/search.py): `backend/splunk/search.py`
- [MCP search client](https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/mcp_client.py): `backend/splunk/mcp_client.py`
- [SDK search client](https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/sdk_client.py): `backend/splunk/sdk_client.py`
- [Synthetic event writer](https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/hec.py): `backend/splunk/hec.py`

### Results and review

- [Anomaly scorer](https://github.com/usv240/argus-detection-evolution/blob/main/backend/models/scorer.py): `backend/models/scorer.py`
- [Splunk app export](https://github.com/usv240/argus-detection-evolution/blob/main/backend/app_export.py): `backend/app_export.py`
- [Saved-search approval](https://github.com/usv240/argus-detection-evolution/blob/main/backend/splunk/sdk_client.py): `backend/splunk/sdk_client.py`
- [Slack notifications](https://github.com/usv240/argus-detection-evolution/blob/main/backend/slack_notifier.py): `backend/slack_notifier.py`

### Other components

- **Security analyst**
- **Splunk instance**

## Connections

- Security analyst → Application shell: opens (evidence: `README.md`)
- Application shell → Landing view: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Arena view: renders (evidence: `frontend/src/App.tsx`)
- Arena view → Live event stream: receives updates (evidence: `frontend/src/views/Arena.tsx`)
- Arena view → HTTP API: requests runs (evidence: `frontend/src/views/Arena.tsx`)
- HTTP API → Arena orchestrator: starts runs (evidence: `backend/api.py`)
- Arena orchestrator → Scenario definitions: uses scenario (evidence: `backend/arena_orchestrator.py`)
- Arena orchestrator → Red synthesizer: requests variants (evidence: `backend/arena_orchestrator.py`)
- Arena orchestrator → Detection evaluator: scores detection (evidence: `backend/arena_orchestrator.py`)
- Arena orchestrator → Blue evolver: evolves rule (evidence: `backend/arena_orchestrator.py`)
- Red synthesizer → Reasoning model: proposes evasions (evidence: `backend/agents/red_synthesizer.py`)
- Blue evolver → Reasoning model: rewrites rule (evidence: `backend/agents/blue_evolver.py`)
- Red synthesizer → Scenario definitions: builds events (evidence: `backend/agents/red_synthesizer.py`)
- Red synthesizer → Synthetic event writer: writes variants (evidence: `backend/agents/red_synthesizer.py`)
- Detection evaluator → Search provider selector: runs SPL (evidence: `backend/agents/evaluator.py`)
- Scenario definitions → Search provider selector: queries distributions (evidence: `backend/scenarios.py`)
- Search provider selector → MCP search client: selects MCP (evidence: `backend/splunk/search.py`)
- Search provider selector → SDK search client: selects SDK (evidence: `backend/splunk/search.py`)
- MCP search client → Splunk instance: runs live searches (evidence: `backend/splunk/mcp_client.py`)
- SDK search client → Splunk instance: runs live searches (evidence: `backend/splunk/sdk_client.py`)
- Synthetic event writer → Splunk instance: ingests events
- Arena orchestrator → Anomaly scorer: scores variants (evidence: `backend/arena_orchestrator.py`)
- HTTP API → Splunk app export: exports app (evidence: `backend/api.py`)
- HTTP API → Saved-search approval: approves deployment (evidence: `backend/api.py`)
- Saved-search approval → Splunk instance: creates saved search (evidence: `backend/splunk/sdk_client.py`)
- HTTP API → Slack notifications: notifies (evidence: `backend/api.py`)
