# shemayon/phoenix-digital-twin architecture

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

- Interactive diagram: https://gitdiagram.com/shemayon/phoenix-digital-twin
- Repository: https://github.com/shemayon/phoenix-digital-twin

## Overview

1. **Overall shape**
   - This repo is a two-tier system: a **FastAPI backend** that owns twin state, simulation, anomaly detection, and chat; and a **Next.js frontend** that renders the operator command center.
   - The architecture is mostly **API-driven and stateless at the edge**. The backend is the source of truth for twin snapshots and command execution.

2. **Deployment boundary**
   - `docker-compose.yml` is the main orchestration point, bringing up the backend and frontend as separate services.
   - The backend is exposed on **port 8000** and the frontend on **port 3000**.
   - There is no evidence of a database or message broker in the tree; state appears to live in process or be derived from the simulator/IDSL model.

3. **Backend entry points**
   - The backend application lives under `backend/src/backend/app`.
   - `app/main.py` is the FastAPI application assembly point, while `src/backend/main.py` looks like the package-level runtime entry.
   - `app/api/deps.py` suggests dependency wiring for services/config, and `app/core/config.py` holds runtime configuration.

4. **Backend API surface**
   - The API is split into three route groups:
     - `api/routes/twin.py` for twin state and control commands
     - `api/routes/chat.py` for operator assistance
     - `api/routes/idsl.py` for loading or serving the IDSL twin specification
   - This separation is important: **twin control**, **assistant interaction**, and **model/spec loading** are distinct boundaries.

5. **Simulation and twin core**
   - `services/simulator.py` is the core runtime model for the digital twin. It likely advances state, applies corrections, and produces snapshot-like outputs.
   - `models/simulator.py` defines the state and DTOs used by that simulator.
   - The frontend’s control actions flow back into this simulator through the `/twin` routes, making the system **closed-loop** rather than read-only.

6. **Anomaly detection and analytics**
   - `services/anomaly_detector.py` is the analytics layer, corresponding to the README’s LSTM-based anomaly detection concept.
   - Its output likely augments twin snapshots with scores, alerts, or trend metrics rather than replacing the simulator.
   - This means the backend has two main compute responsibilities: **physical/twin state generation** and **health assessment**.

7. **IDSL modeling layer**
   - The `app/idsl` package contains `loader.py` and `repository.py`, indicating a dedicated subsystem for loading and resolving the industrial twin specification.
   - `models/idsl.py` likely defines the schema for that specification.
   - Architecturally, this is the **configuration/model boundary**: it defines what assets, tags, and relationships the simulator and UI should render.

8. **Chat and prescriptive assistance**
   - `services/chatbot.py` and `models/chat.py` support the conversational assistant exposed through `/chat`.
   - The README references Gemini; the code structure implies an external LLM-backed assistant that consumes twin context and returns guidance.
   - This is a separate backend capability, not embedded in the simulation loop, but it likely reads the same twin snapshot/state.

9. **Backend presentation layer**
   - `templates/dashboard.html` shows the backend also ships a server-rendered dashboard view, likely for a simple operational/demo entry point.
   - The presence of `tests/test_dashboard.py` indicates this HTML surface is still part of the supported architecture, even though the main UI is the Next.js app.

10. **Frontend structure**
   - The frontend is a Next.js App Router app (`app/layout.tsx`, `app/page.tsx`) with a componentized operator console.
   - Key visual subsystems are named explicitly:
     - `ThreeScene.tsx` for 3D spatial visualization
     - `TopologyView.tsx` for network/asset relationships
     - `TelemetryTable.tsx`, `TrendChart.tsx`, `KpiBar.tsx` for operational analytics
     - `AlertPanel.tsx`, `HistoryView.tsx` for incidents and timeline context
     - `ChatBot.tsx` for the assistant
     - `FaultInjector.tsx` for deliberate disturbance/command testing

11. **Frontend-backend data flow**
   - `frontend/lib/api.ts` is the primary integration layer, centralizing REST calls and typed contracts from the UI to the backend.
   - The UI appears to **poll or refresh twin snapshots** and then fan that data out into charts, tables, 3D rendering, and alerts.
   - User actions such as fault injection or correction commands flow in the opposite direction, from the UI back to the backend `/twin` routes.

12. **Contracts and models**
   - The backend `models/*` and frontend `lib/types.ts` likely define the shared shape of snapshots, telemetry, alerts, and chat responses.
   - This is a critical architecture boundary: the system depends on a stable API contract more than on shared runtime state.

13. **Testing and validation**
   - Backend tests cover the main subsystems: `test_simulator.py`, `test_ids_loader.py`, `test_chat_service.py`, and `test_dashboard.py`.
   - There are also small top-level scripts like `test_api_key.py` and `test_chatbot_demo.py`, which suggest the LLM/chat integration can be exercised independently.
   - This matches the repo’s modular structure: simulation, spec loading, chat, and UI are testable in isolation.

