# muhil-amuthan/netsentry-ai architecture

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

- Interactive diagram: https://gitdiagram.com/muhil-amuthan/netsentry-ai
- Repository: https://github.com/muhil-amuthan/netsentry-ai

## Overview

NetSentry-AI is a telecom NOC incident-triage application. Its principal workflow turns alerts into normalized, deduplicated, correlated incidents; scores impact, retrieves runbook evidence, then recommends actions or escalates when evidence is insufficient. The API and dashboard expose incident views and an “Ask NetSentry” interface. The README documents the end-to-end stages; source excerpts and the SOURCE INDEX support the module coverage and selected connections, but not every internal call sequence.

Main entry points: [`src/api.py`](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/api.py) (FastAPI routes), [`src/database.py`](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/database.py) (In-memory state), [`src/runbook_engine.py`](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/runbook_engine.py) (Runbook retrieval), [`frontend/app.js`](https://github.com/muhil-amuthan/netsentry-ai/blob/main/frontend/app.js) (NOC dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["NOC interface"]
  node_dashboard["NOC dashboard<br/>[app.js]"]
  node_ask["Ask NetSentry<br/>[nlp_handler.py]"]
end

subgraph group_service["API and state"]
  node_api["FastAPI routes<br/>[api.py]"]
  node_store[("In-memory state<br/>[database.py]")]
end

subgraph group_triage["Incident intelligence"]
  node_models["Domain models<br/>[models.py]"]
  node_generator["Scenario alerts<br/>[generator.py]"]
  node_processor["Normalize and dedupe<br/>[processor.py]"]
  node_topology["Network topology<br/>[topology.py]"]
  node_scorer["Correlation engine<br/>[scorer.py]"]
  node_priority["Priority engine<br/>[priority.py]"]
end

subgraph group_knowledge["Evidence and response"]
  node_runbooks["Runbook documents"]
  node_retrieval["Runbook retrieval<br/>[runbook_engine.py]"]
  node_faiss[("FAISS index<br/>[index.faiss]")]
  node_recommendation["Grounded recommendations<br/>[generator.py]"]
  node_escalation["Human escalation<br/>[escalation.py]"]
end

node_noc(("NOC engineer"))
node_alert_source(("Alert feed"))
node_gemini(("Gemini AI"))

node_noc -->|"views triage"| node_dashboard
node_dashboard -->|"uses API"| node_api
node_alert_source -.->|"submits alerts"| node_api
node_api -->|"queries state"| node_store
node_store -->|"loads scenarios"| node_generator
node_store -->|"processes alerts"| node_processor
node_store -->|"correlates alerts"| node_scorer
node_scorer -->|"checks connectivity"| node_topology
node_store -->|"scores incidents"| node_priority
node_priority -->|"uses impact context"| node_topology
node_api -->|"analyzes incidents"| node_retrieval
node_retrieval -->|"loads evidence"| node_runbooks
node_retrieval -->|"retrieves matches"| node_faiss
node_retrieval -.->|"embeds queries"| node_gemini
node_api -->|"requests analysis"| node_recommendation
node_api -->|"evaluates escalation"| node_escalation
node_api -->|"answers questions"| node_ask
node_ask -->|"queries incident state"| node_store
node_store -->|"serves incident views"| node_dashboard

click node_dashboard "https://github.com/muhil-amuthan/netsentry-ai/blob/main/frontend/app.js"
click node_api "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/api.py"
click node_store "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/database.py"
click node_models "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/models.py"
click node_generator "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/generator.py"
click node_processor "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/processor.py"
click node_topology "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/topology.py"
click node_scorer "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/scorer.py"
click node_priority "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/priority.py"
click node_runbooks "https://github.com/muhil-amuthan/netsentry-ai/tree/main/data/runbooks"
click node_retrieval "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/runbook_engine.py"
click node_faiss "https://github.com/muhil-amuthan/netsentry-ai/blob/main/data/faiss_index/index.faiss"
click node_recommendation "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/generator.py"
click node_escalation "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/escalation.py"
click node_ask "https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/nlp_handler.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_dashboard,node_ask toneBlue
class node_api,node_store toneAmber
class node_models,node_generator,node_processor,node_topology,node_scorer,node_priority toneMint
class node_runbooks,node_retrieval,node_faiss,node_recommendation,node_escalation toneRose
class node_noc,node_alert_source,node_gemini toneIndigo
```

## Components

### NOC interface

- [NOC dashboard](https://github.com/muhil-amuthan/netsentry-ai/blob/main/frontend/app.js): `frontend/app.js`
- [Ask NetSentry](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/nlp_handler.py): `src/nlp_handler.py`

### API and state

- [FastAPI routes](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/api.py): `src/api.py`
- [In-memory state](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/database.py): `src/database.py`

### Incident intelligence

- [Domain models](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/models.py): `src/models.py`
- [Scenario alerts](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/generator.py): `src/generator.py`
- [Normalize and dedupe](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/processor.py): `src/processor.py`
- [Network topology](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/topology.py): `src/topology.py`
- [Correlation engine](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/scorer.py): `src/scorer.py`
- [Priority engine](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/priority.py): `src/priority.py`

### Evidence and response

- [Runbook documents](https://github.com/muhil-amuthan/netsentry-ai/tree/main/data/runbooks): `data/runbooks`
- [Runbook retrieval](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/runbook_engine.py): `src/runbook_engine.py`
- [FAISS index](https://github.com/muhil-amuthan/netsentry-ai/blob/main/data/faiss_index/index.faiss): `data/faiss_index/index.faiss`
- [Grounded recommendations](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/generator.py): `src/generator.py`
- [Human escalation](https://github.com/muhil-amuthan/netsentry-ai/blob/main/src/escalation.py): `src/escalation.py`

### Other components

- **NOC engineer**
- **Alert feed**
- **Gemini AI**

## Connections

- NOC engineer → NOC dashboard: views triage (evidence: `README.md`)
- NOC dashboard → FastAPI routes: uses API (evidence: `README.md`)
- Alert feed → FastAPI routes: submits alerts
- FastAPI routes → In-memory state: queries state (evidence: `src/api.py`)
- In-memory state → Scenario alerts: loads scenarios (evidence: `README.md`)
- In-memory state → Normalize and dedupe: processes alerts (evidence: `README.md`)
- In-memory state → Correlation engine: correlates alerts (evidence: `README.md`)
- Correlation engine → Network topology: checks connectivity (evidence: `src/scorer.py`)
- In-memory state → Priority engine: scores incidents (evidence: `README.md`)
- Priority engine → Network topology: uses impact context (evidence: `src/priority.py`)
- FastAPI routes → Runbook retrieval: analyzes incidents (evidence: `src/api.py`)
- Runbook retrieval → Runbook documents: loads evidence (evidence: `src/runbook_engine.py`)
- Runbook retrieval → FAISS index: retrieves matches (evidence: `README.md`)
- Runbook retrieval → Gemini AI: embeds queries (evidence: `src/runbook_engine.py`)
- FastAPI routes → Grounded recommendations: requests analysis (evidence: `src/api.py`)
- FastAPI routes → Human escalation: evaluates escalation (evidence: `src/api.py`)
- FastAPI routes → Ask NetSentry: answers questions (evidence: `src/api.py`)
- Ask NetSentry → In-memory state: queries incident state (evidence: `src/nlp_handler.py`)
- In-memory state → NOC dashboard: serves incident views (evidence: `README.md`)
