# shrankhalalala/digital_twin architecture

> Architecture diagram of the GitHub repository shrankhalalala/digital_twin, 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/shrankhalalala/digital_twin
- Repository: https://github.com/shrankhalalala/digital_twin

## Overview

This is a supply-chain digital twin: operators inspect a network, inject disruptions, run simulations, and review risk, inventory, routing recommendations, and explanations. The browser dashboard presents graph and map views alongside simulation, metrics, routing, and explainability controls; backend APIs manage the graph and dispatch simulation work. The simulation worker runs the in-memory timestep engine and publishes state to Redis. Graph persistence uses Neo4j. The README documents causal scoring, optimization, and telemetry capabilities, but sampled code does not establish all their wiring; those uncertain connections are omitted.

Main entry points: [`frontend/src/app/page.tsx`](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/app/page.tsx) (Dashboard page), [`backend/app/main.py`](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/main.py) (FastAPI application), [`backend/app/services/simulation_service.py`](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/simulation_service.py) (Simulation engine), [`backend/app/workers/simulation_worker.py`](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/workers/simulation_worker.py) (Simulation worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator dashboard"]
  node_dashboard["Dashboard page<br/>[page.tsx]"]
  node_graphview["Graph canvas<br/>[GraphCanvas.tsx]"]
  node_mapview["Geographic map<br/>[MapCanvas.tsx]"]
  node_stateui["Client state<br/>[graphStore.ts]"]
  node_simcontrols["Simulation controls"]
  node_metrics["Metrics panel<br/>[MetricsPanel.tsx]"]
  node_routingui["Routing controls"]
  node_explainui["Explainability panel"]
end

subgraph group_api["API and graph domain"]
  node_apiapp["FastAPI application<br/>[main.py]"]
  node_graphapi["Graph API<br/>[graph.py]"]
  node_devapi["Development API<br/>[dev.py]"]
  node_routingapi["Routing API<br/>[routing.py]"]
  node_simapi["Simulation API<br/>[simulation.py]"]
  node_graphsvc["Graph operations<br/>[graph_service.py]"]
  node_devsvc["Graph seeding<br/>[dev_service.py]"]
  node_graphschema["Graph data schema<br/>[graph.py]"]
end

subgraph group_compute["Simulation and intelligence"]
  node_simengine["Simulation engine"]
  node_causal["Causal risk analysis"]
  node_optimization["Inventory optimization"]
  node_routingmodel["Delay prediction"]
end

subgraph group_state["Persistence and jobs"]
  node_worker["Simulation worker"]
  node_neoaccess["Neo4j connection<br/>[neo4j.py]"]
  node_neostore[("Supply network")]
  node_redisaccess["Redis connection<br/>[redis.py]"]
  node_redisstore[("Simulation state")]
  node_celery["Celery task queue<br/>[celery_app.py]"]
end

node_operator(("Supply-chain operator"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_graphview
node_dashboard -->|"renders"| node_mapview
node_dashboard -->|"renders"| node_simcontrols
node_dashboard -->|"renders"| node_metrics
node_dashboard -->|"renders"| node_routingui
node_dashboard -->|"renders"| node_explainui
node_graphview -->|"shares state"| node_stateui
node_mapview -->|"shares state"| node_stateui
node_stateui -->|"HTTP / WS"| node_apiapp
node_apiapp -->|"registers"| node_graphapi
node_apiapp -->|"registers"| node_devapi
node_apiapp -->|"registers"| node_routingapi
node_apiapp -->|"registers"| node_simapi
node_graphapi -->|"delegates to"| node_graphsvc
node_graphsvc -.->|"uses session"| node_neoaccess
node_neoaccess -->|"reads / writes"| node_neostore
node_graphsvc -->|"validates data"| node_graphschema
node_devapi -->|"delegates to"| node_devsvc
node_devsvc -->|"imports subgraph"| node_graphsvc
node_devsvc -->|"builds seed data"| node_graphschema
node_routingapi -->|"predicts delay"| node_routingmodel
node_simapi -->|"dispatches task"| node_worker
node_worker -->|"runs"| node_simengine
node_worker -->|"registered task"| node_celery
node_simengine -->|"predicts propagation"| node_causal
node_simengine -->|"requests actions"| node_optimization
node_simengine -.->|"loads network"| node_neoaccess
node_simengine -->|"writes updates"| node_redisaccess
node_worker -->|"updates status"| node_redisaccess
node_redisaccess -->|"reads / writes"| node_redisstore

click node_dashboard "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/app/page.tsx"
click node_graphview "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/graph/GraphCanvas.tsx"
click node_mapview "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/graph/MapCanvas.tsx"
click node_stateui "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/store/graphStore.ts"
click node_simcontrols "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/SimulationPanel.tsx"
click node_metrics "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/MetricsPanel.tsx"
click node_routingui "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/RoutingControlPanel.tsx"
click node_explainui "https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/ExplainabilityPanel.tsx"
click node_apiapp "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/main.py"
click node_graphapi "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/graph.py"
click node_devapi "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/dev.py"
click node_routingapi "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/routing.py"
click node_simapi "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/simulation.py"
click node_graphsvc "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/graph_service.py"
click node_devsvc "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/dev_service.py"
click node_graphschema "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/schemas/graph.py"
click node_simengine "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/simulation_service.py"
click node_causal "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/ml_causal_service.py"
click node_optimization "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/ml_optimization_service.py"
click node_routingmodel "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/ml_routing_service.py"
click node_worker "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/workers/simulation_worker.py"
click node_neoaccess "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/db/neo4j.py"
click node_redisaccess "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/db/redis.py"
click node_celery "https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/celery_app.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_graphview,node_mapview,node_stateui,node_simcontrols,node_metrics,node_routingui,node_explainui toneBlue
class node_apiapp,node_graphapi,node_devapi,node_routingapi,node_simapi,node_graphsvc,node_devsvc,node_graphschema toneAmber
class node_simengine,node_causal,node_optimization,node_routingmodel toneMint
class node_worker,node_neoaccess,node_neostore,node_redisaccess,node_redisstore,node_celery toneRose
class node_operator toneIndigo
```

## Components

### Operator dashboard

- [Dashboard page](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Graph canvas](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/graph/GraphCanvas.tsx): `frontend/src/components/graph/GraphCanvas.tsx`
- [Geographic map](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/graph/MapCanvas.tsx): `frontend/src/components/graph/MapCanvas.tsx`
- [Client state](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/store/graphStore.ts): `frontend/src/store/graphStore.ts`
- [Simulation controls](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/SimulationPanel.tsx): `frontend/src/components/dashboard/SimulationPanel.tsx`
- [Metrics panel](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/MetricsPanel.tsx): `frontend/src/components/dashboard/MetricsPanel.tsx`
- [Routing controls](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/RoutingControlPanel.tsx): `frontend/src/components/dashboard/RoutingControlPanel.tsx`
- [Explainability panel](https://github.com/shrankhalalala/digital_twin/blob/master/frontend/src/components/dashboard/ExplainabilityPanel.tsx): `frontend/src/components/dashboard/ExplainabilityPanel.tsx`

### API and graph domain

- [FastAPI application](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/main.py): `backend/app/main.py`
- [Graph API](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/graph.py): `backend/app/api/graph.py`
- [Development API](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/dev.py): `backend/app/api/dev.py`
- [Routing API](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/routing.py): `backend/app/api/routing.py`
- [Simulation API](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Graph operations](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/graph_service.py): `backend/app/services/graph_service.py`
- [Graph seeding](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/dev_service.py): `backend/app/services/dev_service.py`
- [Graph data schema](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/schemas/graph.py): `backend/app/schemas/graph.py`

### Simulation and intelligence

- [Simulation engine](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/simulation_service.py): `backend/app/services/simulation_service.py`
- [Causal risk analysis](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/ml_causal_service.py): `backend/app/services/ml_causal_service.py`
- [Inventory optimization](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/ml_optimization_service.py): `backend/app/services/ml_optimization_service.py`
- [Delay prediction](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/services/ml_routing_service.py): `backend/app/services/ml_routing_service.py`

### Persistence and jobs

- [Simulation worker](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/workers/simulation_worker.py): `backend/app/workers/simulation_worker.py`
- [Neo4j connection](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/db/neo4j.py): `backend/app/db/neo4j.py`
- **Supply network**
- [Redis connection](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/db/redis.py): `backend/app/db/redis.py`
- **Simulation state**
- [Celery task queue](https://github.com/shrankhalalala/digital_twin/blob/master/backend/app/celery_app.py): `backend/app/celery_app.py`

### Other components

- **Supply-chain operator**

## Connections

- Supply-chain operator → Dashboard page: uses (evidence: `README.md`)
- Dashboard page → Graph canvas: renders (evidence: `README.md`)
- Dashboard page → Geographic map: renders (evidence: `README.md`)
- Dashboard page → Simulation controls: renders (evidence: `README.md`)
- Dashboard page → Metrics panel: renders (evidence: `README.md`)
- Dashboard page → Routing controls: renders (evidence: `README.md`)
- Dashboard page → Explainability panel: renders (evidence: `README.md`)
- Graph canvas → Client state: shares state (evidence: `README.md`)
- Geographic map → Client state: shares state (evidence: `README.md`)
- Client state → FastAPI application: HTTP / WS (evidence: `README.md`)
- FastAPI application → Graph API: registers (evidence: `backend/app/main.py`)
- FastAPI application → Development API: registers (evidence: `backend/app/main.py`)
- FastAPI application → Routing API: registers (evidence: `backend/app/main.py`)
- FastAPI application → Simulation API: registers (evidence: `backend/app/main.py`)
- Graph API → Graph operations: delegates to (evidence: `backend/app/api/graph.py`)
- Graph operations → Neo4j connection: uses session (evidence: `backend/app/services/graph_service.py`)
- Neo4j connection → Supply network: reads / writes (evidence: `README.md`)
- Graph operations → Graph data schema: validates data (evidence: `backend/app/services/graph_service.py`)
- Development API → Graph seeding: delegates to (evidence: `backend/app/api/dev.py`)
- Graph seeding → Graph operations: imports subgraph (evidence: `backend/app/services/dev_service.py`)
- Graph seeding → Graph data schema: builds seed data (evidence: `backend/app/services/dev_service.py`)
- Routing API → Delay prediction: predicts delay (evidence: `backend/app/api/routing.py`)
- Simulation API → Simulation worker: dispatches task (evidence: `backend/app/api/simulation.py`)
- Simulation worker → Simulation engine: runs (evidence: `backend/app/workers/simulation_worker.py`)
- Simulation worker → Celery task queue: registered task (evidence: `backend/app/workers/simulation_worker.py`)
- Simulation engine → Causal risk analysis: predicts propagation (evidence: `backend/app/services/simulation_service.py`)
- Simulation engine → Inventory optimization: requests actions (evidence: `backend/app/services/simulation_service.py`)
- Simulation engine → Neo4j connection: loads network
- Simulation engine → Redis connection: writes updates (evidence: `backend/app/services/simulation_service.py`)
- Simulation worker → Redis connection: updates status (evidence: `backend/app/workers/simulation_worker.py`)
- Redis connection → Simulation state: reads / writes (evidence: `README.md`)
