# bems2026/bems architecture

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

- Interactive diagram: https://gitdiagram.com/bems2026/bems
- Repository: https://github.com/bems2026/bems

## Overview

iBEMS is a Raspberry Pi–hosted building energy management system. Its main path runs from LAN smart devices through a Node-RED bridge and authenticated proxy to the browser for live monitoring and control; a separate ingest daemon samples readings into Postgres for history and reporting. Site declarations provide the device and circuit model. The dashboard also supports enrolment, automation, load shedding, analytics, reports, and building-plan configuration. Several backend and UI subsystems are represented from README capabilities and indexed references; unsampled implementation details are not inferred.

Main entry points: [`src/App.tsx`](https://github.com/bems2026/bems/blob/master/src/App.tsx) (Dashboard app), [`node-red-bridge`](https://github.com/bems2026/bems/tree/master/node-red-bridge) (Node-RED bridge), [`server/ingest.mjs`](https://github.com/bems2026/bems/blob/master/server/ingest.mjs) (History ingestion), [`src/components/reports/ReportsPage.tsx`](https://github.com/bems2026/bems/blob/master/src/components/reports/ReportsPage.tsx) (Reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site and devices"]
  node_siteconfig["Site declarations<br/>[site.mjs]"]
  node_registry["Device registry<br/>[registry.mjs]"]
end

subgraph group_runtime["Bridge and services"]
  node_bridge["Node-RED bridge"]
  node_mock["Mock bridge<br/>[server.mjs]"]
  node_proxy["Authenticated proxy<br/>[proxy.mjs]"]
  node_latest["Live payload builder<br/>[buildLatest.mjs]"]
  node_ingest["History ingestion<br/>[ingest.mjs]"]
  node_shaperows["Reading shaping<br/>[shapeRows.mjs]"]
  node_archive[("Sealed archive<br/>[archiveDb.mjs]")]
end

subgraph group_frontend["Dashboard runtime"]
  node_app["Dashboard app<br/>[App.tsx]"]
  node_live["Live connection"]
  node_bridgeclient["Bridge client<br/>[bridgeClient.ts]"]
end

subgraph group_operations["Building operations"]
  node_overview["Overview<br/>[OverviewPage.tsx]"]
  node_control["Device control<br/>[ControlPage.tsx]"]
  node_devicesui["Fleet management<br/>[DevicesView.tsx]"]
  node_automation["Automation<br/>[AutomationPage.tsx]"]
  node_settings["Settings<br/>[SettingsPage.tsx]"]
end

subgraph group_insights["Energy insights"]
  node_analytics["Analytics<br/>[AnalyticsPage.tsx]"]
  node_reports["Reports<br/>[ReportsPage.tsx]"]
  node_reportdata["Report data<br/>[useReportData.ts]"]
end

node_operator(("Building operator"))
node_devices{{"LAN smart devices"}}
node_database[("Postgres history")]

node_operator -->|"uses"| node_app
node_devices -->|"send readings"| node_bridge
node_bridge -->|"builds payload"| node_latest
node_latest -->|"shared transform"| node_mock
node_bridge -->|"serves live data"| node_proxy
node_proxy -->|"proxies requests"| node_bridgeclient
node_bridgeclient -->|"connects live"| node_live
node_live -->|"updates stores"| node_app
node_bridge -->|"polled readings"| node_ingest
node_ingest -->|"shapes readings"| node_shaperows
node_ingest -->|"upserts history"| node_database
node_ingest -->|"seals streams"| node_archive
node_siteconfig -->|"selects site"| node_registry
node_app -->|"routes to"| node_overview
node_app -->|"routes to"| node_control
node_app -->|"routes to"| node_devicesui
node_app -->|"routes to"| node_automation
node_app -->|"routes to"| node_analytics
node_app -->|"routes to"| node_reports
node_app -->|"routes to"| node_settings
node_reports -.->|"loads report data"| node_reportdata
node_operator -->|"commands devices"| node_control
node_operator -->|"manages fleet"| node_devicesui
node_operator -->|"sets schedules"| node_automation
node_operator -->|"reviews energy"| node_analytics
node_operator -->|"exports reports"| node_reports
node_operator -->|"configures site"| node_settings

click node_siteconfig "https://github.com/bems2026/bems/blob/master/shared/sites/mmsu-nberic-care/site.mjs"
click node_registry "https://github.com/bems2026/bems/blob/master/shared/registry.mjs"
click node_bridge "https://github.com/bems2026/bems/tree/master/node-red-bridge"
click node_mock "https://github.com/bems2026/bems/blob/master/mock-bridge/server.mjs"
click node_proxy "https://github.com/bems2026/bems/blob/master/server/proxy.mjs"
click node_latest "https://github.com/bems2026/bems/blob/master/shared/buildLatest.mjs"
click node_ingest "https://github.com/bems2026/bems/blob/master/server/ingest.mjs"
click node_shaperows "https://github.com/bems2026/bems/blob/master/server/shapeRows.mjs"
click node_archive "https://github.com/bems2026/bems/blob/master/server/archiveDb.mjs"
click node_app "https://github.com/bems2026/bems/blob/master/src/App.tsx"
click node_live "https://github.com/bems2026/bems/blob/master/src/hooks/useLiveConnection.ts"
click node_bridgeclient "https://github.com/bems2026/bems/blob/master/src/lib/bridgeClient.ts"
click node_overview "https://github.com/bems2026/bems/blob/master/src/components/overview/OverviewPage.tsx"
click node_control "https://github.com/bems2026/bems/blob/master/src/components/control/ControlPage.tsx"
click node_devicesui "https://github.com/bems2026/bems/blob/master/src/components/devices/DevicesView.tsx"
click node_automation "https://github.com/bems2026/bems/blob/master/src/components/automation/AutomationPage.tsx"
click node_analytics "https://github.com/bems2026/bems/blob/master/src/components/analytics/AnalyticsPage.tsx"
click node_reports "https://github.com/bems2026/bems/blob/master/src/components/reports/ReportsPage.tsx"
click node_reportdata "https://github.com/bems2026/bems/blob/master/src/components/reports/useReportData.ts"
click node_settings "https://github.com/bems2026/bems/blob/master/src/components/settings/SettingsPage.tsx"

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_siteconfig,node_registry toneBlue
class node_bridge,node_mock,node_proxy,node_latest,node_ingest,node_shaperows,node_archive,node_database toneAmber
class node_app,node_live,node_bridgeclient toneMint
class node_overview,node_control,node_devicesui,node_automation,node_settings toneRose
class node_analytics,node_reports,node_reportdata,node_operator,node_devices toneIndigo
```

## Components

### Site and devices

- [Site declarations](https://github.com/bems2026/bems/blob/master/shared/sites/mmsu-nberic-care/site.mjs): `shared/sites/mmsu-nberic-care/site.mjs`
- [Device registry](https://github.com/bems2026/bems/blob/master/shared/registry.mjs): `shared/registry.mjs`

### Bridge and services

- [Node-RED bridge](https://github.com/bems2026/bems/tree/master/node-red-bridge): `node-red-bridge`
- [Mock bridge](https://github.com/bems2026/bems/blob/master/mock-bridge/server.mjs): `mock-bridge/server.mjs`
- [Authenticated proxy](https://github.com/bems2026/bems/blob/master/server/proxy.mjs): `server/proxy.mjs`
- [Live payload builder](https://github.com/bems2026/bems/blob/master/shared/buildLatest.mjs): `shared/buildLatest.mjs`
- [History ingestion](https://github.com/bems2026/bems/blob/master/server/ingest.mjs): `server/ingest.mjs`
- [Reading shaping](https://github.com/bems2026/bems/blob/master/server/shapeRows.mjs): `server/shapeRows.mjs`
- [Sealed archive](https://github.com/bems2026/bems/blob/master/server/archiveDb.mjs): `server/archiveDb.mjs`

### Dashboard runtime

- [Dashboard app](https://github.com/bems2026/bems/blob/master/src/App.tsx): `src/App.tsx`
- [Live connection](https://github.com/bems2026/bems/blob/master/src/hooks/useLiveConnection.ts): `src/hooks/useLiveConnection.ts`
- [Bridge client](https://github.com/bems2026/bems/blob/master/src/lib/bridgeClient.ts): `src/lib/bridgeClient.ts`

### Building operations

- [Overview](https://github.com/bems2026/bems/blob/master/src/components/overview/OverviewPage.tsx): `src/components/overview/OverviewPage.tsx`
- [Device control](https://github.com/bems2026/bems/blob/master/src/components/control/ControlPage.tsx): `src/components/control/ControlPage.tsx`
- [Fleet management](https://github.com/bems2026/bems/blob/master/src/components/devices/DevicesView.tsx): `src/components/devices/DevicesView.tsx`
- [Automation](https://github.com/bems2026/bems/blob/master/src/components/automation/AutomationPage.tsx): `src/components/automation/AutomationPage.tsx`
- [Settings](https://github.com/bems2026/bems/blob/master/src/components/settings/SettingsPage.tsx): `src/components/settings/SettingsPage.tsx`

### Energy insights

- [Analytics](https://github.com/bems2026/bems/blob/master/src/components/analytics/AnalyticsPage.tsx): `src/components/analytics/AnalyticsPage.tsx`
- [Reports](https://github.com/bems2026/bems/blob/master/src/components/reports/ReportsPage.tsx): `src/components/reports/ReportsPage.tsx`
- [Report data](https://github.com/bems2026/bems/blob/master/src/components/reports/useReportData.ts): `src/components/reports/useReportData.ts`

### Other components

- **Building operator**
- **LAN smart devices**
- **Postgres history**

## Connections

- Building operator → Dashboard app: uses (evidence: `README.md`)
- LAN smart devices → Node-RED bridge: send readings (evidence: `README.md`)
- Node-RED bridge → Live payload builder: builds payload (evidence: `README.md`)
- Live payload builder → Mock bridge: shared transform (evidence: `README.md`)
- Node-RED bridge → Authenticated proxy: serves live data (evidence: `README.md`)
- Authenticated proxy → Bridge client: proxies requests (evidence: `README.md`)
- Bridge client → Live connection: connects live (evidence: `src/hooks/useLiveConnection.ts`)
- Live connection → Dashboard app: updates stores (evidence: `src/hooks/useLiveConnection.ts`)
- Node-RED bridge → History ingestion: polled readings (evidence: `README.md`)
- History ingestion → Reading shaping: shapes readings (evidence: `server/ingest.mjs`)
- History ingestion → Postgres history: upserts history (evidence: `server/ingest.mjs`)
- History ingestion → Sealed archive: seals streams (evidence: `server/ingest.mjs`)
- Site declarations → Device registry: selects site (evidence: `README.md`)
- Dashboard app → Overview: routes to (evidence: `src/App.tsx`)
- Dashboard app → Device control: routes to (evidence: `src/App.tsx`)
- Dashboard app → Fleet management: routes to (evidence: `src/App.tsx`)
- Dashboard app → Automation: routes to (evidence: `src/App.tsx`)
- Dashboard app → Analytics: routes to (evidence: `src/App.tsx`)
- Dashboard app → Reports: routes to (evidence: `src/App.tsx`)
- Dashboard app → Settings: routes to (evidence: `src/App.tsx`)
- Reports → Report data: loads report data
- Building operator → Device control: commands devices (evidence: `README.md`)
- Building operator → Fleet management: manages fleet (evidence: `README.md`)
- Building operator → Automation: sets schedules (evidence: `README.md`)
- Building operator → Analytics: reviews energy (evidence: `README.md`)
- Building operator → Reports: exports reports (evidence: `README.md`)
- Building operator → Settings: configures site (evidence: `README.md`)
