# ahmed-metawea/utilityguard architecture

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

- Interactive diagram: https://gitdiagram.com/ahmed-metawea/utilityguard
- Repository: https://github.com/ahmed-metawea/utilityguard

## Overview

Care Grid is a simulated, multi-utility digital twin with a web dashboard. Its main workflow advances the water, electricity and cooling simulation, detects incidents, generates evidence-backed agent findings, and convenes a crew-priority board; a person approves or rejects the plan before dispatch changes the simulated network. The product also exposes forecasting, early warnings, cost and decision analysis, siting, savings, reporting and an AI lab. The graph follows documented capabilities and visible source references; several feature implementations were not sampled, so their internal links are omitted or documented at the product level.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/App.tsx) (Dashboard Application), [`backend/app/agents/service.py`](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/service.py) (Agent Service), [`backend/app/runtime.py`](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/runtime.py) (Live Runtime), [`backend/app/agents/specialists.py`](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/specialists.py) (Network Specialists)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_twin["Twin and Detection"]
  node_topology["Utility Topology<br/>[topology.py]"]
  node_engine["Twin Engine<br/>[engine.py]"]
  node_runtime["Live Runtime<br/>[runtime.py]"]
  node_detection["Incident Detection<br/>[__init__.py]"]
end

subgraph group_agents["Agents and Board"]
  node_agentservice["Agent Service<br/>[service.py]"]
  node_orchestrator["Agent Orchestrator<br/>[orchestrator.py]"]
  node_specialists["Network Specialists<br/>[specialists.py]"]
  node_llm["LLM Gateway<br/>[llm.py]"]
  node_boardanalysis["Board Analysis<br/>[analysis.py]"]
  node_boardsession["Board Meeting<br/>[session.py]"]
  node_dispatch["Approval and Dispatch<br/>[dispatch.py]"]
end

subgraph group_analysis["Analysis and Planning"]
  node_ml["Forecasts and Warnings<br/>[service.py]"]
  node_cost["Cost and Evidence<br/>[__init__.py]"]
  node_decision["Decision Studio<br/>[decision.py]"]
  node_siting["Siting Evaluation<br/>[siting.py]"]
end

subgraph group_backend["Backend Services"]
  node_extras["Briefing and Savings<br/>[briefing.py]"]
  node_api["HTTP and WebSocket API<br/>[main.py]"]
end

subgraph group_frontend["Web Application"]
  node_app["Dashboard Application<br/>[App.tsx]"]
  node_stream["Live Stream Client<br/>[ws.ts]"]
  node_map["Live Twin Map<br/>[CityMap.tsx]"]
  node_forecastpage["Forecast View<br/>[Forecast.tsx]"]
  node_boardui["Board Interface<br/>[Board.tsx]"]
  node_lab["AI Lab<br/>[Lab.tsx]"]
end

node_operator(("Operator"))

node_operator -->|"uses dashboard"| node_app
node_topology -->|"configures network"| node_engine
node_engine -->|"advances ticks"| node_runtime
node_runtime -->|"runs tick hooks"| node_detection
node_runtime -.->|"feeds live data"| node_ml
node_detection -->|"notifies incidents"| node_agentservice
node_agentservice -->|"runs analysis"| node_specialists
node_agentservice -->|"routes chat"| node_orchestrator
node_orchestrator -->|"consults agents"| node_specialists
node_specialists -->|"requests wording"| node_llm
node_specialists -->|"computes figures"| node_cost
node_agentservice -->|"convenes board"| node_boardsession
node_boardsession -->|"uses calculated facts"| node_boardanalysis
node_boardanalysis -->|"prices alternatives"| node_cost
node_operator -->|"approves or rejects"| node_dispatch
node_dispatch -->|"applies crew repair"| node_engine
node_operator -->|"compares action options"| node_decision
node_operator -->|"evaluates proposed load"| node_siting
node_operator -->|"reviews daily insights"| node_extras
node_app -->|"loads product data"| node_api
node_app -->|"starts live stream"| node_stream
node_stream -.->|"receives twin updates"| node_api
node_app -->|"shows live twin"| node_map
node_app -->|"opens forecasts"| node_forecastpage
node_app -->|"shows board decisions"| node_boardui
node_app -->|"opens AI lab"| node_lab
node_api -->|"streams twin state"| node_runtime

