How shemayon/phoenix-digital-twin works
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: main.py Backend app · twin.py Twin API · api.ts API client · repository.py IDSL repo
Components 18
Repository
Top-level deployment and runtime boundary
- Compose · Starts backend and frontend services
docker-compose.yml
Backend
FastAPI twin services and API surface
- Backend app · FastAPI application assembly point
backend/src/backend/app/main.py - Runtime entry · Package-level backend launcher
backend/src/backend/main.py - Config · Backend settings and environment wiring
backend/src/backend/app/core/config.py - Dependencies · Service and config dependency injection
backend/src/backend/app/api/deps.py - Twin API · Twin state, control commands, and snapshots
backend/src/backend/app/api/routes/twin.py - Chat API · Operator assistant interaction endpoints
backend/src/backend/app/api/routes/chat.py - IDSL API · Loads and serves the twin specification
backend/src/backend/app/api/routes/idsl.py - Simulator · Advances twin state and applies commands
backend/src/backend/app/services/simulator.py - Anomaly detector · Scores twin health and alerts
backend/src/backend/app/services/anomaly_detector.py - Chatbot · Generates prescriptive guidance from twin context
backend/src/backend/app/services/chatbot.py - IDSL loader · Resolves the industrial twin specification
backend/src/backend/app/idsl/loader.py - IDSL repo · Stores and serves loaded IDSL definitions
backend/src/backend/app/idsl/repository.py - Dashboard · Backend HTML dashboard surface
backend/src/backend/templates/dashboard.html
Frontend
Next.js operator command center
- Frontend app · App Router shell for the operator console
frontend/app/page.tsx - API client · Central REST client and typed contracts
frontend/lib/api.ts - Visuals · 3D scene, topology, telemetry, trends, KPIs, alerts, history, chat, and fault injection
frontend/components/ThreeScene.tsx - UI types · Frontend data shapes for snapshots and responses
frontend/lib/types.ts
Connections 24
- 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