# cyclone03/gridd-smart-environment architecture

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

- Interactive diagram: https://gitdiagram.com/cyclone03/gridd-smart-environment
- Repository: https://github.com/cyclone03/gridd-smart-environment

## Overview

GRIDD is a smart-environment dashboard for collecting sensor observations, assessing comfort and threshold alerts, and presenting current conditions and history. Observations enter through the optional Kafka consumer or simulator, then the shared processor validates and persists them, evaluates alerts and comfort, and broadcasts realtime events. The web app provides dashboard, observation, alert and location views. The README documents the API and realtime capabilities; several frontend-to-backend connections are not shown in the sampled source, so those links are marked unverified.

Main entry points: [`apps/api/src/observations/observation.processor.ts`](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observation.processor.ts) (Observation processor), [`apps/api/src/analysis/analysis.service.ts`](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/analysis.service.ts) (Comfort analysis), [`apps/web/src/services/api.ts`](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/services/api.ts) (HTTP API client), [`apps/api/src/alerts/alerts.service.ts`](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/alerts/alerts.service.ts) (Alert evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Ingestion"]
  node_kafka["Kafka consumer"]
  node_mapper["Kafka mapping"]
  node_simulator["Observation simulator"]
  node_processor["Observation processor"]
  node_validator["Input validation"]
  node_input["Observation input"]
end

subgraph group_domain["Analysis & alerts"]
  node_analysis["Comfort analysis"]
  node_comfort["Comfort configuration"]
  node_comfort_types["Comfort results<br/>[comfort.types.ts]"]
  node_alerts["Alert evaluation<br/>[alerts.service.ts]"]
end

subgraph group_api["API &amp; realtime"]
  node_realtime["Realtime gateway"]
  node_obs_controller["Observation endpoints"]
  node_analysis_controller["Comfort endpoint"]
  node_alerts_controller["Alert endpoints"]
  node_health["Health endpoint"]
end

subgraph group_web["Web dashboard"]
  node_views["Dashboard views<br/>[DashboardView.vue]"]
  node_obs_view["Observation view"]
  node_alert_view["Alerts view<br/>[AlertsView.vue]"]
  node_location_view["Locations view<br/>[LocationsView.vue]"]
  node_dashboard_store["Dashboard state<br/>[dashboard.store.ts]"]
  node_obs_store["Observation state"]
  node_alerts_store["Alert state<br/>[alerts.store.ts]"]
  node_locations_store["Location state<br/>[locations.store.ts]"]
  node_api_client["HTTP API client<br/>[api.ts]"]
  node_socket_client["Realtime client<br/>[realtime.ts]"]
  node_chart["Observation chart"]
  node_comfort_card["Comfort display<br/>[ComfortCard.vue]"]
  node_location_tree["Location tree"]
end

subgraph group_storage["Persistence"]
  node_observations["Observation service"]
  node_observation[("Observation records")]
  node_alert[("Alert records<br/>[alert.entity.ts]")]
  node_db_config["Database configuration<br/>[typeorm.config.ts]"]
end

node_user(("Dashboard user"))

node_kafka -->|"maps messages"| node_mapper
node_kafka -->|"processes input"| node_processor
node_mapper -->|"creates"| node_input
node_simulator -->|"processes samples"| node_processor
node_processor -->|"validates"| node_validator
node_processor -->|"persists"| node_observations
node_observations -->|"reads and writes"| node_observation
node_processor -->|"evaluates"| node_alerts
node_alerts -->|"reads and writes"| node_alert
node_processor -->|"requests comfort"| node_analysis
node_analysis -->|"queries measurements"| node_observation
node_analysis -->|"uses thresholds"| node_comfort
node_analysis -->|"returns result"| node_comfort_types
node_alerts -->|"uses thresholds"| node_comfort
node_processor -->|"emits updates"| node_realtime
node_obs_controller -->|"lists observations"| node_observations
node_analysis_controller -->|"requests comfort"| node_analysis
node_alerts_controller -->|"filters alerts"| node_alerts
node_db_config -->|"registers entity"| node_observation
node_db_config -->|"registers entity"| node_alert
node_user -.->|"uses dashboard"| node_views
node_views -.->|"reads state"| node_dashboard_store
node_obs_view -.->|"reads state"| node_obs_store
node_alert_view -.->|"reads state"| node_alerts_store
node_location_view -.->|"reads state"| node_locations_store
node_dashboard_store -->|"uses observations"| node_obs_store
node_dashboard_store -->|"uses alerts"| node_alerts_store
node_obs_store -.->|"requests data"| node_api_client
node_alerts_store -.->|"requests data"| node_api_client
node_locations_store -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_obs_controller
node_api_client -.->|"calls API"| node_alerts_controller
node_socket_client -.->|"receives events"| node_realtime
node_views -.->|"displays comfort"| node_comfort_card
node_obs_view -.->|"renders history"| node_chart
node_location_view -.->|"renders hierarchy"| node_location_tree

click node_kafka "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/kafka/kafka.consumer.service.ts"
click node_mapper "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/kafka/kafka-message.mapper.ts"
click node_simulator "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/simulator/simulator.service.ts"
click node_processor "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observation.processor.ts"
click node_validator "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observation-input.validator.ts"
click node_input "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/interfaces/observation-input.interface.ts"
click node_observations "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observations.service.ts"
click node_observation "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/entities/observation.entity.ts"
click node_analysis "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/analysis.service.ts"
click node_comfort "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/environment.config.ts"
click node_comfort_types "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/comfort.types.ts"
click node_alerts "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/alerts/alerts.service.ts"
click node_alert "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/alerts/entities/alert.entity.ts"
click node_realtime "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/realtime/realtime.gateway.ts"
click node_obs_controller "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observations.controller.ts"
click node_analysis_controller "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/analysis.controller.ts"
click node_alerts_controller "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/alerts/alerts.controller.ts"
click node_health "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/health/health.controller.ts"
click node_db_config "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/database/typeorm.config.ts"
click node_views "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/DashboardView.vue"
click node_obs_view "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/ObservationsView.vue"
click node_alert_view "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/AlertsView.vue"
click node_location_view "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/LocationsView.vue"
click node_dashboard_store "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/dashboard.store.ts"
click node_obs_store "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/observations.store.ts"
click node_alerts_store "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/alerts.store.ts"
click node_locations_store "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/locations.store.ts"
click node_api_client "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/services/api.ts"
click node_socket_client "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/services/realtime.ts"
click node_chart "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/components/charts/ObservationChart.vue"
click node_comfort_card "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/components/dashboard/ComfortCard.vue"
click node_location_tree "https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/components/locations/LocationTreeNode.vue"

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_kafka,node_mapper,node_simulator,node_processor,node_validator,node_input,node_user toneBlue
class node_analysis,node_comfort,node_comfort_types,node_alerts toneAmber
class node_realtime,node_obs_controller,node_analysis_controller,node_alerts_controller,node_health toneMint
class node_views,node_obs_view,node_alert_view,node_location_view,node_dashboard_store,node_obs_store,node_alerts_store,node_locations_store,node_api_client,node_socket_client,node_chart,node_comfort_card,node_location_tree toneRose
class node_observations,node_observation,node_alert,node_db_config toneIndigo
```

## Components

### Ingestion

- [Kafka consumer](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/kafka/kafka.consumer.service.ts): `apps/api/src/kafka/kafka.consumer.service.ts`
- [Kafka mapping](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/kafka/kafka-message.mapper.ts): `apps/api/src/kafka/kafka-message.mapper.ts`
- [Observation simulator](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/simulator/simulator.service.ts): `apps/api/src/simulator/simulator.service.ts`
- [Observation processor](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observation.processor.ts): `apps/api/src/observations/observation.processor.ts`
- [Input validation](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observation-input.validator.ts): `apps/api/src/observations/observation-input.validator.ts`
- [Observation input](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/interfaces/observation-input.interface.ts): `apps/api/src/observations/interfaces/observation-input.interface.ts`

### Analysis & alerts

- [Comfort analysis](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/analysis.service.ts): `apps/api/src/analysis/analysis.service.ts`
- [Comfort configuration](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/environment.config.ts): `apps/api/src/analysis/environment.config.ts`
- [Comfort results](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/comfort.types.ts): `apps/api/src/analysis/comfort.types.ts`
- [Alert evaluation](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/alerts/alerts.service.ts): `apps/api/src/alerts/alerts.service.ts`

### API & realtime

- [Realtime gateway](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/realtime/realtime.gateway.ts): `apps/api/src/realtime/realtime.gateway.ts`
- [Observation endpoints](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observations.controller.ts): `apps/api/src/observations/observations.controller.ts`
- [Comfort endpoint](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/analysis/analysis.controller.ts): `apps/api/src/analysis/analysis.controller.ts`
- [Alert endpoints](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/alerts/alerts.controller.ts): `apps/api/src/alerts/alerts.controller.ts`
- [Health endpoint](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/health/health.controller.ts): `apps/api/src/health/health.controller.ts`

### Web dashboard

- [Dashboard views](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/DashboardView.vue): `apps/web/src/views/DashboardView.vue`
- [Observation view](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/ObservationsView.vue): `apps/web/src/views/ObservationsView.vue`
- [Alerts view](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/AlertsView.vue): `apps/web/src/views/AlertsView.vue`
- [Locations view](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/views/LocationsView.vue): `apps/web/src/views/LocationsView.vue`
- [Dashboard state](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/dashboard.store.ts): `apps/web/src/stores/dashboard.store.ts`
- [Observation state](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/observations.store.ts): `apps/web/src/stores/observations.store.ts`
- [Alert state](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/alerts.store.ts): `apps/web/src/stores/alerts.store.ts`
- [Location state](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/stores/locations.store.ts): `apps/web/src/stores/locations.store.ts`
- [HTTP API client](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/services/api.ts): `apps/web/src/services/api.ts`
- [Realtime client](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/services/realtime.ts): `apps/web/src/services/realtime.ts`
- [Observation chart](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/components/charts/ObservationChart.vue): `apps/web/src/components/charts/ObservationChart.vue`
- [Comfort display](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/components/dashboard/ComfortCard.vue): `apps/web/src/components/dashboard/ComfortCard.vue`
- [Location tree](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/web/src/components/locations/LocationTreeNode.vue): `apps/web/src/components/locations/LocationTreeNode.vue`

### Persistence

- [Observation service](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/observations.service.ts): `apps/api/src/observations/observations.service.ts`
- [Observation records](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/observations/entities/observation.entity.ts): `apps/api/src/observations/entities/observation.entity.ts`
- [Alert records](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/alerts/entities/alert.entity.ts): `apps/api/src/alerts/entities/alert.entity.ts`
- [Database configuration](https://github.com/cyclone03/gridd-smart-environment/blob/main/apps/api/src/database/typeorm.config.ts): `apps/api/src/database/typeorm.config.ts`

### Other components

- **Dashboard user**

## Connections

- Kafka consumer → Kafka mapping: maps messages (evidence: `apps/api/src/kafka/kafka.consumer.service.ts`)
- Kafka consumer → Observation processor: processes input (evidence: `apps/api/src/kafka/kafka.consumer.service.ts`)
- Kafka mapping → Observation input: creates (evidence: `apps/api/src/kafka/kafka-message.mapper.ts`)
- Observation simulator → Observation processor: processes samples (evidence: `apps/api/src/simulator/simulator.service.ts`)
- Observation processor → Input validation: validates (evidence: `apps/api/src/observations/observation.processor.ts`)
- Observation processor → Observation service: persists (evidence: `apps/api/src/observations/observation.processor.ts`)
- Observation service → Observation records: reads and writes (evidence: `apps/api/src/observations/observations.service.ts`)
- Observation processor → Alert evaluation: evaluates (evidence: `apps/api/src/observations/observation.processor.ts`)
- Alert evaluation → Alert records: reads and writes (evidence: `apps/api/src/alerts/alerts.service.ts`)
- Observation processor → Comfort analysis: requests comfort (evidence: `apps/api/src/observations/observation.processor.ts`)
- Comfort analysis → Observation records: queries measurements (evidence: `apps/api/src/analysis/analysis.service.ts`)
- Comfort analysis → Comfort configuration: uses thresholds (evidence: `apps/api/src/analysis/analysis.service.ts`)
- Comfort analysis → Comfort results: returns result (evidence: `apps/api/src/analysis/analysis.service.ts`)
- Alert evaluation → Comfort configuration: uses thresholds (evidence: `apps/api/src/alerts/alerts.service.ts`)
- Observation processor → Realtime gateway: emits updates (evidence: `apps/api/src/observations/observation.processor.ts`)
- Observation endpoints → Observation service: lists observations (evidence: `apps/api/src/observations/observations.controller.ts`)
- Comfort endpoint → Comfort analysis: requests comfort (evidence: `apps/api/src/analysis/analysis.controller.ts`)
- Alert endpoints → Alert evaluation: filters alerts (evidence: `apps/api/src/alerts/alerts.controller.ts`)
- Database configuration → Observation records: registers entity (evidence: `apps/api/src/database/typeorm.config.ts`)
- Database configuration → Alert records: registers entity (evidence: `apps/api/src/database/typeorm.config.ts`)
- Dashboard user → Dashboard views: uses dashboard
- Dashboard views → Dashboard state: reads state
- Observation view → Observation state: reads state
- Alerts view → Alert state: reads state
- Locations view → Location state: reads state
- Dashboard state → Observation state: uses observations (evidence: `apps/web/src/stores/dashboard.store.ts`)
- Dashboard state → Alert state: uses alerts (evidence: `apps/web/src/stores/dashboard.store.ts`)
- Observation state → HTTP API client: requests data
- Alert state → HTTP API client: requests data
- Location state → HTTP API client: requests data
- HTTP API client → Observation endpoints: calls API
- HTTP API client → Alert endpoints: calls API
- Realtime client → Realtime gateway: receives events
- Dashboard views → Comfort display: displays comfort
- Observation view → Observation chart: renders history
- Locations view → Location tree: renders hierarchy