# nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response architecture

> Architecture diagram of the GitHub repository nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response
- Repository: https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response

## Overview

ThreatLens AI is a FastAPI intrusion-detection and analyst-guidance application. An operator or network-flow producer submits canonical flow features; the prediction route validates them, runs model inference, and can enrich attack results with SHAP explanations, defensive recommendations, and an optional IBM Granite advisory. Attack alerts and correlated incidents are persisted for alert and dashboard views. The README documents the dashboard’s alert, distribution, timeline, and attacker visualizations. Edges are limited to README statements and shown source/index references; some internal dashboard and service wiring was not sampled.

Main entry points: [`app/api/predictions.py`](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/predictions.py) (Prediction routes), [`app/main.py`](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/main.py) (FastAPI entry), [`app/api/explainability.py`](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/explainability.py) (Explain routes), [`app/api/dashboard.py`](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/dashboard.py) (Dashboard routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and input"]
  node_entry["FastAPI entry<br/>[main.py]"]
  node_prediction_api["Prediction routes<br/>[predictions.py]"]
  node_explain_api["Explain routes<br/>[explainability.py]"]
  node_alert_api["Alert routes<br/>[alerts.py]"]
  node_dashboard_api["Dashboard routes<br/>[dashboard.py]"]
  node_request_schema["Flow validation<br/>[requests.py]"]
  node_response_schema["Response models<br/>[responses.py]"]
end

subgraph group_detection["Detection and explanation"]
  node_inference["Model inference"]
  node_shap["SHAP attribution<br/>[shap_service.py]"]
  node_explain["Explanation synthesis<br/>[explainable_ai.py]"]
end

subgraph group_response["Alert and response"]
  node_defense["Action recommendations"]
  node_genai["GenAI advisory<br/>[genai_service.py]"]
  node_notifications["Alert notifications"]
  node_alert_service["Alert and incidents<br/>[alert_service.py]"]
end

subgraph group_persistence["Persistence and dashboard"]
  node_session["Database sessions<br/>[session.py]"]
  node_models["Alert and incident models<br/>[models.py]"]
  node_database[("SQLite database")]
  node_dashboard_ui["Live dashboard<br/>[app.js]"]
end

node_flow_source(("Flow producer"))
node_analyst(("Security analyst"))
node_granite["IBM Granite"]

node_flow_source -->|"submits flows"| node_prediction_api
node_analyst -->|"views alerts"| node_dashboard_ui
node_entry -->|"registers route"| node_prediction_api
node_entry -->|"registers route"| node_explain_api
node_entry -->|"registers route"| node_alert_api
node_entry -->|"registers route"| node_dashboard_api
node_entry -->|"initializes database"| node_session
node_prediction_api -->|"accepts features"| node_request_schema
node_prediction_api -->|"predicts flow"| node_inference
node_prediction_api -->|"requests attribution"| node_shap
node_prediction_api -->|"builds explanation"| node_explain
node_prediction_api -->|"requests actions"| node_defense
node_prediction_api -->|"requests advisory"| node_genai
node_genai -.->|"requests generation"| node_granite
node_prediction_api -->|"creates attack alert"| node_alert_service
node_prediction_api -->|"sends notification"| node_notifications
node_prediction_api -->|"returns result"| node_response_schema
node_explain_api -->|"uses prediction"| node_inference
node_explain_api -->|"requests attribution"| node_shap
node_explain_api -->|"builds explanation"| node_explain
node_explain_api -->|"requests advisory"| node_genai
node_alert_api -->|"manages alerts"| node_alert_service
node_alert_api -->|"requests actions"| node_defense
node_dashboard_api -->|"queries data"| node_session
node_alert_service -->|"queries and writes"| node_models
node_session -->|"creates tables"| node_models
node_session -->|"connects"| node_database
node_dashboard_ui -.->|"loads dashboard data"| node_dashboard_api
node_dashboard_api -->|"formats responses"| node_response_schema

click node_entry "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/main.py"
click node_prediction_api "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/predictions.py"
click node_explain_api "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/explainability.py"
click node_alert_api "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/alerts.py"
click node_dashboard_api "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/dashboard.py"
click node_request_schema "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/schemas/requests.py"
click node_response_schema "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/schemas/responses.py"
click node_inference "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/inference_service.py"
click node_shap "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/shap_service.py"
click node_explain "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/explainable_ai.py"
click node_defense "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/defensive_action_service.py"
click node_genai "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/genai_service.py"
click node_notifications "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/notification_service.py"
click node_alert_service "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/alert_service.py"
click node_session "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/database/session.py"
click node_models "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/database/models.py"
click node_dashboard_ui "https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/static/app.js"

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_entry,node_prediction_api,node_explain_api,node_alert_api,node_dashboard_api,node_request_schema,node_response_schema toneBlue
class node_inference,node_shap,node_explain toneAmber
class node_defense,node_genai,node_notifications,node_alert_service toneMint
class node_session,node_models,node_database,node_dashboard_ui toneRose
class node_flow_source,node_analyst,node_granite toneIndigo
```

## Components

### API and input

- [FastAPI entry](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/main.py): `app/main.py`
- [Prediction routes](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/predictions.py): `app/api/predictions.py`
- [Explain routes](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/explainability.py): `app/api/explainability.py`
- [Alert routes](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/alerts.py): `app/api/alerts.py`
- [Dashboard routes](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/api/dashboard.py): `app/api/dashboard.py`
- [Flow validation](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/schemas/requests.py): `app/schemas/requests.py`
- [Response models](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/schemas/responses.py): `app/schemas/responses.py`

### Detection and explanation

- [Model inference](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/inference_service.py): `app/services/inference_service.py`
- [SHAP attribution](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/shap_service.py): `app/services/shap_service.py`
- [Explanation synthesis](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/explainable_ai.py): `app/services/explainable_ai.py`

### Alert and response

- [Action recommendations](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/defensive_action_service.py): `app/services/defensive_action_service.py`
- [GenAI advisory](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/genai_service.py): `app/services/genai_service.py`
- [Alert notifications](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/notification_service.py): `app/services/notification_service.py`
- [Alert and incidents](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/services/alert_service.py): `app/services/alert_service.py`

### Persistence and dashboard

- [Database sessions](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/database/session.py): `app/database/session.py`
- [Alert and incident models](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/database/models.py): `app/database/models.py`
- **SQLite database**
- [Live dashboard](https://github.com/nehachavan005/threatlens-ai-explainable-cyber-threat-intelligence-response/blob/main/app/static/app.js): `app/static/app.js`

### Other components

- **Flow producer**
- **Security analyst**
- **IBM Granite**

## Connections

- Flow producer → Prediction routes: submits flows (evidence: `README.md`)
- Security analyst → Live dashboard: views alerts (evidence: `README.md`)
- FastAPI entry → Prediction routes: registers route (evidence: `app/main.py`)
- FastAPI entry → Explain routes: registers route (evidence: `app/main.py`)
- FastAPI entry → Alert routes: registers route (evidence: `app/main.py`)
- FastAPI entry → Dashboard routes: registers route (evidence: `app/main.py`)
- FastAPI entry → Database sessions: initializes database (evidence: `app/main.py`)
- Prediction routes → Flow validation: accepts features (evidence: `app/api/predictions.py`)
- Prediction routes → Model inference: predicts flow (evidence: `app/api/predictions.py`)
- Prediction routes → SHAP attribution: requests attribution (evidence: `app/api/predictions.py`)
- Prediction routes → Explanation synthesis: builds explanation (evidence: `app/api/predictions.py`)
- Prediction routes → Action recommendations: requests actions (evidence: `app/api/predictions.py`)
- Prediction routes → GenAI advisory: requests advisory (evidence: `app/api/predictions.py`)
- GenAI advisory → IBM Granite: requests generation
- Prediction routes → Alert and incidents: creates attack alert (evidence: `app/api/predictions.py`)
- Prediction routes → Alert notifications: sends notification (evidence: `app/api/predictions.py`)
- Prediction routes → Response models: returns result (evidence: `app/api/predictions.py`)
- Explain routes → Model inference: uses prediction (evidence: `app/api/explainability.py`)
- Explain routes → SHAP attribution: requests attribution (evidence: `app/api/explainability.py`)
- Explain routes → Explanation synthesis: builds explanation (evidence: `app/api/explainability.py`)
- Explain routes → GenAI advisory: requests advisory (evidence: `app/api/explainability.py`)
- Alert routes → Alert and incidents: manages alerts (evidence: `app/api/alerts.py`)
- Alert routes → Action recommendations: requests actions (evidence: `app/api/alerts.py`)
- Dashboard routes → Database sessions: queries data (evidence: `app/api/dashboard.py`)
- Alert and incidents → Alert and incident models: queries and writes (evidence: `app/services/alert_service.py`)
- Database sessions → Alert and incident models: creates tables (evidence: `app/database/session.py`)
- Database sessions → SQLite database: connects (evidence: `app/database/session.py`)
- Live dashboard → Dashboard routes: loads dashboard data
- Dashboard routes → Response models: formats responses (evidence: `app/api/dashboard.py`)