# ay178/digital-twin- architecture

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

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

## Overview

This is a spacecraft digital-twin mission dashboard. Operators choose mission parameters and optional faults, request a simulated telemetry run, then inspect health, remaining useful life, anomaly evidence, physics residuals, and recommended actions while scrubbing through cycles. The backend orchestrates telemetry replay, fault injection, model predictions, thermal comparison, and explanations; the frontend presents results and supports what-if mitigation and fleet views. The README is empty, so capability evidence comes from the sampled source; frontend-to-backend HTTP wiring and the role of the legacy model utility are not verified.

Main entry points: [`frontend/src/App.jsx`](https://github.com/ay178/digital-twin-/blob/main/frontend/src/App.jsx) (Mission dashboard), [`backend/app/main.py`](https://github.com/ay178/digital-twin-/blob/main/backend/app/main.py) (Twin API), [`backend/app/spacecraft_channels.py`](https://github.com/ay178/digital-twin-/blob/main/backend/app/spacecraft_channels.py) (Telemetry channel catalog), [`backend/app/model_utils_v2.py`](https://github.com/ay178/digital-twin-/blob/main/backend/app/model_utils_v2.py) (Telemetry model pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Mission Dashboard"]
  node_dashboard["Mission dashboard<br/>[App.jsx]"]
  node_sim_client["Simulation client<br/>[api.js]"]
  node_fault_client["Fault client<br/>[faultApi.js]"]
  node_spacecraft_view["Spacecraft view"]
  node_warroom["Mission backdrop"]
  node_recommendations["Recommendation panel"]
  node_agent["Offline mission agent<br/>[AgentChat.jsx]"]
  node_physics_chart["Physics chart<br/>[PhysicsChart.jsx]"]
end

subgraph group_api["API Orchestration"]
  node_api_service["Twin API<br/>[main.py]"]
end

subgraph group_analysis["Twin Analysis"]
  node_model_v2["Telemetry model pipeline<br/>[model_utils_v2.py]"]
  node_legacy_models["Legacy model utilities<br/>[model_utils.py]"]
  node_fault_injector["Fault injection<br/>[faults.py]"]
  node_thermal_twin["Thermal physics twin<br/>[physics_twin.py]"]
  node_explanations["Diagnosis builder<br/>[explain.py]"]
end

subgraph group_domain["Spacecraft Domain"]
  node_channel_catalog["Telemetry channel catalog"]
end

node_operator(("Mission operator"))

node_operator -->|"sets mission"| node_dashboard
node_dashboard -->|"requests runs"| node_sim_client
node_dashboard -->|"loads faults"| node_fault_client
node_dashboard -->|"renders status"| node_spacecraft_view
node_dashboard -->|"renders backdrop"| node_warroom
node_dashboard -->|"renders diagnoses"| node_recommendations
node_dashboard -->|"supplies twin state"| node_agent
node_dashboard -->|"renders analysis"| node_physics_chart
node_sim_client -.->|"requests simulation"| node_api_service
node_fault_client -.->|"requests fault list"| node_api_service
node_api_service -->|"loads and predicts"| node_model_v2
node_api_service -->|"injects selected fault"| node_fault_injector
node_api_service -->|"computes residuals"| node_thermal_twin
node_api_service -->|"builds diagnoses"| node_explanations
node_api_service -->|"labels telemetry"| node_channel_catalog
node_model_v2 -->|"uses fault definitions"| node_fault_injector
node_model_v2 -->|"uses channel order"| node_channel_catalog
node_fault_injector -->|"maps fault channels"| node_channel_catalog
node_explanations -->|"maps error channels"| node_channel_catalog
node_thermal_twin -.->|"provides residual data"| node_physics_chart

click node_dashboard "https://github.com/ay178/digital-twin-/blob/main/frontend/src/App.jsx"
click node_sim_client "https://github.com/ay178/digital-twin-/blob/main/frontend/src/api.js"
click node_fault_client "https://github.com/ay178/digital-twin-/blob/main/frontend/src/faultApi.js"
click node_spacecraft_view "https://github.com/ay178/digital-twin-/blob/main/frontend/src/SpacecraftVisual3D.jsx"
click node_warroom "https://github.com/ay178/digital-twin-/blob/main/frontend/src/WarRoomBackground.jsx"
click node_recommendations "https://github.com/ay178/digital-twin-/blob/main/frontend/src/components/RecommendationPanel.jsx"
click node_agent "https://github.com/ay178/digital-twin-/blob/main/frontend/src/components/AgentChat.jsx"
click node_physics_chart "https://github.com/ay178/digital-twin-/blob/main/frontend/src/components/PhysicsChart.jsx"
click node_api_service "https://github.com/ay178/digital-twin-/blob/main/backend/app/main.py"
click node_model_v2 "https://github.com/ay178/digital-twin-/blob/main/backend/app/model_utils_v2.py"
click node_legacy_models "https://github.com/ay178/digital-twin-/blob/main/backend/app/model_utils.py"
click node_fault_injector "https://github.com/ay178/digital-twin-/blob/main/backend/app/faults.py"
click node_thermal_twin "https://github.com/ay178/digital-twin-/blob/main/backend/app/physics_twin.py"
click node_explanations "https://github.com/ay178/digital-twin-/blob/main/backend/app/explain.py"
click node_channel_catalog "https://github.com/ay178/digital-twin-/blob/main/backend/app/spacecraft_channels.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_sim_client,node_fault_client,node_spacecraft_view,node_warroom,node_recommendations,node_agent,node_physics_chart toneBlue
class node_api_service toneAmber
class node_model_v2,node_legacy_models,node_fault_injector,node_thermal_twin,node_explanations toneMint
class node_channel_catalog toneRose
class node_operator toneIndigo
```

## Components

### Mission Dashboard

- [Mission dashboard](https://github.com/ay178/digital-twin-/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Simulation client](https://github.com/ay178/digital-twin-/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Fault client](https://github.com/ay178/digital-twin-/blob/main/frontend/src/faultApi.js): `frontend/src/faultApi.js`
- [Spacecraft view](https://github.com/ay178/digital-twin-/blob/main/frontend/src/SpacecraftVisual3D.jsx): `frontend/src/SpacecraftVisual3D.jsx`
- [Mission backdrop](https://github.com/ay178/digital-twin-/blob/main/frontend/src/WarRoomBackground.jsx): `frontend/src/WarRoomBackground.jsx`
- [Recommendation panel](https://github.com/ay178/digital-twin-/blob/main/frontend/src/components/RecommendationPanel.jsx): `frontend/src/components/RecommendationPanel.jsx`
- [Offline mission agent](https://github.com/ay178/digital-twin-/blob/main/frontend/src/components/AgentChat.jsx): `frontend/src/components/AgentChat.jsx`
- [Physics chart](https://github.com/ay178/digital-twin-/blob/main/frontend/src/components/PhysicsChart.jsx): `frontend/src/components/PhysicsChart.jsx`

### API Orchestration

- [Twin API](https://github.com/ay178/digital-twin-/blob/main/backend/app/main.py): `backend/app/main.py`

### Twin Analysis

- [Telemetry model pipeline](https://github.com/ay178/digital-twin-/blob/main/backend/app/model_utils_v2.py): `backend/app/model_utils_v2.py`
- [Legacy model utilities](https://github.com/ay178/digital-twin-/blob/main/backend/app/model_utils.py): `backend/app/model_utils.py`
- [Fault injection](https://github.com/ay178/digital-twin-/blob/main/backend/app/faults.py): `backend/app/faults.py`
- [Thermal physics twin](https://github.com/ay178/digital-twin-/blob/main/backend/app/physics_twin.py): `backend/app/physics_twin.py`
- [Diagnosis builder](https://github.com/ay178/digital-twin-/blob/main/backend/app/explain.py): `backend/app/explain.py`

### Spacecraft Domain

- [Telemetry channel catalog](https://github.com/ay178/digital-twin-/blob/main/backend/app/spacecraft_channels.py): `backend/app/spacecraft_channels.py`

### Other components

- **Mission operator**

## Connections

- Mission operator → Mission dashboard: sets mission (evidence: `frontend/src/App.jsx`)
- Mission dashboard → Simulation client: requests runs (evidence: `frontend/src/App.jsx`)
- Mission dashboard → Fault client: loads faults (evidence: `frontend/src/App.jsx`)
- Mission dashboard → Spacecraft view: renders status (evidence: `frontend/src/App.jsx`)
- Mission dashboard → Mission backdrop: renders backdrop (evidence: `frontend/src/App.jsx`)
- Mission dashboard → Recommendation panel: renders diagnoses (evidence: `frontend/src/App.jsx`)
- Mission dashboard → Offline mission agent: supplies twin state (evidence: `frontend/src/App.jsx`)
- Mission dashboard → Physics chart: renders analysis (evidence: `frontend/src/App.jsx`)
- Simulation client → Twin API: requests simulation
- Fault client → Twin API: requests fault list
- Twin API → Telemetry model pipeline: loads and predicts (evidence: `backend/app/main.py`)
- Twin API → Fault injection: injects selected fault (evidence: `backend/app/main.py`)
- Twin API → Thermal physics twin: computes residuals (evidence: `backend/app/main.py`)
- Twin API → Diagnosis builder: builds diagnoses (evidence: `backend/app/main.py`)
- Twin API → Telemetry channel catalog: labels telemetry (evidence: `backend/app/main.py`)
- Telemetry model pipeline → Fault injection: uses fault definitions (evidence: `backend/app/model_utils_v2.py`)
- Telemetry model pipeline → Telemetry channel catalog: uses channel order (evidence: `backend/app/model_utils_v2.py`)
- Fault injection → Telemetry channel catalog: maps fault channels (evidence: `backend/app/faults.py`)
- Diagnosis builder → Telemetry channel catalog: maps error channels (evidence: `backend/app/explain.py`)
- Thermal physics twin → Physics chart: provides residual data