click node_topology "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/sim/topology.py"
click node_engine "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/sim/engine.py"
click node_runtime "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/runtime.py"
click node_detection "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/detection/__init__.py"
click node_ml "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/ml/service.py"
click node_agentservice "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/service.py"
click node_orchestrator "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/orchestrator.py"
click node_specialists "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/specialists.py"
click node_llm "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/llm.py"
click node_cost "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/cost/__init__.py"
click node_boardanalysis "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/board/analysis.py"
click node_boardsession "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/board/session.py"
click node_dispatch "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/board/dispatch.py"
click node_decision "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/decision.py"
click node_siting "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/siting.py"
click node_extras "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/briefing.py"
click node_api "https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/main.py"
click node_app "https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/App.tsx"
click node_stream "https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/api/ws.ts"
click node_map "https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/map/CityMap.tsx"
click node_forecastpage "https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/pages/Forecast.tsx"
click node_boardui "https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/ui/Board.tsx"
click node_lab "https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/pages/Lab.tsx"

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_topology,node_engine,node_runtime,node_detection toneBlue
class node_agentservice,node_orchestrator,node_specialists,node_llm,node_boardanalysis,node_boardsession,node_dispatch toneAmber
class node_ml,node_cost,node_decision,node_siting toneMint
class node_extras,node_api toneRose
class node_app,node_stream,node_map,node_forecastpage,node_boardui,node_lab,node_operator toneIndigo
```

## Components

### Twin and Detection

- [Utility Topology](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/sim/topology.py): `backend/app/sim/topology.py`
- [Twin Engine](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/sim/engine.py): `backend/app/sim/engine.py`
- [Live Runtime](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/runtime.py): `backend/app/runtime.py`
- [Incident Detection](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/detection/__init__.py): `backend/app/detection/__init__.py`

### Agents and Board

- [Agent Service](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/service.py): `backend/app/agents/service.py`
- [Agent Orchestrator](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Network Specialists](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/specialists.py): `backend/app/agents/specialists.py`
- [LLM Gateway](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/agents/llm.py): `backend/app/agents/llm.py`
- [Board Analysis](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/board/analysis.py): `backend/app/board/analysis.py`
- [Board Meeting](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/board/session.py): `backend/app/board/session.py`
- [Approval and Dispatch](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/board/dispatch.py): `backend/app/board/dispatch.py`

### Analysis and Planning

- [Forecasts and Warnings](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/ml/service.py): `backend/app/ml/service.py`
- [Cost and Evidence](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/cost/__init__.py): `backend/app/cost/__init__.py`
- [Decision Studio](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/decision.py): `backend/app/decision.py`
- [Siting Evaluation](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/siting.py): `backend/app/siting.py`

### Backend Services

- [Briefing and Savings](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/briefing.py): `backend/app/briefing.py`
- [HTTP and WebSocket API](https://github.com/ahmed-metawea/utilityguard/blob/main/backend/app/main.py): `backend/app/main.py`

### Web Application

- [Dashboard Application](https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Live Stream Client](https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/api/ws.ts): `frontend/src/api/ws.ts`
- [Live Twin Map](https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/map/CityMap.tsx): `frontend/src/map/CityMap.tsx`
- [Forecast View](https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/pages/Forecast.tsx): `frontend/src/pages/Forecast.tsx`
- [Board Interface](https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/ui/Board.tsx): `frontend/src/ui/Board.tsx`
- [AI Lab](https://github.com/ahmed-metawea/utilityguard/blob/main/frontend/src/pages/Lab.tsx): `frontend/src/pages/Lab.tsx`

### Other components

- **Operator**

## Connections

- Operator → Dashboard Application: uses dashboard (evidence: `README.md`)
- Utility Topology → Twin Engine: configures network (evidence: `backend/app/sim/engine.py`)
- Twin Engine → Live Runtime: advances ticks (evidence: `backend/app/runtime.py`)
- Live Runtime → Incident Detection: runs tick hooks (evidence: `backend/app/agents/service.py`)
- Live Runtime → Forecasts and Warnings: feeds live data (evidence: `backend/app/ml/service.py`)
- Incident Detection → Agent Service: notifies incidents (evidence: `backend/app/agents/service.py`)
- Agent Service → Network Specialists: runs analysis (evidence: `backend/app/agents/service.py`)
- Agent Service → Agent Orchestrator: routes chat (evidence: `backend/app/agents/service.py`)
- Agent Orchestrator → Network Specialists: consults agents (evidence: `backend/app/agents/orchestrator.py`)
- Network Specialists → LLM Gateway: requests wording (evidence: `backend/app/agents/specialists.py`)
- Network Specialists → Cost and Evidence: computes figures (evidence: `backend/app/agents/specialists.py`)
- Agent Service → Board Meeting: convenes board (evidence: `backend/app/agents/service.py`)
- Board Meeting → Board Analysis: uses calculated facts (evidence: `backend/app/board/session.py`)
- Board Analysis → Cost and Evidence: prices alternatives (evidence: `backend/app/board/analysis.py`)
- Operator → Approval and Dispatch: approves or rejects (evidence: `README.md`)
- Approval and Dispatch → Twin Engine: applies crew repair (evidence: `backend/app/board/dispatch.py`)
- Operator → Decision Studio: compares action options (evidence: `README.md`)
- Operator → Siting Evaluation: evaluates proposed load (evidence: `README.md`)
- Operator → Briefing and Savings: reviews daily insights (evidence: `README.md`)
- Dashboard Application → HTTP and WebSocket API: loads product data (evidence: `frontend/src/App.tsx`)
- Dashboard Application → Live Stream Client: starts live stream (evidence: `frontend/src/App.tsx`)
- Live Stream Client → HTTP and WebSocket API: receives twin updates
- Dashboard Application → Live Twin Map: shows live twin (evidence: `README.md`)
- Dashboard Application → Forecast View: opens forecasts (evidence: `frontend/src/App.tsx`)
- Dashboard Application → Board Interface: shows board decisions (evidence: `README.md`)
- Dashboard Application → AI Lab: opens AI lab (evidence: `frontend/src/App.tsx`)
- HTTP and WebSocket API → Live Runtime: streams twin state (evidence: `README.md`)
