# don-gabriel/medgraph-sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/don-gabriel/medgraph-sentinel
- Repository: https://github.com/don-gabriel/medgraph-sentinel

## Overview

MedGraph Sentinel generates a reproducible synthetic medical-tourism economy, loads its graph into Neo4j, and runs graph-based fraud detection to produce scored alerts. Investigators then use the console’s queue-to-case workflow to inspect an alert’s evidence subgraph and narration and record a disposition. The README documents detection and narration as offline build-time outputs; runtime serves committed alert and narration data. Some capability links are README-based because the relevant implementation was not sampled.

Main entry points: [`detection/run.py`](https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/run.py) (Detection run), [`api/alerts.py`](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/alerts.py) (Alert endpoints), [`frontend/src/components/AlertView.jsx`](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/AlertView.jsx) (Alert case view), [`frontend/src/App.jsx`](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/App.jsx) (Console app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Synthetic data"]
  node_generator["Economy generator<br/>[economy.py]"]
  node_fraud["Fraud overlays<br/>[fraud.py]"]
  node_scenarios["Scenario overlays<br/>[scenario.py]"]
  node_loader["Graph loader<br/>[load.py]"]
  node_graphdb[("Neo4j graph")]
end

subgraph group_detect["Fraud detection"]
  node_detection["Detection run<br/>[run.py]"]
  node_rule_common["Rule helpers<br/>[common.py]"]
  node_ghost_rule["Ghost clinic rule<br/>[ghost_clinic.py]"]
  node_travel_rule["Impossible travel rule"]
  node_kickback_rule["Kickback ring rule<br/>[kickback_ring.py]"]
  node_credential_rule["Credential laundering rule"]
  node_alert_exports["Alert exports<br/>[export.py]"]
end

subgraph group_serve["API and graph access"]
  node_api_main["FastAPI service<br/>[main.py]"]
  node_alerts["Alert endpoints<br/>[alerts.py]"]
  node_entities["Entity endpoints<br/>[entities.py]"]
  node_graph_access["Neo4j access<br/>[graph.py]"]
  node_subgraph["Evidence subgraphs<br/>[subgraph.py]"]
  node_narration_cache["Narration build<br/>[build.py]"]
  node_narration_fallback["Narration fallback<br/>[fallback.py]"]
  node_narration_live["Optional live narration<br/>[live.py]"]
end

subgraph group_console["Investigator console"]
  node_app["Console app<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_alert_view["Alert case view<br/>[AlertView.jsx]"]
  node_queue["Alert queue<br/>[AlertQueue.jsx]"]
  node_case_file["Evidence case file<br/>[CaseFile.jsx]"]
  node_disposition["Review disposition<br/>[Disposition.jsx]"]
  node_subgraph_canvas["Subgraph canvas<br/>[SubgraphCanvas.jsx]"]
  node_graph_style["Graph styling<br/>[graphStyle.js]"]
  node_format["Evidence formatting<br/>[format.js]"]
end

node_investigator(("Investigator"))

node_generator -->|"uses parameters"| node_fraud
node_scenarios -->|"extends economy"| node_generator
node_scenarios -->|"uses overlays"| node_fraud
node_generator -.->|"writes dataset"| node_loader
node_loader -->|"loads graph"| node_graphdb
node_detection -->|"queries graph"| node_graphdb
node_detection -.->|"runs rule"| node_ghost_rule
node_detection -.->|"runs rule"| node_travel_rule
node_detection -.->|"runs rule"| node_kickback_rule
node_detection -.->|"runs rule"| node_credential_rule
node_ghost_rule -->|"uses helpers"| node_rule_common
node_kickback_rule -->|"uses helpers"| node_rule_common
node_detection -->|"exports alerts"| node_alert_exports
node_alert_exports -->|"committed alert data"| node_graphdb
node_detection -->|"builds narration"| node_narration_cache
node_api_main -->|"mounts routes"| node_alerts
node_api_main -->|"mounts routes"| node_entities
node_alerts -->|"queries graph"| node_graph_access
node_entities -->|"uses access"| node_graph_access
node_graph_access -->|"reads and writes"| node_graphdb
node_alerts -->|"builds evidence"| node_subgraph
node_alerts -->|"reads cache"| node_narration_cache
node_alerts -->|"uses fallback"| node_narration_fallback
node_alerts -.->|"optional narration"| node_narration_live
node_investigator -->|"reviews alerts"| node_app
node_app -->|"requests data"| node_api_client
node_app -->|"renders queue"| node_queue
node_app -->|"opens case"| node_alert_view
node_alert_view -->|"fetches case data"| node_api_client
node_api_client -->|"HTTP JSON"| node_api_main
node_alert_view -->|"renders evidence"| node_subgraph_canvas
node_alert_view -->|"shows evidence"| node_case_file
node_alert_view -->|"offers review"| node_disposition
node_alert_view -->|"uses status display"| node_queue
node_subgraph_canvas -->|"applies styles"| node_graph_style
node_subgraph_canvas -->|"formats labels"| node_format
node_case_file -->|"formats evidence"| node_format
node_case_file -->|"uses graph styles"| node_graph_style
node_queue -->|"formats alerts"| node_format
node_disposition -->|"uses case content"| node_case_file

click node_generator "https://github.com/don-gabriel/medgraph-sentinel/blob/main/generator/economy.py"
click node_fraud "https://github.com/don-gabriel/medgraph-sentinel/blob/main/generator/fraud.py"
click node_scenarios "https://github.com/don-gabriel/medgraph-sentinel/blob/main/generator/scenario.py"
click node_loader "https://github.com/don-gabriel/medgraph-sentinel/blob/main/loader/load.py"
click node_detection "https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/run.py"
click node_rule_common "https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/common.py"
click node_ghost_rule "https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/ghost_clinic.py"
click node_travel_rule "https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/impossible_travel.py"
click node_kickback_rule "https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/kickback_ring.py"
click node_credential_rule "https://github.com/don-gabriel/medgraph-sentinel/tree/main/detection/rules/impl"
click node_alert_exports "https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/export.py"
click node_api_main "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/main.py"
click node_alerts "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/alerts.py"
click node_entities "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/entities.py"
click node_graph_access "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/graph.py"
click node_subgraph "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/subgraph.py"
click node_narration_cache "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/narration/build.py"
click node_narration_fallback "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/narration/fallback.py"
click node_narration_live "https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/narration/live.py"
click node_app "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/api.js"
click node_alert_view "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/AlertView.jsx"
click node_queue "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/AlertQueue.jsx"
click node_case_file "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/CaseFile.jsx"
click node_disposition "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/Disposition.jsx"
click node_subgraph_canvas "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/SubgraphCanvas.jsx"
click node_graph_style "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/lib/graphStyle.js"
click node_format "https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/lib/format.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_generator,node_fraud,node_scenarios,node_loader,node_graphdb toneBlue
class node_detection,node_rule_common,node_ghost_rule,node_travel_rule,node_kickback_rule,node_credential_rule,node_alert_exports toneAmber
class node_api_main,node_alerts,node_entities,node_graph_access,node_subgraph,node_narration_cache,node_narration_fallback,node_narration_live toneMint
class node_app,node_api_client,node_alert_view,node_queue,node_case_file,node_disposition,node_subgraph_canvas,node_graph_style,node_format toneRose
class node_investigator toneIndigo
```

## Components

### Synthetic data

- [Economy generator](https://github.com/don-gabriel/medgraph-sentinel/blob/main/generator/economy.py): `generator/economy.py`
- [Fraud overlays](https://github.com/don-gabriel/medgraph-sentinel/blob/main/generator/fraud.py): `generator/fraud.py`
- [Scenario overlays](https://github.com/don-gabriel/medgraph-sentinel/blob/main/generator/scenario.py): `generator/scenario.py`
- [Graph loader](https://github.com/don-gabriel/medgraph-sentinel/blob/main/loader/load.py): `loader/load.py`
- **Neo4j graph**

### Fraud detection

- [Detection run](https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/run.py): `detection/run.py`
- [Rule helpers](https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/common.py): `detection/rules/impl/common.py`
- [Ghost clinic rule](https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/ghost_clinic.py): `detection/rules/impl/ghost_clinic.py`
- [Impossible travel rule](https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/impossible_travel.py): `detection/rules/impl/impossible_travel.py`
- [Kickback ring rule](https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/rules/impl/kickback_ring.py): `detection/rules/impl/kickback_ring.py`
- [Credential laundering rule](https://github.com/don-gabriel/medgraph-sentinel/tree/main/detection/rules/impl): `detection/rules/impl`
- [Alert exports](https://github.com/don-gabriel/medgraph-sentinel/blob/main/detection/export.py): `detection/export.py`

### API and graph access

- [FastAPI service](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/main.py): `api/main.py`
- [Alert endpoints](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/alerts.py): `api/alerts.py`
- [Entity endpoints](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/entities.py): `api/entities.py`
- [Neo4j access](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/graph.py): `api/graph.py`
- [Evidence subgraphs](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/subgraph.py): `api/subgraph.py`
- [Narration build](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/narration/build.py): `api/narration/build.py`
- [Narration fallback](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/narration/fallback.py): `api/narration/fallback.py`
- [Optional live narration](https://github.com/don-gabriel/medgraph-sentinel/blob/main/api/narration/live.py): `api/narration/live.py`

### Investigator console

- [Console app](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Alert case view](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/AlertView.jsx): `frontend/src/components/AlertView.jsx`
- [Alert queue](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/AlertQueue.jsx): `frontend/src/components/AlertQueue.jsx`
- [Evidence case file](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/CaseFile.jsx): `frontend/src/components/CaseFile.jsx`
- [Review disposition](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/Disposition.jsx): `frontend/src/components/Disposition.jsx`
- [Subgraph canvas](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/components/SubgraphCanvas.jsx): `frontend/src/components/SubgraphCanvas.jsx`
- [Graph styling](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/lib/graphStyle.js): `frontend/src/lib/graphStyle.js`
- [Evidence formatting](https://github.com/don-gabriel/medgraph-sentinel/blob/main/frontend/src/lib/format.js): `frontend/src/lib/format.js`

### Other components

- **Investigator**

## Connections

- Economy generator → Fraud overlays: uses parameters (evidence: `generator/economy.py`)
- Scenario overlays → Economy generator: extends economy (evidence: `generator/scenario.py`)
- Scenario overlays → Fraud overlays: uses overlays (evidence: `generator/scenario.py`)
- Economy generator → Graph loader: writes dataset
- Graph loader → Neo4j graph: loads graph (evidence: `README.md`)
- Detection run → Neo4j graph: queries graph (evidence: `README.md`)
- Detection run → Ghost clinic rule: runs rule
- Detection run → Impossible travel rule: runs rule
- Detection run → Kickback ring rule: runs rule
- Detection run → Credential laundering rule: runs rule
- Ghost clinic rule → Rule helpers: uses helpers (evidence: `detection/rules/impl/ghost_clinic.py`)
- Kickback ring rule → Rule helpers: uses helpers (evidence: `detection/rules/impl/kickback_ring.py`)
- Detection run → Alert exports: exports alerts (evidence: `README.md`)
- Alert exports → Neo4j graph: committed alert data (evidence: `README.md`)
- Detection run → Narration build: builds narration (evidence: `README.md`)
- FastAPI service → Alert endpoints: mounts routes (evidence: `api/main.py`)
- FastAPI service → Entity endpoints: mounts routes (evidence: `api/main.py`)
- Alert endpoints → Neo4j access: queries graph (evidence: `api/alerts.py`)
- Entity endpoints → Neo4j access: uses access (evidence: `api/entities.py`)
- Neo4j access → Neo4j graph: reads and writes (evidence: `README.md`)
- Alert endpoints → Evidence subgraphs: builds evidence (evidence: `api/alerts.py`)
- Alert endpoints → Narration build: reads cache (evidence: `api/alerts.py`)
- Alert endpoints → Narration fallback: uses fallback (evidence: `api/alerts.py`)
- Alert endpoints → Optional live narration: optional narration (evidence: `api/alerts.py`)
- Investigator → Console app: reviews alerts (evidence: `README.md`)
- Console app → API client: requests data (evidence: `frontend/src/App.jsx`)
- Console app → Alert queue: renders queue (evidence: `frontend/src/App.jsx`)
- Console app → Alert case view: opens case (evidence: `frontend/src/App.jsx`)
- Alert case view → API client: fetches case data (evidence: `frontend/src/components/AlertView.jsx`)
- API client → FastAPI service: HTTP JSON (evidence: `README.md`)
- Alert case view → Subgraph canvas: renders evidence (evidence: `frontend/src/components/AlertView.jsx`)
- Alert case view → Evidence case file: shows evidence (evidence: `frontend/src/components/AlertView.jsx`)
- Alert case view → Review disposition: offers review (evidence: `frontend/src/components/AlertView.jsx`)
- Alert case view → Alert queue: uses status display (evidence: `frontend/src/components/AlertView.jsx`)
- Subgraph canvas → Graph styling: applies styles (evidence: `frontend/src/components/SubgraphCanvas.jsx`)
- Subgraph canvas → Evidence formatting: formats labels (evidence: `frontend/src/components/SubgraphCanvas.jsx`)
- Evidence case file → Evidence formatting: formats evidence (evidence: `frontend/src/components/CaseFile.jsx`)
- Evidence case file → Graph styling: uses graph styles (evidence: `frontend/src/components/CaseFile.jsx`)
- Alert queue → Evidence formatting: formats alerts (evidence: `frontend/src/components/AlertQueue.jsx`)
- Review disposition → Evidence case file: uses case content (evidence: `frontend/src/components/Disposition.jsx`)
