# doctype02/plugin-ems architecture

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

- Interactive diagram: https://gitdiagram.com/doctype02/plugin-ems
- Repository: https://github.com/doctype02/plugin-ems

## Overview

This repository combines a Python building-energy digital twin and analysis workflow, a Node-RED live-control path, and a Grafana panel for monitoring, control, and interactive simulation. The main offline path runs climate and occupancy inputs through the simulator, building model, and controller, then supports scenario comparison, forecasting, validation, and KPIs. The live path connects the EMS to MQTT/InfluxDB and Node-RED. The README documents capabilities whose source was not sampled; their links are omitted or marked unverified where needed.

Main entry points: [`ems/simulacion.py`](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/simulacion.py) (Twin simulation), [`ems/cli.py`](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/cli.py) (CLI workflow), [`grafana-ems-panel/src/components/EmsPanel.tsx`](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/components/EmsPanel.tsx) (EMS dashboard), [`ems/live.py`](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/live.py) (Live MQTT loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python EMS"]
  node_cli["CLI workflow<br/>[cli.py]"]
  node_config["Building config<br/>[config.py]"]
  node_climate["Climate input<br/>[clima.py]"]
  node_occupancy["Occupancy input<br/>[ocupacion.py]"]
  node_sim["Twin simulation<br/>[simulacion.py]"]
  node_building["Thermal building<br/>[edificio.py]"]
  node_events["Building events<br/>[eventos.py]"]
  node_control["EMS control<br/>[control.py]"]
end

subgraph group_iot["IoT Control"]
  node_live["Live MQTT loop<br/>[live.py]"]
  node_nodegen["Node-RED rules<br/>[ems_reglas.js]"]
  node_nodehttp["Manual control API<br/>[http_control.js]"]
  node_mqtt["MQTT broker"]
  node_influx[("InfluxDB telemetry<br/>[influx.py]")]
end

subgraph group_panel["Grafana Panel"]
  node_panelplugin["Grafana plugin<br/>[module.ts]"]
  node_panel["EMS dashboard<br/>[EmsPanel.tsx]"]
  node_visual["Building visualization<br/>[Building3D.tsx]"]
  node_webcontrol["Dashboard controls"]
  node_demosim["Demo simulator<br/>[simulator.ts]"]
  node_telemetry["Panel telemetry<br/>[telemetry.ts]"]
  node_eventsui["Incident simulation<br/>[events.ts]"]
end

subgraph group_analysis["Analysis"]
  node_scenarios["Scenario analysis<br/>[escenarios.py]"]
  node_forecast["Load forecast<br/>[pronostico.py]"]
  node_validation["EnergyPlus validation<br/>[validacion.py]"]
  node_kpi["Energy KPIs<br/>[kpi.py]"]
  node_reports["Reports<br/>[reportes.py]"]
end

node_operator(("Operator"))
node_energyplus["EnergyPlus"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"runs simulation"| node_sim
node_sim -->|"requests weather"| node_climate
node_sim -->|"requests occupancy"| node_occupancy
node_sim -->|"asks decisions"| node_control
node_sim -->|"applies commands"| node_building
node_building -->|"tracks incidents"| node_events
node_control -->|"uses zone model"| node_building
node_sim -->|"derives zones"| node_config
node_cli -->|"compares strategies"| node_scenarios
node_scenarios -->|"runs cases"| node_sim
node_scenarios -->|"computes metrics"| node_kpi
node_cli -->|"starts forecast"| node_forecast
node_forecast -->|"uses climate data"| node_climate
node_cli -->|"starts validation"| node_validation
node_validation -->|"compares twin"| node_sim
node_validation -.->|"validates against"| node_energyplus
node_cli -->|"writes outputs"| node_reports
node_operator -->|"starts live mode"| node_live
node_live -.->|"exchanges telemetry"| node_mqtt
node_live -.->|"stores live data"| node_influx
node_nodegen -->|"runs EMS rules"| node_mqtt
node_nodehttp -->|"publishes commands"| node_mqtt
node_panelplugin -->|"registers panel"| node_panel
node_panel -->|"renders building"| node_visual
node_panel -->|"renders controls"| node_webcontrol
node_panel -.->|"shows demo state"| node_demosim
node_panel -.->|"reads live data"| node_telemetry
node_panel -.->|"simulates incidents"| node_eventsui
node_webcontrol -->|"sends overrides"| node_nodehttp
node_panel -.->|"queries telemetry"| node_influx

click node_cli "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/cli.py"
click node_config "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/config.py"
click node_climate "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/clima.py"
click node_occupancy "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/ocupacion.py"
click node_sim "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/simulacion.py"
click node_building "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/edificio.py"
click node_events "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/eventos.py"
click node_control "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/control.py"
click node_live "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/live.py"
click node_nodegen "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/nodered/src/ems_reglas.js"
click node_nodehttp "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/nodered/src/http_control.js"
click node_influx "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/influx.py"
click node_panelplugin "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/module.ts"
click node_panel "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/components/EmsPanel.tsx"
click node_visual "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/components/Building3D.tsx"
click node_webcontrol "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/components/BuildingControl.tsx"
click node_demosim "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/building/simulator.ts"
click node_telemetry "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/building/telemetry.ts"
click node_eventsui "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/building/events.ts"
click node_scenarios "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/escenarios.py"
click node_forecast "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/pronostico.py"
click node_validation "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/validacion.py"
click node_kpi "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/kpi.py"
click node_reports "https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/reportes.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_cli,node_config,node_climate,node_occupancy,node_sim,node_building,node_events,node_control toneBlue
class node_live,node_nodegen,node_nodehttp,node_mqtt,node_influx toneAmber
class node_panelplugin,node_panel,node_visual,node_webcontrol,node_demosim,node_telemetry,node_eventsui toneMint
class node_scenarios,node_forecast,node_validation,node_kpi,node_reports toneRose
class node_operator,node_energyplus toneIndigo
```

## Components

### Python EMS

- [CLI workflow](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/cli.py): `ems/cli.py`
- [Building config](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/config.py): `ems/config.py`
- [Climate input](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/clima.py): `ems/clima.py`
- [Occupancy input](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/ocupacion.py): `ems/ocupacion.py`
- [Twin simulation](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/simulacion.py): `ems/simulacion.py`
- [Thermal building](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/edificio.py): `ems/edificio.py`
- [Building events](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/eventos.py): `ems/eventos.py`
- [EMS control](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/control.py): `ems/control.py`

### IoT Control

- [Live MQTT loop](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/live.py): `ems/live.py`
- [Node-RED rules](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/nodered/src/ems_reglas.js): `nodered/src/ems_reglas.js`
- [Manual control API](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/nodered/src/http_control.js): `nodered/src/http_control.js`
- **MQTT broker**
- [InfluxDB telemetry](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/influx.py): `ems/influx.py`

### Grafana Panel

- [Grafana plugin](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/module.ts): `grafana-ems-panel/src/module.ts`
- [EMS dashboard](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/components/EmsPanel.tsx): `grafana-ems-panel/src/components/EmsPanel.tsx`
- [Building visualization](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/components/Building3D.tsx): `grafana-ems-panel/src/components/Building3D.tsx`
- [Dashboard controls](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/components/BuildingControl.tsx): `grafana-ems-panel/src/components/BuildingControl.tsx`
- [Demo simulator](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/building/simulator.ts): `grafana-ems-panel/src/building/simulator.ts`
- [Panel telemetry](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/building/telemetry.ts): `grafana-ems-panel/src/building/telemetry.ts`
- [Incident simulation](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/grafana-ems-panel/src/building/events.ts): `grafana-ems-panel/src/building/events.ts`

### Analysis

- [Scenario analysis](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/escenarios.py): `ems/escenarios.py`
- [Load forecast](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/pronostico.py): `ems/pronostico.py`
- [EnergyPlus validation](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/validacion.py): `ems/validacion.py`
- [Energy KPIs](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/kpi.py): `ems/kpi.py`
- [Reports](https://github.com/doctype02/plugin-ems/blob/claude/focused-ramanujan-y99jeb/ems/reportes.py): `ems/reportes.py`

### Other components

- **Operator**
- **EnergyPlus**

## Connections

- Operator → CLI workflow: runs commands (evidence: `ems/cli.py`)
- CLI workflow → Building config: loads settings (evidence: `ems/cli.py`)
- CLI workflow → Twin simulation: runs simulation (evidence: `ems/cli.py`)
- Twin simulation → Climate input: requests weather (evidence: `ems/simulacion.py`)
- Twin simulation → Occupancy input: requests occupancy (evidence: `ems/simulacion.py`)
- Twin simulation → EMS control: asks decisions (evidence: `ems/simulacion.py`)
- Twin simulation → Thermal building: applies commands (evidence: `ems/simulacion.py`)
- Thermal building → Building events: tracks incidents (evidence: `ems/edificio.py`)
- EMS control → Thermal building: uses zone model (evidence: `ems/control.py`)
- Twin simulation → Building config: derives zones (evidence: `ems/simulacion.py`)
- CLI workflow → Scenario analysis: compares strategies (evidence: `ems/cli.py`)
- Scenario analysis → Twin simulation: runs cases (evidence: `ems/escenarios.py`)
- Scenario analysis → Energy KPIs: computes metrics (evidence: `ems/escenarios.py`)
- CLI workflow → Load forecast: starts forecast (evidence: `ems/cli.py`)
- Load forecast → Climate input: uses climate data (evidence: `ems/pronostico.py`)
- CLI workflow → EnergyPlus validation: starts validation (evidence: `ems/cli.py`)
- EnergyPlus validation → Twin simulation: compares twin (evidence: `ems/validacion.py`)
- EnergyPlus validation → EnergyPlus: validates against (evidence: `README.md`)
- CLI workflow → Reports: writes outputs (evidence: `ems/cli.py`)
- Operator → Live MQTT loop: starts live mode (evidence: `README.md`)
- Live MQTT loop → MQTT broker: exchanges telemetry (evidence: `README.md`)
- Live MQTT loop → InfluxDB telemetry: stores live data (evidence: `README.md`)
- Node-RED rules → MQTT broker: runs EMS rules
- Manual control API → MQTT broker: publishes commands (evidence: `README.md`)
- Grafana plugin → EMS dashboard: registers panel (evidence: `grafana-ems-panel/src/module.ts`)
- EMS dashboard → Building visualization: renders building (evidence: `grafana-ems-panel/src/components/EmsPanel.tsx`)
- EMS dashboard → Dashboard controls: renders controls (evidence: `grafana-ems-panel/src/components/EmsPanel.tsx`)
- EMS dashboard → Demo simulator: shows demo state (evidence: `README.md`)
- EMS dashboard → Panel telemetry: reads live data (evidence: `README.md`)
- EMS dashboard → Incident simulation: simulates incidents (evidence: `README.md`)
- Dashboard controls → Manual control API: sends overrides
- EMS dashboard → InfluxDB telemetry: queries telemetry (evidence: `README.md`)
