# aleisistan/clustercontrol architecture

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

- Interactive diagram: https://gitdiagram.com/aleisistan/clustercontrol
- Repository: https://github.com/aleisistan/clustercontrol

## Overview

ClusterControl lets administrators manage clusters, users and cameras, while authenticated users monitor device telemetry on a dashboard. Devices publish through MQTT; the backend ingests and stores telemetry and serves dashboard data, with camera relay, alerts, weather and industrial-test status as separate capabilities. The README documents the major integrations and user flows; source excerpts are incomplete, so unsampled subsystem links are shown only where the README supports them.

Main entry points: [`backend/src/main.ts`](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/main.ts) (NestJS API), [`frontend/src/app/app.routes.ts`](https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/app.routes.ts) (Angular application), [`frontend/src/app/dashboard/dashboard.component.ts`](https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/dashboard/dashboard.component.ts) (Telemetry dashboard), [`backend/src/users/users.service.ts`](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/users/users.service.ts) (User management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_frontend["Angular application<br/>[app.routes.ts]"]
  node_login["Login and session<br/>[auth.service.ts]"]
  node_dashboard["Telemetry dashboard"]
  node_adminui["Admin pages"]
end

subgraph group_identity["Identity and administration"]
  node_api["NestJS API<br/>[main.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_users["User management<br/>[users.service.ts]"]
  node_clusters["Cluster management<br/>[cluster.service.ts]"]
end

subgraph group_device["Devices and telemetry"]
  node_ingestion["MQTT ingestion<br/>[mqtt.service.ts]"]
  node_telemetry["Telemetry service"]
  node_industrial["Industrial test status"]
end

subgraph group_services["Operational services"]
  node_cameras["Camera management and relay"]
  node_alerts["Alerts and email<br/>[alerts.service.ts]"]
  node_weather["Weather panel<br/>[weather.service.ts]"]
end

subgraph group_infra["Runtime integrations"]
  node_postgres[("PostgreSQL")]
  node_device["MQTT device<br/>[main.cpp]"]
  node_simulator["Telemetry simulator<br/>[simulator.js]"]
  node_broker["MQTT broker"]
  node_industrialrunner["Industrial test runners<br/>[endurance.py]"]
end

node_user(("User"))
node_weatherapi["OpenWeather"]
node_camera["IP cameras"]

node_user -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_login
node_login -->|"requests login"| node_api
node_api -.->|"routes authentication"| node_auth
node_auth -->|"looks up user"| node_users
node_frontend -->|"routes to"| node_dashboard
node_frontend -->|"routes to"| node_adminui
node_adminui -.->|"manages clusters"| node_api
node_api -->|"routes cluster requests"| node_clusters
node_api -->|"routes user requests"| node_users
node_clusters -.->|"persists clusters"| node_postgres
node_users -.->|"persists users"| node_postgres
node_device -->|"publishes telemetry"| node_broker
node_simulator -->|"publishes telemetry"| node_broker
node_broker -->|"delivers messages"| node_ingestion
node_ingestion -.->|"passes readings"| node_telemetry
node_telemetry -.->|"stores readings"| node_postgres
node_dashboard -.->|"requests telemetry"| node_api
node_industrialrunner -->|"monitors MQTT"| node_broker
node_industrial -->|"reports test status"| node_dashboard
node_api -->|"routes camera requests"| node_cameras
node_cameras -->|"relays stream"| node_camera
node_api -->|"routes alert requests"| node_alerts
node_dashboard -.->|"shows weather"| node_weather
node_weather -->|"fetches forecast"| node_weatherapi

click node_frontend "https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/app.routes.ts"
click node_login "https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/services/auth.service.ts"
click node_dashboard "https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/dashboard/dashboard.component.ts"
click node_adminui "https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/pages/admin-clusters-page.component.ts"
click node_api "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/main.ts"
click node_auth "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/auth/auth.service.ts"
click node_users "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/users/users.service.ts"
click node_clusters "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/cluster/cluster.service.ts"
click node_device "https://github.com/aleisistan/clustercontrol/blob/main/firmware/esp32-mqtt-base/src/main.cpp"
click node_simulator "https://github.com/aleisistan/clustercontrol/blob/main/simulator/simulator.js"
click node_ingestion "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/telemetry/mqtt.service.ts"
click node_telemetry "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/telemetry/telemetry.service.ts"
click node_industrial "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/industrial-tests/industrial-test-status.service.ts"
click node_cameras "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/camera/camera.controller.ts"
click node_alerts "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/alerts/alerts.service.ts"
click node_weather "https://github.com/aleisistan/clustercontrol/blob/main/backend/src/weather/weather.service.ts"
click node_industrialrunner "https://github.com/aleisistan/clustercontrol/blob/main/tests-industriales/runner/endurance.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_frontend,node_login,node_dashboard,node_adminui,node_user toneBlue
class node_api,node_auth,node_users,node_clusters toneAmber
class node_ingestion,node_telemetry,node_industrial toneMint
class node_cameras,node_alerts,node_weather toneRose
class node_postgres,node_device,node_simulator,node_broker,node_industrialrunner,node_weatherapi,node_camera toneIndigo
```

## Components

### Web interface

- [Angular application](https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/app.routes.ts): `frontend/src/app/app.routes.ts`
- [Login and session](https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/services/auth.service.ts): `frontend/src/app/services/auth.service.ts`
- [Telemetry dashboard](https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/dashboard/dashboard.component.ts): `frontend/src/app/dashboard/dashboard.component.ts`
- [Admin pages](https://github.com/aleisistan/clustercontrol/blob/main/frontend/src/app/pages/admin-clusters-page.component.ts): `frontend/src/app/pages/admin-clusters-page.component.ts`

### Identity and administration

- [NestJS API](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/main.ts): `backend/src/main.ts`
- [Authentication](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [User management](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/users/users.service.ts): `backend/src/users/users.service.ts`
- [Cluster management](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/cluster/cluster.service.ts): `backend/src/cluster/cluster.service.ts`

### Devices and telemetry

- [MQTT ingestion](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/telemetry/mqtt.service.ts): `backend/src/telemetry/mqtt.service.ts`
- [Telemetry service](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/telemetry/telemetry.service.ts): `backend/src/telemetry/telemetry.service.ts`
- [Industrial test status](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/industrial-tests/industrial-test-status.service.ts): `backend/src/industrial-tests/industrial-test-status.service.ts`

### Operational services

- [Camera management and relay](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/camera/camera.controller.ts): `backend/src/camera/camera.controller.ts`
- [Alerts and email](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/alerts/alerts.service.ts): `backend/src/alerts/alerts.service.ts`
- [Weather panel](https://github.com/aleisistan/clustercontrol/blob/main/backend/src/weather/weather.service.ts): `backend/src/weather/weather.service.ts`

### Runtime integrations

- **PostgreSQL**
- [MQTT device](https://github.com/aleisistan/clustercontrol/blob/main/firmware/esp32-mqtt-base/src/main.cpp): `firmware/esp32-mqtt-base/src/main.cpp`
- [Telemetry simulator](https://github.com/aleisistan/clustercontrol/blob/main/simulator/simulator.js): `simulator/simulator.js`
- **MQTT broker**
- [Industrial test runners](https://github.com/aleisistan/clustercontrol/blob/main/tests-industriales/runner/endurance.py): `tests-industriales/runner/endurance.py`

### Other components

- **User**
- **OpenWeather**
- **IP cameras**

## Connections

- User → Angular application: uses
- Angular application → Login and session: routes to (evidence: `frontend/src/app/app.routes.ts`)
- Login and session → NestJS API: requests login
- NestJS API → Authentication: routes authentication
- Authentication → User management: looks up user (evidence: `backend/src/auth/auth.service.ts`)
- Angular application → Telemetry dashboard: routes to (evidence: `frontend/src/app/app.routes.ts`)
- Angular application → Admin pages: routes to (evidence: `frontend/src/app/app.routes.ts`)
- Admin pages → NestJS API: manages clusters
- NestJS API → Cluster management: routes cluster requests
- NestJS API → User management: routes user requests
- Cluster management → PostgreSQL: persists clusters
- User management → PostgreSQL: persists users
- MQTT device → MQTT broker: publishes telemetry
- Telemetry simulator → MQTT broker: publishes telemetry
- MQTT broker → MQTT ingestion: delivers messages
- MQTT ingestion → Telemetry service: passes readings
- Telemetry service → PostgreSQL: stores readings
- Telemetry dashboard → NestJS API: requests telemetry
- Industrial test runners → MQTT broker: monitors MQTT
- Industrial test status → Telemetry dashboard: reports test status
- NestJS API → Camera management and relay: routes camera requests (evidence: `backend/src/camera/camera.controller.ts`)
- Camera management and relay → IP cameras: relays stream
- NestJS API → Alerts and email: routes alert requests
- Telemetry dashboard → Weather panel: shows weather
- Weather panel → OpenWeather: fetches forecast
