# thedeductor/jarvis architecture

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

- Interactive diagram: https://gitdiagram.com/thedeductor/jarvis
- Repository: https://github.com/thedeductor/jarvis

## Overview

JARVIS is an HVAC digital-twin simulator and control dashboard. Occupants and facility managers use the frontend to inspect live building state, adjust simulation and environment controls, or submit comfort complaints. The API routes these operations through the simulation manager, which applies constraint and tariff overlays and advances the twin; physics models calculate thermal, IAQ, energy, and comfort outcomes. An optional PPO policy supplies autonomous control, while weather and NLP use external services. The frontend and API excerpts are partial, so uncertain endpoint-to-panel wiring is not expanded.

Main entry points: [`backend/digital_twin.py`](https://github.com/thedeductor/jarvis/blob/main/backend/digital_twin.py) (Building twin), [`backend/simulation_manager.py`](https://github.com/thedeductor/jarvis/blob/main/backend/simulation_manager.py) (Simulation manager), [`backend/main.py`](https://github.com/thedeductor/jarvis/blob/main/backend/main.py) (HTTP API), [`frontend/src/App.tsx`](https://github.com/thedeductor/jarvis/blob/main/frontend/src/App.tsx) (Dashboard app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_app["Dashboard app<br/>[App.tsx]"]
  node_ui_components["Controls and views"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and orchestration"]
  node_api_routes["HTTP API<br/>[main.py]"]
  node_manager["Simulation manager"]
  node_constraints["Constraint lifecycle"]
  node_tariff["Tariff response"]
  node_auth["Authentication<br/>[auth.py]"]
  node_database["Database access<br/>[database.py]"]
end

subgraph group_twin["Digital twin"]
  node_twin["Building twin<br/>[digital_twin.py]"]
  node_thermal["Thermal model<br/>[thermal_model.py]"]
  node_iaq["IAQ model<br/>[digital_twin.py]"]
  node_energy["Energy model<br/>[energy_model.py]"]
  node_comfort["Comfort model<br/>[comfort_model.py]"]
  node_baseline["Baseline twin<br/>[baseline.py]"]
end

subgraph group_integrations["AI and services"]
  node_rl_agent["PPO controller<br/>[agent.py]"]
  node_rl_environment["RL environment<br/>[building_env.py]"]
  node_nlp["Complaint parser<br/>[nlp_engine.py]"]
  node_weather_service["Weather service<br/>[weather_service.py]"]
end

node_occupants(("Occupants / managers"))
node_groq{{"Groq LLM"}}
node_open_meteo{{"Open-Meteo"}}
node_db[("Application database")]

node_occupants -->|"use"| node_app
node_app -->|"renders"| node_ui_components
node_app -->|"requests"| node_api_client
node_api_client -->|"REST calls"| node_api_routes
node_api_routes -->|"controls and queries"| node_manager
node_manager -->|"advances and controls"| node_twin
node_manager -->|"manages"| node_constraints
node_manager -->|"applies"| node_tariff
node_twin -->|"calculates"| node_thermal
node_twin -->|"calculates"| node_iaq
node_twin -->|"calculates"| node_energy
node_twin -->|"calculates"| node_comfort
node_twin -->|"compares"| node_baseline
node_manager -.->|"executes policy"| node_rl_agent
node_rl_environment -->|"simulates with"| node_twin
node_manager -->|"parses complaints"| node_nlp
node_nlp -.->|"prompts"| node_groq
node_api_routes -->|"requests weather"| node_weather_service
node_weather_service -->|"fetches conditions"| node_open_meteo
node_api_routes -->|"authenticates"| node_auth
node_auth -->|"queries users"| node_database
node_api_routes -->|"persists events"| node_database
node_database -->|"reads and writes"| node_db

click node_app "https://github.com/thedeductor/jarvis/blob/main/frontend/src/App.tsx"
click node_ui_components "https://github.com/thedeductor/jarvis/tree/main/frontend/src/components"
click node_api_client "https://github.com/thedeductor/jarvis/blob/main/frontend/src/api.ts"
click node_api_routes "https://github.com/thedeductor/jarvis/blob/main/backend/main.py"
click node_manager "https://github.com/thedeductor/jarvis/blob/main/backend/simulation_manager.py"
click node_constraints "https://github.com/thedeductor/jarvis/blob/main/backend/simulation_manager.py"
click node_tariff "https://github.com/thedeductor/jarvis/blob/main/backend/simulation_manager.py"
click node_twin "https://github.com/thedeductor/jarvis/blob/main/backend/digital_twin.py"
click node_thermal "https://github.com/thedeductor/jarvis/blob/main/backend/thermal_model.py"
click node_iaq "https://github.com/thedeductor/jarvis/blob/main/backend/digital_twin.py"
click node_energy "https://github.com/thedeductor/jarvis/blob/main/backend/energy_model.py"
click node_comfort "https://github.com/thedeductor/jarvis/blob/main/backend/comfort_model.py"
click node_baseline "https://github.com/thedeductor/jarvis/blob/main/backend/baseline.py"
click node_rl_agent "https://github.com/thedeductor/jarvis/blob/main/rl/agent.py"
click node_rl_environment "https://github.com/thedeductor/jarvis/blob/main/rl/env/building_env.py"
click node_nlp "https://github.com/thedeductor/jarvis/blob/main/backend/nlp_engine.py"
click node_weather_service "https://github.com/thedeductor/jarvis/blob/main/backend/weather_service.py"
click node_auth "https://github.com/thedeductor/jarvis/blob/main/backend/auth.py"
click node_database "https://github.com/thedeductor/jarvis/blob/main/backend/database.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_app,node_ui_components,node_api_client toneBlue
class node_api_routes,node_manager,node_constraints,node_tariff,node_auth,node_database,node_db toneAmber
class node_twin,node_thermal,node_iaq,node_energy,node_comfort,node_baseline toneMint
class node_rl_agent,node_rl_environment,node_nlp,node_weather_service toneRose
class node_occupants,node_groq,node_open_meteo toneIndigo
```

## Components

### Dashboard

- [Dashboard app](https://github.com/thedeductor/jarvis/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Controls and views](https://github.com/thedeductor/jarvis/tree/main/frontend/src/components): `frontend/src/components`
- [API client](https://github.com/thedeductor/jarvis/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and orchestration

- [HTTP API](https://github.com/thedeductor/jarvis/blob/main/backend/main.py): `backend/main.py`
- [Simulation manager](https://github.com/thedeductor/jarvis/blob/main/backend/simulation_manager.py): `backend/simulation_manager.py`
- [Constraint lifecycle](https://github.com/thedeductor/jarvis/blob/main/backend/simulation_manager.py): `backend/simulation_manager.py`
- [Tariff response](https://github.com/thedeductor/jarvis/blob/main/backend/simulation_manager.py): `backend/simulation_manager.py`
- [Authentication](https://github.com/thedeductor/jarvis/blob/main/backend/auth.py): `backend/auth.py`
- [Database access](https://github.com/thedeductor/jarvis/blob/main/backend/database.py): `backend/database.py`

### Digital twin

- [Building twin](https://github.com/thedeductor/jarvis/blob/main/backend/digital_twin.py): `backend/digital_twin.py`
- [Thermal model](https://github.com/thedeductor/jarvis/blob/main/backend/thermal_model.py): `backend/thermal_model.py`
- [IAQ model](https://github.com/thedeductor/jarvis/blob/main/backend/digital_twin.py): `backend/digital_twin.py`
- [Energy model](https://github.com/thedeductor/jarvis/blob/main/backend/energy_model.py): `backend/energy_model.py`
- [Comfort model](https://github.com/thedeductor/jarvis/blob/main/backend/comfort_model.py): `backend/comfort_model.py`
- [Baseline twin](https://github.com/thedeductor/jarvis/blob/main/backend/baseline.py): `backend/baseline.py`

### AI and services

- [PPO controller](https://github.com/thedeductor/jarvis/blob/main/rl/agent.py): `rl/agent.py`
- [RL environment](https://github.com/thedeductor/jarvis/blob/main/rl/env/building_env.py): `rl/env/building_env.py`
- [Complaint parser](https://github.com/thedeductor/jarvis/blob/main/backend/nlp_engine.py): `backend/nlp_engine.py`
- [Weather service](https://github.com/thedeductor/jarvis/blob/main/backend/weather_service.py): `backend/weather_service.py`

### Other components

- **Occupants / managers**
- **Groq LLM**
- **Open-Meteo**
- **Application database**

## Connections

- Occupants / managers → Dashboard app: use
- Dashboard app → Controls and views: renders
- Dashboard app → API client: requests
- API client → HTTP API: REST calls
- HTTP API → Simulation manager: controls and queries
- Simulation manager → Building twin: advances and controls
- Simulation manager → Constraint lifecycle: manages
- Simulation manager → Tariff response: applies
- Building twin → Thermal model: calculates
- Building twin → IAQ model: calculates
- Building twin → Energy model: calculates
- Building twin → Comfort model: calculates
- Building twin → Baseline twin: compares
- Simulation manager → PPO controller: executes policy
- RL environment → Building twin: simulates with
- Simulation manager → Complaint parser: parses complaints
- Complaint parser → Groq LLM: prompts
- HTTP API → Weather service: requests weather
- Weather service → Open-Meteo: fetches conditions
- HTTP API → Authentication: authenticates
- Authentication → Database access: queries users
- HTTP API → Database access: persists events
- Database access → Application database: reads and writes