14. **What to draw in an architecture diagram**
   - The primary boxes should be:
     - **Frontend command center**
     - **FastAPI backend API**
     - **Simulator / twin core**
     - **Anomaly detection**
     - **IDSL spec loader/repository**
     - **Chatbot/LLM assistant**
   - The key arrows are:
     - frontend reads twin state from backend
     - frontend sends control commands to backend
     - backend simulator generates state and metrics
     - anomaly detection annotates that state
     - chatbot consumes twin context and returns guidance
     - IDSL supplies the structural model that both backend and UI rely on

Main entry points: [`backend/src/backend/app/main.py`](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/main.py) (Backend app), [`backend/src/backend/app/api/routes/twin.py`](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/routes/twin.py) (Twin API), [`frontend/lib/api.ts`](https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/lib/api.ts) (API client), [`backend/src/backend/app/idsl/repository.py`](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/idsl/repository.py) (IDSL repo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
end

subgraph group_backend["Backend"]
  node_backend_main["Backend app<br/>fastapi entry<br/>[main.py]"]
  node_runtime_main["Runtime entry<br/>package entry<br/>[main.py]"]
  node_config["Config<br/>[config.py]"]
  node_deps["Dependencies<br/>api wiring<br/>[deps.py]"]
  node_twin_api["Twin API<br/>route group<br/>[twin.py]"]
  node_chat_api["Chat API<br/>route group<br/>[chat.py]"]
  node_idsl_api["IDSL API<br/>route group<br/>[idsl.py]"]
  node_simulator(("Simulator<br/>twin core<br/>[simulator.py]"))
  node_anomaly(("Anomaly detector<br/>analytics"))
  node_chatbot(("Chatbot<br/>llm assistant<br/>[chatbot.py]"))
  node_idsl_loader["IDSL loader<br/>model loader<br/>[loader.py]"]
  node_idsl_repo[("IDSL repo<br/>spec repository<br/>[repository.py]")]
  node_dashboard["Dashboard<br/>server-rendered ui<br/>[dashboard.html]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Frontend app<br/>nextjs entry<br/>[page.tsx]"]
  node_api_client["API client<br/>frontend integration<br/>[api.ts]"]
  node_visuals["Visuals<br/>ui subsystem<br/>[ThreeScene.tsx]"]
  node_types["UI types<br/>contracts<br/>[types.ts]"]
end

node_compose -->|"runs"| node_backend_main
node_compose -->|"runs"| node_frontend_app
node_runtime_main -->|"boots"| node_backend_main
node_backend_main -->|"reads"| node_config
node_backend_main -->|"wires"| node_deps
node_backend_main -->|"mounts"| node_twin_api
node_backend_main -->|"mounts"| node_chat_api
node_backend_main -->|"mounts"| node_idsl_api
node_twin_api -->|"drives"| node_simulator
node_twin_api -->|"enriches"| node_anomaly
node_chat_api -->|"invokes"| node_chatbot
node_chatbot -.->|"reads context"| node_twin_api
node_idsl_api -->|"loads"| node_idsl_loader
node_idsl_loader -->|"stores"| node_idsl_repo
node_idsl_repo -.->|"describes"| node_simulator
node_idsl_repo -.->|"structures"| node_visuals
node_backend_main -->|"serves"| node_dashboard
node_frontend_app -->|"uses"| node_api_client
node_api_client -->|"types"| node_types
node_api_client -->|"reads/writes"| node_twin_api
node_api_client -->|"reads/writes"| node_chat_api
node_api_client -->|"reads"| node_idsl_api
node_frontend_app -->|"renders"| node_visuals
node_visuals -->|"consumes"| node_twin_api

click node_compose "https://github.com/shemayon/phoenix-digital-twin/blob/main/docker-compose.yml"
click node_backend_main "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/main.py"
click node_runtime_main "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/main.py"
click node_config "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/core/config.py"
click node_deps "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/deps.py"
click node_twin_api "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/routes/twin.py"
click node_chat_api "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/routes/chat.py"
click node_idsl_api "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/routes/idsl.py"
click node_simulator "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/services/simulator.py"
click node_anomaly "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/services/anomaly_detector.py"
click node_chatbot "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/services/chatbot.py"
click node_idsl_loader "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/idsl/loader.py"
click node_idsl_repo "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/idsl/repository.py"
click node_dashboard "https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/templates/dashboard.html"
click node_frontend_app "https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/app/page.tsx"
click node_api_client "https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/lib/api.ts"
click node_visuals "https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/components/ThreeScene.tsx"
click node_types "https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/lib/types.ts"

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_compose toneBlue
class node_backend_main,node_runtime_main,node_config,node_deps,node_twin_api,node_chat_api,node_idsl_api,node_simulator,node_anomaly,node_chatbot,node_idsl_loader,node_idsl_repo,node_dashboard toneAmber
class node_frontend_app,node_api_client,node_visuals,node_types toneMint
```

## Components

### Repository

Top-level deployment and runtime boundary

- [Compose](https://github.com/shemayon/phoenix-digital-twin/blob/main/docker-compose.yml): orchestration · Starts backend and frontend services · `docker-compose.yml`

### Backend

FastAPI twin services and API surface

- [Backend app](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/main.py): fastapi entry · FastAPI application assembly point · `backend/src/backend/app/main.py`
- [Runtime entry](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/main.py): package entry · Package-level backend launcher · `backend/src/backend/main.py`
- [Config](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/core/config.py): runtime config · Backend settings and environment wiring · `backend/src/backend/app/core/config.py`
- [Dependencies](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/deps.py): api wiring · Service and config dependency injection · `backend/src/backend/app/api/deps.py`
- [Twin API](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/routes/twin.py): route group · Twin state, control commands, and snapshots · `backend/src/backend/app/api/routes/twin.py`
- [Chat API](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/routes/chat.py): route group · Operator assistant interaction endpoints · `backend/src/backend/app/api/routes/chat.py`
- [IDSL API](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/api/routes/idsl.py): route group · Loads and serves the twin specification · `backend/src/backend/app/api/routes/idsl.py`
- [Simulator](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/services/simulator.py): twin core · Advances twin state and applies commands · `backend/src/backend/app/services/simulator.py`
- [Anomaly detector](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/services/anomaly_detector.py): analytics · Scores twin health and alerts · `backend/src/backend/app/services/anomaly_detector.py`
- [Chatbot](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/services/chatbot.py): llm assistant · Generates prescriptive guidance from twin context · `backend/src/backend/app/services/chatbot.py`
- [IDSL loader](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/idsl/loader.py): model loader · Resolves the industrial twin specification · `backend/src/backend/app/idsl/loader.py`
- [IDSL repo](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/app/idsl/repository.py): spec repository · Stores and serves loaded IDSL definitions · `backend/src/backend/app/idsl/repository.py`
- [Dashboard](https://github.com/shemayon/phoenix-digital-twin/blob/main/backend/src/backend/templates/dashboard.html): server-rendered ui · Backend HTML dashboard surface · `backend/src/backend/templates/dashboard.html`

### Frontend

Next.js operator command center

- [Frontend app](https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/app/page.tsx): nextjs entry · App Router shell for the operator console · `frontend/app/page.tsx`
- [API client](https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/lib/api.ts): frontend integration · Central REST client and typed contracts · `frontend/lib/api.ts`
- [Visuals](https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/components/ThreeScene.tsx): ui subsystem · 3D scene, topology, telemetry, trends, KPIs, alerts, history, chat, and fault injection · `frontend/components/ThreeScene.tsx`
- [UI types](https://github.com/shemayon/phoenix-digital-twin/blob/main/frontend/lib/types.ts): contracts · Frontend data shapes for snapshots and responses · `frontend/lib/types.ts`

## Connections

- Compose → Backend app: runs · Compose starts the FastAPI backend
- Compose → Frontend app: runs · Compose starts the Next.js frontend
- Runtime entry → Backend app: boots · Package entry invokes the app assembly
- Backend app → Config: reads · App startup consumes runtime configuration
- Backend app → Dependencies: wires · App startup wires service dependencies
- Backend app → Twin API: mounts · Registers twin routes
- Backend app → Chat API: mounts · Registers chat routes
- Backend app → IDSL API: mounts · Registers IDSL routes
- Twin API → Simulator: drives · Control commands and reads flow through the simulator
- Twin API → Anomaly detector: enriches · Twin responses include health scoring and alerts
- Chat API → Chatbot: invokes · Chat endpoints call the assistant service
- Chatbot → Twin API: reads context · Assistant guidance uses twin state and signals
- IDSL API → IDSL loader: loads · API resolves model/spec definitions
- IDSL loader → IDSL repo: stores · Loaded specs are kept in the repository layer
- IDSL repo → Simulator: describes · Specification shapes simulated assets and relationships
- IDSL repo → Visuals: structures · Frontend topology and asset views follow the spec
- Backend app → Dashboard: serves · Backend also renders a dashboard page
- Frontend app → API client: uses · UI talks to backend through the API client
- API client → UI types: types · Client is backed by shared frontend contracts
- API client → Twin API: reads/writes · Frontend polls state and sends control commands
- API client → Chat API: reads/writes · Chat UI exchanges messages with the assistant API
- API client → IDSL API: reads · UI fetches model/spec data when needed
- Frontend app → Visuals: renders · Command center composes visualization and operator panels
- Visuals → Twin API: consumes · Charts, tables, and 3D views render twin snapshots
