# dawidtrochim/attack-graph-chain-reconstruction-engine architecture

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

- Interactive diagram: https://gitdiagram.com/dawidtrochim/attack-graph-chain-reconstruction-engine
- Repository: https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine

## Overview

This is a SOC investigation backend: analysts or API clients submit IOC and log data, trigger correlation and reconstruction, then inspect attack chains and update investigation status through REST or dashboard views. The documented pipeline includes MITRE ATT&CK mapping, severity scoring, graph persistence, and interactive visualization. Core runtime paths are represented; dashboard templates and some integrations are documented but not excerpted, so those relationships rely on the README where noted.

Main entry points: [`app/models.py`](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/models.py) (PostgreSQL data), [`app/main.py`](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/main.py) (FastAPI application), [`app/services/reconstruction.py`](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/reconstruction.py) (Chain reconstruction), [`app/routes/dashboard.py`](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/dashboard.py) (Dashboard and workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion API"]
  node_application["FastAPI application<br/>[main.py]"]
  node_ioc_ingest["IOC ingestion<br/>[iocs.py]"]
  node_log_ingest["Log ingestion<br/>[logs.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
end

subgraph group_detection["Detection Pipeline"]
  node_correlation_route["Detection triggers<br/>[attack_chains.py]"]
  node_correlation["IOC correlation<br/>[correlation.py]"]
  node_reconstruction["Chain reconstruction<br/>[reconstruction.py]"]
  node_stage_mapping["ATT&amp;CK mapping<br/>[stage_mapping.py]"]
  node_scoring["Severity scoring<br/>[scoring.py]"]
  node_graph_builder["Attack graph builder<br/>[graph_builder.py]"]
end

subgraph group_persistence["Persistence"]
  node_database[("PostgreSQL data<br/>[models.py]")]
  node_db_sessions["Database sessions<br/>[db.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_investigation["Investigation UI"]
  node_attack_api["Chain and graph API<br/>[attack_chains.py]"]
  node_dashboard["Dashboard and workflow<br/>[dashboard.py]"]
  node_dashboard_templates["Investigation views"]
  node_graph_ui["Interactive graph view<br/>[graph_view.html]"]
end

node_analyst(("SOC analyst"))
node_api_client(("API client"))

node_api_client -->|"sends requests"| node_application
node_analyst -->|"investigates chains"| node_dashboard
node_application -->|"registers router"| node_ioc_ingest
node_application -->|"registers router"| node_log_ingest
node_application -->|"registers router"| node_correlation_route
node_application -->|"registers router"| node_dashboard
node_ioc_ingest -->|"validates payload"| node_schemas
node_log_ingest -->|"validates payload"| node_schemas
node_ioc_ingest -->|"writes indicators"| node_database
node_log_ingest -->|"writes log events"| node_database
node_correlation_route -->|"runs correlation"| node_correlation
node_correlation -->|"reads and records matches"| node_database
node_correlation_route -->|"starts reconstruction"| node_reconstruction
node_reconstruction -->|"reads matches; writes chains"| node_database
node_reconstruction -->|"maps events"| node_stage_mapping
node_reconstruction -->|"computes scores"| node_scoring
node_reconstruction -->|"builds chain graph"| node_graph_builder
node_graph_builder -->|"persists graph"| node_database
node_application -->|"initializes database"| node_db_sessions
node_db_sessions -->|"gets database URL"| node_settings
node_db_sessions -->|"opens sessions"| node_database
node_attack_api -->|"reads chains and graphs"| node_database
node_dashboard -->|"reads and updates cases"| node_database
node_dashboard -->|"renders views"| node_dashboard_templates
node_dashboard_templates -.->|"includes graph view"| node_graph_ui

click node_application "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/main.py"
click node_ioc_ingest "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/iocs.py"
click node_log_ingest "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/logs.py"
click node_schemas "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/schemas.py"
click node_correlation_route "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/attack_chains.py"
click node_correlation "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/correlation.py"
click node_reconstruction "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/reconstruction.py"
click node_stage_mapping "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/stage_mapping.py"
click node_scoring "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/scoring.py"
click node_graph_builder "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/graph_builder.py"
click node_database "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/models.py"
click node_db_sessions "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/db.py"
click node_settings "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/config.py"
click node_attack_api "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/attack_chains.py"
click node_dashboard "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/dashboard.py"
click node_dashboard_templates "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/tree/main/app/templates"
click node_graph_ui "https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/templates/graph_view.html"

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_application,node_ioc_ingest,node_log_ingest,node_schemas,node_api_client toneBlue
class node_correlation_route,node_correlation,node_reconstruction,node_stage_mapping,node_scoring,node_graph_builder toneAmber
class node_database,node_db_sessions,node_settings toneMint
class node_attack_api,node_dashboard,node_dashboard_templates,node_graph_ui toneRose
class node_analyst toneIndigo
```

## Components

### Ingestion API

- [FastAPI application](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/main.py): `app/main.py`
- [IOC ingestion](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/iocs.py): `app/routes/iocs.py`
- [Log ingestion](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/logs.py): `app/routes/logs.py`
- [Request schemas](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/schemas.py): `app/schemas.py`

### Detection Pipeline

- [Detection triggers](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/attack_chains.py): `app/routes/attack_chains.py`
- [IOC correlation](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/correlation.py): `app/services/correlation.py`
- [Chain reconstruction](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/reconstruction.py): `app/services/reconstruction.py`
- [ATT&CK mapping](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/stage_mapping.py): `app/services/stage_mapping.py`
- [Severity scoring](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/scoring.py): `app/services/scoring.py`
- [Attack graph builder](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/services/graph_builder.py): `app/services/graph_builder.py`

### Persistence

- [PostgreSQL data](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/models.py): `app/models.py`
- [Database sessions](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/db.py): `app/db.py`
- [Runtime settings](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/config.py): `app/config.py`

### Investigation UI

- [Chain and graph API](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/attack_chains.py): `app/routes/attack_chains.py`
- [Dashboard and workflow](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/routes/dashboard.py): `app/routes/dashboard.py`
- [Investigation views](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/tree/main/app/templates): `app/templates`
- [Interactive graph view](https://github.com/dawidtrochim/attack-graph-chain-reconstruction-engine/blob/main/app/templates/graph_view.html): `app/templates/graph_view.html`

### Other components

- **SOC analyst**
- **API client**

## Connections

- API client → FastAPI application: sends requests (evidence: `README.md`)
- SOC analyst → Dashboard and workflow: investigates chains (evidence: `README.md`)
- FastAPI application → IOC ingestion: registers router (evidence: `app/main.py`)
- FastAPI application → Log ingestion: registers router (evidence: `app/main.py`)
- FastAPI application → Detection triggers: registers router (evidence: `app/main.py`)
- FastAPI application → Dashboard and workflow: registers router (evidence: `app/main.py`)
- IOC ingestion → Request schemas: validates payload (evidence: `app/routes/iocs.py`)
- Log ingestion → Request schemas: validates payload (evidence: `app/routes/logs.py`)
- IOC ingestion → PostgreSQL data: writes indicators (evidence: `app/routes/iocs.py`)
- Log ingestion → PostgreSQL data: writes log events (evidence: `app/routes/logs.py`)
- Detection triggers → IOC correlation: runs correlation (evidence: `app/routes/attack_chains.py`)
- IOC correlation → PostgreSQL data: reads and records matches (evidence: `app/services/correlation.py`)
- Detection triggers → Chain reconstruction: starts reconstruction (evidence: `app/routes/attack_chains.py`)
- Chain reconstruction → PostgreSQL data: reads matches; writes chains (evidence: `app/services/reconstruction.py`)
- Chain reconstruction → ATT&CK mapping: maps events (evidence: `app/services/reconstruction.py`)
- Chain reconstruction → Severity scoring: computes scores (evidence: `app/services/reconstruction.py`)
- Chain reconstruction → Attack graph builder: builds chain graph (evidence: `app/services/reconstruction.py`)
- Attack graph builder → PostgreSQL data: persists graph (evidence: `app/services/graph_builder.py`)
- FastAPI application → Database sessions: initializes database (evidence: `app/main.py`)
- Database sessions → Runtime settings: gets database URL (evidence: `app/db.py`)
- Database sessions → PostgreSQL data: opens sessions (evidence: `app/db.py`)
- Chain and graph API → PostgreSQL data: reads chains and graphs (evidence: `app/routes/attack_chains.py`)
- Dashboard and workflow → PostgreSQL data: reads and updates cases (evidence: `app/routes/dashboard.py`)
- Dashboard and workflow → Investigation views: renders views (evidence: `README.md`)
- Investigation views → Interactive graph view: includes graph view
