# hemanth2607-cyber/aegis-cyber-cashout architecture

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

- Interactive diagram: https://gitdiagram.com/hemanth2607-cyber/aegis-cyber-cashout
- Repository: https://github.com/hemanth2607-cyber/aegis-cyber-cashout

## Overview

AEGIS-CYBER forecasts likely cybercrime cash-out locations and supports rapid police interdiction, with an evidence ledger and operational dashboard. The intended flow is complaint ingestion, transaction-graph and spatial analysis, dual-stage forecasting with explanations, then dispatch/interdiction and docketing. The frontend also presents live alerts, ledger inspection, and a staged tactical simulation. Several backend services and surveillance details are unsampled; edges below follow shown imports, calls, route registration, or README claims rather than assuming connections from names alone.

Main entry points: [`backend/main.py`](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/main.py) (API application), [`backend/services/ml_service.py`](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/ml_service.py) (Prediction service), [`backend/services/graph_service.py`](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/graph_service.py) (Graph service), [`backend/routes/interventions.py`](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/interventions.py) (Intervention API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_app["API application<br/>[main.py]"]
  node_complaints["Complaint intake<br/>[complaints.py]"]
  node_predictions["Prediction API<br/>[predictions.py]"]
  node_docket["Docket API<br/>[docket.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
end

subgraph group_analysis["Risk analytics"]
  node_graphsvc["Graph service<br/>[graph_service.py]"]
  node_graphengine["Transaction graph<br/>[graph_engine.py]"]
  node_spatial["Spatial index<br/>[spatial_indexer.py]"]
  node_featurepipe["Feature pipeline<br/>[pipeline.py]"]
  node_mlsvc["Prediction service<br/>[ml_service.py]"]
  node_inference["ML inference<br/>[inference.py]"]
  node_explainer["Tactical explanation<br/>[explainer.py]"]
end

subgraph group_response["Intervention &amp; evidence"]
  node_interventions["Intervention API<br/>[interventions.py]"]
  node_interdiction["Interdiction logic"]
  node_hardware["Hardware bridge<br/>[hardware_bridge.py]"]
  node_surveillance["Surveillance API<br/>[surveillance.py]"]
  node_vision["Vision emulator<br/>[vision_emulator.py]"]
  node_ledgerapi["Ledger API"]
  node_ledger[("Sentinel ledger")]
  node_docketgen["Docket generator"]
  node_ws["Alert WebSocket<br/>[websocket.py]"]
end

subgraph group_client["Operator experience"]
  node_dashboard["Operations dashboard<br/>[page.tsx]"]
  node_simpage["Simulation view<br/>[page.tsx]"]
  node_journey["Journey map"]
  node_inspector["Algorithm inspector"]
  node_timeline["Simulation timeline"]
  node_blockexplorer["Block explorer"]
  node_alerts["Realtime alert hook"]
end

subgraph group_data["Feature data"]
  node_generator["Synthetic data generation<br/>[generate_data.py]"]
  node_dataconfig["Data configuration<br/>[config.py]"]
end

node_operator(("Investigator"))
node_atm["ATM / kiosk"]

node_app -->|"registers route"| node_complaints
node_app -->|"registers route"| node_predictions
node_app -->|"registers route"| node_interventions
node_app -->|"registers route"| node_docket
node_app -->|"registers route"| node_surveillance
node_app -->|"registers route"| node_ledgerapi
node_complaints -->|"registers complaint"| node_graphsvc
node_complaints -->|"requests prediction"| node_mlsvc
node_complaints -->|"records incident"| node_ledger
node_predictions -->|"requests forecast"| node_mlsvc
node_predictions -->|"reads features"| node_graphsvc
node_graphsvc -->|"uses graph"| node_graphengine
node_graphsvc -->|"uses spatial index"| node_spatial
node_featurepipe -->|"builds transaction graph"| node_graphengine
node_featurepipe -->|"enriches features"| node_spatial
node_mlsvc -->|"uses graph features"| node_graphsvc
node_mlsvc -->|"runs inference"| node_inference
node_mlsvc -->|"builds explanation"| node_explainer
node_interventions -->|"requests interdiction"| node_interdiction
node_interventions -->|"bridges dispatch"| node_hardware
node_interventions -->|"requests surveillance"| node_vision
node_interventions -->|"records intervention"| node_ledger
node_surveillance -->|"requests vision"| node_vision
node_ledgerapi -->|"queries ledger"| node_ledger
node_docket -->|"reads graph data"| node_graphsvc
node_docket -->|"reads prediction"| node_mlsvc
node_docket -->|"generates docket"| node_docketgen
node_operator -->|"operates"| node_dashboard
node_dashboard -->|"submits complaint"| node_complaints
node_dashboard -->|"uses live alerts"| node_alerts
node_alerts -->|"receives messages"| node_ws
node_operator -->|"inspects simulation"| node_simpage
node_simpage -->|"renders journey"| node_journey
node_simpage -->|"renders analysis"| node_inspector
node_simpage -->|"controls stages"| node_timeline
node_operator -->|"inspects ledger"| node_blockexplorer
node_generator -->|"loads configuration"| node_dataconfig
node_hardware -.->|"signals terminal"| node_atm

click node_app "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/main.py"
click node_complaints "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/complaints.py"
click node_predictions "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/predictions.py"
click node_docket "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/docket.py"
click node_schemas "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/schemas.py"
click node_graphsvc "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/graph_service.py"
click node_graphengine "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/features/graph_engine.py"
click node_spatial "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/features/spatial_indexer.py"
click node_featurepipe "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/features/pipeline.py"
click node_mlsvc "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/ml_service.py"
click node_inference "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/ml_models/inference.py"
click node_explainer "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/ml_models/explainer.py"
click node_interventions "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/interventions.py"
click node_interdiction "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/interdiction_service.py"
click node_hardware "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/hardware_bridge.py"
click node_surveillance "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/surveillance.py"
click node_vision "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/vision_emulator.py"
click node_ledgerapi "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/blockchain_routes.py"
click node_ledger "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/blockchain_engine.py"
click node_docketgen "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/docket_generator.py"
click node_ws "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/websocket.py"
click node_dashboard "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/app/dashboard/page.tsx"
click node_simpage "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/app/simulation/page.tsx"
click node_journey "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/components/TacticalJourneyMap.tsx"
click node_inspector "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/components/AlgorithmRealityInspector.tsx"
click node_timeline "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/state/simulationTimeline.ts"
click node_blockexplorer "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/components/ConsortiumBlockExplorer.tsx"
click node_alerts "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/hooks/useRealtimeAlerts.ts"
click node_generator "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/data_generator/generate_data.py"
click node_dataconfig "https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/data_generator/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_app,node_complaints,node_predictions,node_docket,node_schemas toneBlue
class node_graphsvc,node_graphengine,node_spatial,node_featurepipe,node_mlsvc,node_inference,node_explainer toneAmber
class node_interventions,node_interdiction,node_hardware,node_surveillance,node_vision,node_ledgerapi,node_ledger,node_docketgen,node_ws toneMint
class node_dashboard,node_simpage,node_journey,node_inspector,node_timeline,node_blockexplorer,node_alerts toneRose
class node_generator,node_dataconfig,node_operator,node_atm toneIndigo
```

## Components

### API workflows

- [API application](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/main.py): `backend/main.py`
- [Complaint intake](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/complaints.py): `backend/routes/complaints.py`
- [Prediction API](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/predictions.py): `backend/routes/predictions.py`
- [Docket API](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/docket.py): `backend/routes/docket.py`
- [Request schemas](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/schemas.py): `backend/schemas.py`

### Risk analytics

- [Graph service](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/graph_service.py): `backend/services/graph_service.py`
- [Transaction graph](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/features/graph_engine.py): `features/graph_engine.py`
- [Spatial index](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/features/spatial_indexer.py): `features/spatial_indexer.py`
- [Feature pipeline](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/features/pipeline.py): `features/pipeline.py`
- [Prediction service](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/ml_service.py): `backend/services/ml_service.py`
- [ML inference](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/ml_models/inference.py): `ml_models/inference.py`
- [Tactical explanation](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/ml_models/explainer.py): `ml_models/explainer.py`

### Intervention & evidence

- [Intervention API](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/interventions.py): `backend/routes/interventions.py`
- [Interdiction logic](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/interdiction_service.py): `backend/services/interdiction_service.py`
- [Hardware bridge](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/hardware_bridge.py): `backend/services/hardware_bridge.py`
- [Surveillance API](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/surveillance.py): `backend/routes/surveillance.py`
- [Vision emulator](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/vision_emulator.py): `backend/services/vision_emulator.py`
- [Ledger API](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/routes/blockchain_routes.py): `backend/routes/blockchain_routes.py`
- [Sentinel ledger](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/blockchain_engine.py): `backend/services/blockchain_engine.py`
- [Docket generator](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/services/docket_generator.py): `backend/services/docket_generator.py`
- [Alert WebSocket](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/backend/websocket.py): `backend/websocket.py`

### Operator experience

- [Operations dashboard](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Simulation view](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/app/simulation/page.tsx): `frontend/app/simulation/page.tsx`
- [Journey map](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/components/TacticalJourneyMap.tsx): `frontend/components/TacticalJourneyMap.tsx`
- [Algorithm inspector](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/components/AlgorithmRealityInspector.tsx): `frontend/components/AlgorithmRealityInspector.tsx`
- [Simulation timeline](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/state/simulationTimeline.ts): `frontend/state/simulationTimeline.ts`
- [Block explorer](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/components/ConsortiumBlockExplorer.tsx): `frontend/components/ConsortiumBlockExplorer.tsx`
- [Realtime alert hook](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/frontend/hooks/useRealtimeAlerts.ts): `frontend/hooks/useRealtimeAlerts.ts`

### Feature data

- [Synthetic data generation](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/data_generator/generate_data.py): `data_generator/generate_data.py`
- [Data configuration](https://github.com/hemanth2607-cyber/aegis-cyber-cashout/blob/main/data_generator/config.py): `data_generator/config.py`

### Other components

- **Investigator**
- **ATM / kiosk**

## Connections

- API application → Complaint intake: registers route (evidence: `backend/main.py`)
- API application → Prediction API: registers route (evidence: `backend/main.py`)
- API application → Intervention API: registers route (evidence: `backend/main.py`)
- API application → Docket API: registers route (evidence: `backend/main.py`)
- API application → Surveillance API: registers route (evidence: `backend/main.py`)
- API application → Ledger API: registers route (evidence: `backend/main.py`)
- Complaint intake → Graph service: registers complaint (evidence: `backend/routes/complaints.py`)
- Complaint intake → Prediction service: requests prediction (evidence: `backend/routes/complaints.py`)
- Complaint intake → Sentinel ledger: records incident (evidence: `backend/routes/complaints.py`)
- Prediction API → Prediction service: requests forecast (evidence: `backend/routes/predictions.py`)
- Prediction API → Graph service: reads features (evidence: `backend/routes/predictions.py`)
- Graph service → Transaction graph: uses graph (evidence: `backend/services/graph_service.py`)
- Graph service → Spatial index: uses spatial index (evidence: `backend/services/graph_service.py`)
- Feature pipeline → Transaction graph: builds transaction graph (evidence: `features/pipeline.py`)
- Feature pipeline → Spatial index: enriches features (evidence: `features/pipeline.py`)
- Prediction service → Graph service: uses graph features (evidence: `backend/services/ml_service.py`)
- Prediction service → ML inference: runs inference (evidence: `backend/services/ml_service.py`)
- Prediction service → Tactical explanation: builds explanation (evidence: `backend/services/ml_service.py`)
- Intervention API → Interdiction logic: requests interdiction (evidence: `backend/routes/interventions.py`)
- Intervention API → Hardware bridge: bridges dispatch (evidence: `backend/routes/interventions.py`)
- Intervention API → Vision emulator: requests surveillance (evidence: `backend/routes/interventions.py`)
- Intervention API → Sentinel ledger: records intervention (evidence: `backend/routes/interventions.py`)
- Surveillance API → Vision emulator: requests vision (evidence: `backend/routes/surveillance.py`)
- Ledger API → Sentinel ledger: queries ledger (evidence: `backend/routes/blockchain_routes.py`)
- Docket API → Graph service: reads graph data (evidence: `backend/routes/docket.py`)
- Docket API → Prediction service: reads prediction (evidence: `backend/routes/docket.py`)
- Docket API → Docket generator: generates docket (evidence: `backend/routes/docket.py`)
- Investigator → Operations dashboard: operates (evidence: `frontend/app/dashboard/page.tsx`)
- Operations dashboard → Complaint intake: submits complaint (evidence: `frontend/app/dashboard/page.tsx`)
- Operations dashboard → Realtime alert hook: uses live alerts (evidence: `frontend/app/dashboard/page.tsx`)
- Realtime alert hook → Alert WebSocket: receives messages (evidence: `frontend/hooks/useRealtimeAlerts.ts`)
- Investigator → Simulation view: inspects simulation (evidence: `frontend/app/simulation/page.tsx`)
- Simulation view → Journey map: renders journey (evidence: `frontend/app/simulation/page.tsx`)
- Simulation view → Algorithm inspector: renders analysis (evidence: `frontend/app/simulation/page.tsx`)
- Simulation view → Simulation timeline: controls stages
- Investigator → Block explorer: inspects ledger
- Synthetic data generation → Data configuration: loads configuration (evidence: `data_generator/generate_data.py`)
- Hardware bridge → ATM / kiosk: signals terminal
