# salamfarukh13-blip/threat-assist architecture

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

- Interactive diagram: https://gitdiagram.com/salamfarukh13-blip/threat-assist
- Repository: https://github.com/salamfarukh13-blip/threat-assist

## Overview

THREAT ASSIST is an academic prototype for correlating synthetic threat-actor identities and presenting investigation results. The user workflow is to browse actor dossiers, compare two actors or search an identifier, inspect shared-footprint network connections, manage synthetic records, and generate a case report. The backend exposes these capabilities through FastAPI routes; matching combines explainable scoring, an ML probability, and graph paths. The README documents the product capabilities; unsampled route and page internals are represented only at their tree-supported paths, so uncertain implementation wiring is omitted.

Main entry points: [`backend/app/main.py`](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/main.py) (FastAPI Entry), [`backend/app/database.py`](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/database.py) (Database Layer), [`frontend/src/App.jsx`](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/App.jsx) (Application Shell), [`frontend/src/services/api.js`](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/services/api.js) (REST Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Investigation UI"]
  node_app["Application Shell<br/>[App.jsx]"]
  node_actors_ui["Actor Dossiers<br/>[ActorDatabase.jsx]"]
  node_dashboard_ui["Dashboard<br/>[Dashboard.jsx]"]
  node_compare_ui["Identity Comparison"]
  node_graph_ui["Relationship Graph"]
  node_manage_ui["Data Management<br/>[DataManagement.jsx]"]
  node_report_ui["Case Report"]
  node_api_client["REST Client<br/>[api.js]"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI Entry<br/>[main.py]"]
  node_actors_route["Actor Routes<br/>[actors.py]"]
  node_footprints_route["Footprint Routes<br/>[footprints.py]"]
  node_relationships_route["Relationship Routes<br/>[relationships.py]"]
  node_dashboard_route["Dashboard Route<br/>[dashboard.py]"]
  node_matching_route["Matching Route<br/>[matching.py]"]
  node_graph_route["Graph Route<br/>[graph.py]"]
  node_report_route["Report Route<br/>[report.py]"]
end

subgraph group_analysis["Correlation Analysis"]
  node_engine["Heuristic Scoring<br/>[engine.py]"]
  node_ml["ML Classifier<br/>[ml_model.py]"]
  node_analytics["Graph Analytics<br/>[graph_analytics.py]"]
end

subgraph group_data["Synthetic Data"]
  node_db_manager["Database Layer<br/>[database.py]"]
  node_store[("Actor and Evidence Store<br/>[database.py]")]
  node_seed["Synthetic Dataset<br/>[synthetic_data.py]"]
end

node_investigator(("Investigator"))

node_investigator -->|"uses"| node_app
node_app -->|"selects view"| node_actors_ui
node_app -->|"selects view"| node_dashboard_ui
node_app -->|"selects view"| node_compare_ui
node_app -->|"selects view"| node_graph_ui
node_app -->|"selects view"| node_manage_ui
node_app -->|"selects view"| node_report_ui
node_actors_ui -->|"requests actors"| node_api_client
node_dashboard_ui -->|"requests metrics"| node_api_client
node_compare_ui -->|"requests comparison"| node_api_client
node_graph_ui -->|"requests graph"| node_api_client
node_manage_ui -->|"manages records"| node_api_client
node_report_ui -->|"requests report"| node_api_client
node_api_client -->|"HTTP JSON"| node_server
node_server -->|"dispatches"| node_actors_route
node_server -->|"dispatches"| node_footprints_route
node_server -->|"dispatches"| node_relationships_route
node_server -->|"dispatches"| node_dashboard_route
node_server -->|"dispatches"| node_matching_route
node_server -->|"dispatches"| node_graph_route
node_server -->|"dispatches"| node_report_route
node_actors_route -->|"reads and writes"| node_db_manager
node_footprints_route -->|"reads and writes"| node_db_manager
node_relationships_route -->|"reads and writes"| node_db_manager
node_dashboard_route -->|"reads metrics"| node_db_manager
node_matching_route -->|"loads actors"| node_db_manager
node_matching_route -->|"scores pair"| node_engine
node_matching_route -->|"predicts probability"| node_ml
node_matching_route -->|"finds path"| node_analytics
node_graph_route -->|"queries graph"| node_analytics
node_report_route -->|"loads report data"| node_db_manager
node_db_manager -->|"persists records"| node_store
node_server -->|"loads initial data"| node_seed
node_server -->|"initializes store"| node_db_manager
node_server -->|"primes graph"| node_analytics
node_db_manager -->|"supplies graph data"| node_analytics

click node_app "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/App.jsx"
click node_actors_ui "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/ActorDatabase.jsx"
click node_dashboard_ui "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/Dashboard.jsx"
click node_compare_ui "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/IdentityComparison.jsx"
click node_graph_ui "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/RelationshipGraph.jsx"
click node_manage_ui "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/DataManagement.jsx"
click node_report_ui "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/InvestigationReport.jsx"
click node_api_client "https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/main.py"
click node_actors_route "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/actors.py"
click node_footprints_route "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/footprints.py"
click node_relationships_route "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/relationships.py"
click node_dashboard_route "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/dashboard.py"
click node_matching_route "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/matching.py"
click node_graph_route "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/graph.py"
click node_report_route "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/report.py"
click node_engine "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/matching/engine.py"
click node_ml "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/matching/ml_model.py"
click node_analytics "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/matching/graph_analytics.py"
click node_db_manager "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/database.py"
click node_store "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/database.py"
click node_seed "https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/seed/synthetic_data.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_actors_ui,node_dashboard_ui,node_compare_ui,node_graph_ui,node_manage_ui,node_report_ui,node_api_client toneBlue
class node_server,node_actors_route,node_footprints_route,node_relationships_route,node_dashboard_route,node_matching_route,node_graph_route,node_report_route toneAmber
class node_engine,node_ml,node_analytics toneMint
class node_db_manager,node_store,node_seed toneRose
class node_investigator toneIndigo
```

## Components

### Investigation UI

- [Application Shell](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Actor Dossiers](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/ActorDatabase.jsx): `frontend/src/pages/ActorDatabase.jsx`
- [Dashboard](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Identity Comparison](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/IdentityComparison.jsx): `frontend/src/pages/IdentityComparison.jsx`
- [Relationship Graph](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/RelationshipGraph.jsx): `frontend/src/pages/RelationshipGraph.jsx`
- [Data Management](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/DataManagement.jsx): `frontend/src/pages/DataManagement.jsx`
- [Case Report](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/pages/InvestigationReport.jsx): `frontend/src/pages/InvestigationReport.jsx`
- [REST Client](https://github.com/salamfarukh13-blip/threat-assist/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Backend API

- [FastAPI Entry](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/main.py): `backend/app/main.py`
- [Actor Routes](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/actors.py): `backend/app/routes/actors.py`
- [Footprint Routes](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/footprints.py): `backend/app/routes/footprints.py`
- [Relationship Routes](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/relationships.py): `backend/app/routes/relationships.py`
- [Dashboard Route](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/dashboard.py): `backend/app/routes/dashboard.py`
- [Matching Route](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/matching.py): `backend/app/routes/matching.py`
- [Graph Route](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/graph.py): `backend/app/routes/graph.py`
- [Report Route](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/routes/report.py): `backend/app/routes/report.py`

### Correlation Analysis

- [Heuristic Scoring](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/matching/engine.py): `backend/app/matching/engine.py`
- [ML Classifier](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/matching/ml_model.py): `backend/app/matching/ml_model.py`
- [Graph Analytics](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/matching/graph_analytics.py): `backend/app/matching/graph_analytics.py`

### Synthetic Data

- [Database Layer](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/database.py): `backend/app/database.py`
- [Actor and Evidence Store](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/app/database.py): `backend/app/database.py`
- [Synthetic Dataset](https://github.com/salamfarukh13-blip/threat-assist/blob/main/backend/seed/synthetic_data.py): `backend/seed/synthetic_data.py`

### Other components

- **Investigator**

## Connections

- Investigator → Application Shell: uses
- Application Shell → Actor Dossiers: selects view
- Application Shell → Dashboard: selects view
- Application Shell → Identity Comparison: selects view
- Application Shell → Relationship Graph: selects view
- Application Shell → Data Management: selects view
- Application Shell → Case Report: selects view
- Actor Dossiers → REST Client: requests actors
- Dashboard → REST Client: requests metrics
- Identity Comparison → REST Client: requests comparison
- Relationship Graph → REST Client: requests graph
- Data Management → REST Client: manages records
- Case Report → REST Client: requests report
- REST Client → FastAPI Entry: HTTP JSON
- FastAPI Entry → Actor Routes: dispatches
- FastAPI Entry → Footprint Routes: dispatches
- FastAPI Entry → Relationship Routes: dispatches
- FastAPI Entry → Dashboard Route: dispatches
- FastAPI Entry → Matching Route: dispatches
- FastAPI Entry → Graph Route: dispatches
- FastAPI Entry → Report Route: dispatches
- Actor Routes → Database Layer: reads and writes
- Footprint Routes → Database Layer: reads and writes
- Relationship Routes → Database Layer: reads and writes
- Dashboard Route → Database Layer: reads metrics
- Matching Route → Database Layer: loads actors
- Matching Route → Heuristic Scoring: scores pair
- Matching Route → ML Classifier: predicts probability
- Matching Route → Graph Analytics: finds path
- Graph Route → Graph Analytics: queries graph
- Report Route → Database Layer: loads report data
- Database Layer → Actor and Evidence Store: persists records
- FastAPI Entry → Synthetic Dataset: loads initial data
- FastAPI Entry → Database Layer: initializes store
- FastAPI Entry → Graph Analytics: primes graph
- Database Layer → Graph Analytics: supplies graph data