# akshay9024/network_anomaly architecture

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

- Interactive diagram: https://gitdiagram.com/akshay9024/network_anomaly
- Repository: https://github.com/akshay9024/network_anomaly

## Overview

Network Anomaly Root-Cause Assistant ingests a case’s telemetry and topology, detects anomalies, ranks causal hypotheses, builds an evidence ledger and timeline, then produces grounded narration and persists auditable results. Users submit cases and inspect incident analysis, dashboards, topology, impact paths, and audit history in the Next.js UI. The graph emphasizes the documented analysis flow and major capabilities. Some subsystem links are based on the README and SOURCE INDEX; unsampled implementation details are not asserted.

Main entry points: [`rca/pipeline.py`](https://github.com/akshay9024/network_anomaly/blob/main/rca/pipeline.py) (Incident Pipeline), [`rca/api/app.py`](https://github.com/akshay9024/network_anomaly/blob/main/rca/api/app.py) (FastAPI Endpoints), [`rca/causal/engine.py`](https://github.com/akshay9024/network_anomaly/blob/main/rca/causal/engine.py) (Causal Discovery), [`frontend/src/services/rca-service.ts`](https://github.com/akshay9024/network_anomaly/blob/main/frontend/src/services/rca-service.ts) (RCA Service Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Incident Dashboard<br/>[page.tsx]"]
  node_incident_views["Incident Views<br/>[page.tsx]"]
  node_topology_views["Topology Explorer<br/>[page.tsx]"]
  node_topology_graph_ui["Topology Graph<br/>[topology-graph.tsx]"]
  node_frontend_service["RCA Service Client<br/>[rca-service.ts]"]
end

subgraph group_service["API and Workflow"]
  node_api["FastAPI Endpoints<br/>[app.py]"]
  node_contract["API Contract<br/>[contract.py]"]
  node_settings["Runtime Settings<br/>[config.py]"]
end

subgraph group_analysis["Analysis"]
  node_ingest["Telemetry Ingestion"]
  node_pipeline["Incident Pipeline<br/>[pipeline.py]"]
  node_detectors["Detector Ensemble"]
  node_topology["Topology Graph<br/>[graph.py]"]
  node_causal_engine["Causal Discovery<br/>[engine.py]"]
  node_causal_rank["Cause Ranking<br/>[rank.py]"]
  node_ml_features["ML Features<br/>[features.py]"]
end

subgraph group_results["Evidence and Results"]
  node_evidence_ledger["Evidence Ledger<br/>[builder.py]"]
  node_narrator["Grounded Narration<br/>[narrator.py]"]
  node_postgres[("Postgres Repository<br/>[postgres.py]")]
end

node_operator(("Operator"))

node_operator -->|"views cases"| node_dashboard
node_dashboard -->|"requests analysis"| node_frontend_service
node_incident_views -->|"loads incident"| node_frontend_service
node_topology_views -->|"loads topology"| node_frontend_service
node_topology_views -->|"renders topology"| node_topology_graph_ui
node_frontend_service -->|"calls endpoints"| node_api
node_api -->|"validates requests"| node_contract
node_api -->|"loads case data"| node_ingest
node_api -->|"schedules analysis"| node_pipeline
node_api -->|"reads status"| node_postgres
node_pipeline -->|"runs detection"| node_detectors
node_pipeline -->|"analyzes causes"| node_causal_engine
node_causal_engine -->|"uses service graph"| node_topology
node_causal_engine -->|"ranks candidates"| node_causal_rank
node_causal_engine -->|"builds GNN features"| node_ml_features
node_pipeline -->|"builds evidence"| node_evidence_ledger
node_pipeline -->|"requests narration"| node_narrator
node_pipeline -->|"persists results"| node_postgres
node_narrator -->|"grounds incident"| node_contract
node_pipeline -->|"returns incident"| node_contract
node_api -->|"serves read results"| node_postgres
node_settings -.->|"configures service"| node_api
node_settings -.->|"configures models"| node_detectors

click node_dashboard "https://github.com/akshay9024/network_anomaly/blob/main/frontend/app/page.tsx"
click node_incident_views "https://github.com/akshay9024/network_anomaly/blob/main/frontend/app/incidents/%5Bid%5D/page.tsx"
click node_topology_views "https://github.com/akshay9024/network_anomaly/blob/main/frontend/app/topologies/%5Bid%5D/page.tsx"
click node_topology_graph_ui "https://github.com/akshay9024/network_anomaly/blob/main/frontend/components/topology-graph.tsx"
click node_frontend_service "https://github.com/akshay9024/network_anomaly/blob/main/frontend/src/services/rca-service.ts"
click node_api "https://github.com/akshay9024/network_anomaly/blob/main/rca/api/app.py"
click node_contract "https://github.com/akshay9024/network_anomaly/blob/main/rca/contract.py"
click node_ingest "https://github.com/akshay9024/network_anomaly/tree/main/rca/ingest"
click node_pipeline "https://github.com/akshay9024/network_anomaly/blob/main/rca/pipeline.py"
click node_detectors "https://github.com/akshay9024/network_anomaly/tree/main/rca/detect"
click node_topology "https://github.com/akshay9024/network_anomaly/blob/main/rca/causal/graph.py"
click node_causal_engine "https://github.com/akshay9024/network_anomaly/blob/main/rca/causal/engine.py"
click node_causal_rank "https://github.com/akshay9024/network_anomaly/blob/main/rca/causal/rank.py"
click node_ml_features "https://github.com/akshay9024/network_anomaly/blob/main/rca/ml/features.py"
click node_evidence_ledger "https://github.com/akshay9024/network_anomaly/blob/main/rca/ledger/builder.py"
click node_narrator "https://github.com/akshay9024/network_anomaly/blob/main/rca/narrate/narrator.py"
click node_postgres "https://github.com/akshay9024/network_anomaly/blob/main/rca/db/postgres.py"
click node_settings "https://github.com/akshay9024/network_anomaly/blob/main/rca/config.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_incident_views,node_topology_views,node_topology_graph_ui,node_frontend_service toneBlue
class node_api,node_contract,node_settings toneAmber
class node_ingest,node_pipeline,node_detectors,node_topology,node_causal_engine,node_causal_rank,node_ml_features toneMint
class node_evidence_ledger,node_narrator,node_postgres toneRose
class node_operator toneIndigo
```

## Components

### Dashboard

- [Incident Dashboard](https://github.com/akshay9024/network_anomaly/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Incident Views](https://github.com/akshay9024/network_anomaly/blob/main/frontend/app/incidents/%5Bid%5D/page.tsx): `frontend/app/incidents/[id]/page.tsx`
- [Topology Explorer](https://github.com/akshay9024/network_anomaly/blob/main/frontend/app/topologies/%5Bid%5D/page.tsx): `frontend/app/topologies/[id]/page.tsx`
- [Topology Graph](https://github.com/akshay9024/network_anomaly/blob/main/frontend/components/topology-graph.tsx): `frontend/components/topology-graph.tsx`
- [RCA Service Client](https://github.com/akshay9024/network_anomaly/blob/main/frontend/src/services/rca-service.ts): `frontend/src/services/rca-service.ts`

### API and Workflow

- [FastAPI Endpoints](https://github.com/akshay9024/network_anomaly/blob/main/rca/api/app.py): `rca/api/app.py`
- [API Contract](https://github.com/akshay9024/network_anomaly/blob/main/rca/contract.py): `rca/contract.py`
- [Runtime Settings](https://github.com/akshay9024/network_anomaly/blob/main/rca/config.py): `rca/config.py`

### Analysis

- [Telemetry Ingestion](https://github.com/akshay9024/network_anomaly/tree/main/rca/ingest): `rca/ingest`
- [Incident Pipeline](https://github.com/akshay9024/network_anomaly/blob/main/rca/pipeline.py): `rca/pipeline.py`
- [Detector Ensemble](https://github.com/akshay9024/network_anomaly/tree/main/rca/detect): `rca/detect`
- [Topology Graph](https://github.com/akshay9024/network_anomaly/blob/main/rca/causal/graph.py): `rca/causal/graph.py`
- [Causal Discovery](https://github.com/akshay9024/network_anomaly/blob/main/rca/causal/engine.py): `rca/causal/engine.py`
- [Cause Ranking](https://github.com/akshay9024/network_anomaly/blob/main/rca/causal/rank.py): `rca/causal/rank.py`
- [ML Features](https://github.com/akshay9024/network_anomaly/blob/main/rca/ml/features.py): `rca/ml/features.py`

### Evidence and Results

- [Evidence Ledger](https://github.com/akshay9024/network_anomaly/blob/main/rca/ledger/builder.py): `rca/ledger/builder.py`
- [Grounded Narration](https://github.com/akshay9024/network_anomaly/blob/main/rca/narrate/narrator.py): `rca/narrate/narrator.py`
- [Postgres Repository](https://github.com/akshay9024/network_anomaly/blob/main/rca/db/postgres.py): `rca/db/postgres.py`

### Other components

- **Operator**

## Connections

- Operator → Incident Dashboard: views cases
- Incident Dashboard → RCA Service Client: requests analysis
- Incident Views → RCA Service Client: loads incident
- Topology Explorer → RCA Service Client: loads topology
- Topology Explorer → Topology Graph: renders topology (evidence: `frontend/app/topologies/[id]/page.tsx`)
- RCA Service Client → FastAPI Endpoints: calls endpoints
- FastAPI Endpoints → API Contract: validates requests (evidence: `rca/api/app.py`)
- FastAPI Endpoints → Telemetry Ingestion: loads case data (evidence: `rca/api/app.py`)
- FastAPI Endpoints → Incident Pipeline: schedules analysis (evidence: `rca/api/app.py`)
- FastAPI Endpoints → Postgres Repository: reads status (evidence: `rca/api/app.py`)
- Incident Pipeline → Detector Ensemble: runs detection (evidence: `rca/pipeline.py`)
- Incident Pipeline → Causal Discovery: analyzes causes (evidence: `rca/pipeline.py`)
- Causal Discovery → Topology Graph: uses service graph (evidence: `rca/causal/engine.py`)
- Causal Discovery → Cause Ranking: ranks candidates (evidence: `rca/causal/engine.py`)
- Causal Discovery → ML Features: builds GNN features (evidence: `rca/causal/engine.py`)
- Incident Pipeline → Evidence Ledger: builds evidence (evidence: `rca/pipeline.py`)
- Incident Pipeline → Grounded Narration: requests narration (evidence: `rca/pipeline.py`)
- Incident Pipeline → Postgres Repository: persists results (evidence: `rca/pipeline.py`)
- Grounded Narration → API Contract: grounds incident (evidence: `rca/narrate/narrator.py`)
- Incident Pipeline → API Contract: returns incident (evidence: `rca/pipeline.py`)
- FastAPI Endpoints → Postgres Repository: serves read results (evidence: `rca/api/app.py`)
- Runtime Settings → FastAPI Endpoints: configures service (evidence: `rca/api/app.py`)
- Runtime Settings → Detector Ensemble: configures models (evidence: `rca/detect/dl_deeplog.py`)