# udbhav07/edge-smart-space architecture

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

- Interactive diagram: https://gitdiagram.com/udbhav07/edge-smart-space
- Repository: https://github.com/udbhav07/edge-smart-space

## Overview

edge-smart-space is an edge-hosted autonomous smart-room system. Its central loop turns sensor readings into thermal estimates and fault health, proposes setpoint goals, validates them, and regulates the actuator; MQTT is the sole inter-service blackboard. Separate reasoning and optional speech provide occupant interaction, while the browser console exposes controls and operational views. The README establishes the independent cadences and safety boundary; source-index references and excerpts support selected internal links. Several console pages and integrations are documented but unsampled, so their internal wiring is not inferred.

Main entry points: [`src/common/mqtt_client.py`](https://github.com/udbhav07/edge-smart-space/blob/main/src/common/mqtt_client.py) (MQTT blackboard), [`src/reasoning/assistant.py`](https://github.com/udbhav07/edge-smart-space/blob/main/src/reasoning/assistant.py) (Reasoning assistant), [`src/estimation/service.py`](https://github.com/udbhav07/edge-smart-space/blob/main/src/estimation/service.py) (Thermal estimator), [`src/control/service.py`](https://github.com/udbhav07/edge-smart-space/blob/main/src/control/service.py) (Goal and regulatory control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_room_io["Room I/O"]
  node_sensing["Sensor adapters<br/>[devices.py]"]
  node_simulator["Room simulator<br/>[run_sim.py]"]
  node_device_services["Device services<br/>[service.py]"]
  node_blackboard["MQTT blackboard<br/>[mqtt_client.py]"]
  node_contracts["Topics and schemas<br/>[topics.py]"]
end

subgraph group_control["Estimation and control"]
  node_estimator["Thermal estimator<br/>[service.py]"]
  node_estimator_model["RLS model<br/>[rls.py]"]
  node_coefficient_store[("Coefficient persistence<br/>[persistence.py]")]
  node_fault_service["Fault detection<br/>[service.py]"]
  node_goal_control["Goal and regulatory control<br/>[service.py]"]
  node_safety["Goal validation<br/>[validator.py]"]
end

subgraph group_intelligence["Reasoning and assistance"]
  node_assistant["Reasoning assistant<br/>[assistant.py]"]
  node_tool_catalogue["Tool registry<br/>[tools.py]"]
  node_memory["Assistance memory<br/>[memory.py]"]
  node_google["Google calendar and mail<br/>[sync.py]"]
end

subgraph group_interaction["Occupant interaction"]
  node_speech["Speech pipeline<br/>[pipeline.py]"]
end

subgraph group_operations["Console and observability"]
  node_console_server["Console server<br/>[server.py]"]
  node_console_state["Console state<br/>[state.py]"]
  node_web_app["Browser console<br/>[App.tsx]"]
end

node_occupant(("Occupant"))
node_operator(("Operator"))
node_inference["Inference server"]
node_google_service["Google services"]

node_occupant -->|"speaks to"| node_speech
node_occupant -->|"uses"| node_web_app
node_operator -->|"operates"| node_web_app
node_sensing -->|"publishes readings"| node_blackboard
node_simulator -->|"publishes simulated state"| node_blackboard
node_blackboard -->|"delivers readings"| node_estimator
node_estimator -->|"updates model"| node_estimator_model
node_estimator -->|"loads and persists"| node_coefficient_store
node_estimator -->|"publishes estimates"| node_blackboard
node_blackboard -->|"delivers sensor data"| node_fault_service
node_fault_service -->|"publishes health and faults"| node_blackboard
node_blackboard -->|"delivers control inputs"| node_goal_control
node_goal_control -->|"validates goals"| node_safety
node_goal_control -->|"publishes commands"| node_blackboard
node_assistant -->|"invokes tools"| node_tool_catalogue
node_assistant -.->|"requests reasoning"| node_inference
node_assistant -->|"proposes setpoints"| node_blackboard
node_tool_catalogue -.->|"dispatches device actions"| node_device_services
node_assistant -.->|"uses assistance memory"| node_memory
node_assistant -.->|"uses account integrations"| node_google
node_google -.->|"accesses"| node_google_service
node_speech -->|"passes spoken requests"| node_assistant
node_console_server -->|"subscribes and publishes"| node_blackboard
node_console_server -->|"updates state"| node_console_state
node_web_app -.->|"uses console API"| node_console_server
node_console_state -->|"reads room state"| node_blackboard
node_contracts -->|"defines topic contracts"| node_blackboard

click node_sensing "https://github.com/udbhav07/edge-smart-space/blob/main/src/io/devices.py"
click node_simulator "https://github.com/udbhav07/edge-smart-space/blob/main/sim/run_sim.py"
click node_device_services "https://github.com/udbhav07/edge-smart-space/blob/main/src/devices/service.py"
click node_blackboard "https://github.com/udbhav07/edge-smart-space/blob/main/src/common/mqtt_client.py"
click node_contracts "https://github.com/udbhav07/edge-smart-space/blob/main/src/common/topics.py"
click node_estimator "https://github.com/udbhav07/edge-smart-space/blob/main/src/estimation/service.py"
click node_estimator_model "https://github.com/udbhav07/edge-smart-space/blob/main/src/estimation/rls.py"
click node_coefficient_store "https://github.com/udbhav07/edge-smart-space/blob/main/src/estimation/persistence.py"
click node_fault_service "https://github.com/udbhav07/edge-smart-space/blob/main/src/faults/service.py"
click node_goal_control "https://github.com/udbhav07/edge-smart-space/blob/main/src/control/service.py"
click node_safety "https://github.com/udbhav07/edge-smart-space/blob/main/src/control/validator.py"
click node_assistant "https://github.com/udbhav07/edge-smart-space/blob/main/src/reasoning/assistant.py"
click node_tool_catalogue "https://github.com/udbhav07/edge-smart-space/blob/main/src/common/tools.py"
click node_memory "https://github.com/udbhav07/edge-smart-space/blob/main/src/assistance/memory.py"
click node_google "https://github.com/udbhav07/edge-smart-space/blob/main/src/assistance/google/sync.py"
click node_speech "https://github.com/udbhav07/edge-smart-space/blob/main/src/speech/pipeline.py"
click node_console_server "https://github.com/udbhav07/edge-smart-space/blob/main/src/console/server.py"
click node_console_state "https://github.com/udbhav07/edge-smart-space/blob/main/src/console/state.py"
click node_web_app "https://github.com/udbhav07/edge-smart-space/blob/main/console/web/src/App.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_sensing,node_simulator,node_device_services,node_blackboard,node_contracts toneBlue
class node_estimator,node_estimator_model,node_coefficient_store,node_fault_service,node_goal_control,node_safety toneAmber
class node_assistant,node_tool_catalogue,node_memory,node_google,node_inference toneMint
class node_speech toneRose
class node_console_server,node_console_state,node_web_app,node_occupant,node_operator,node_google_service toneIndigo
```

## Components

### Room I/O

- [Sensor adapters](https://github.com/udbhav07/edge-smart-space/blob/main/src/io/devices.py): `src/io/devices.py`
- [Room simulator](https://github.com/udbhav07/edge-smart-space/blob/main/sim/run_sim.py): `sim/run_sim.py`
- [Device services](https://github.com/udbhav07/edge-smart-space/blob/main/src/devices/service.py): `src/devices/service.py`
- [MQTT blackboard](https://github.com/udbhav07/edge-smart-space/blob/main/src/common/mqtt_client.py): `src/common/mqtt_client.py`
- [Topics and schemas](https://github.com/udbhav07/edge-smart-space/blob/main/src/common/topics.py): `src/common/topics.py`

### Estimation and control

- [Thermal estimator](https://github.com/udbhav07/edge-smart-space/blob/main/src/estimation/service.py): `src/estimation/service.py`
- [RLS model](https://github.com/udbhav07/edge-smart-space/blob/main/src/estimation/rls.py): `src/estimation/rls.py`
- [Coefficient persistence](https://github.com/udbhav07/edge-smart-space/blob/main/src/estimation/persistence.py): `src/estimation/persistence.py`
- [Fault detection](https://github.com/udbhav07/edge-smart-space/blob/main/src/faults/service.py): `src/faults/service.py`
- [Goal and regulatory control](https://github.com/udbhav07/edge-smart-space/blob/main/src/control/service.py): `src/control/service.py`
- [Goal validation](https://github.com/udbhav07/edge-smart-space/blob/main/src/control/validator.py): `src/control/validator.py`

### Reasoning and assistance

- [Reasoning assistant](https://github.com/udbhav07/edge-smart-space/blob/main/src/reasoning/assistant.py): `src/reasoning/assistant.py`
- [Tool registry](https://github.com/udbhav07/edge-smart-space/blob/main/src/common/tools.py): `src/common/tools.py`
- [Assistance memory](https://github.com/udbhav07/edge-smart-space/blob/main/src/assistance/memory.py): `src/assistance/memory.py`
- [Google calendar and mail](https://github.com/udbhav07/edge-smart-space/blob/main/src/assistance/google/sync.py): `src/assistance/google/sync.py`

### Occupant interaction

- [Speech pipeline](https://github.com/udbhav07/edge-smart-space/blob/main/src/speech/pipeline.py): `src/speech/pipeline.py`

### Console and observability

- [Console server](https://github.com/udbhav07/edge-smart-space/blob/main/src/console/server.py): `src/console/server.py`
- [Console state](https://github.com/udbhav07/edge-smart-space/blob/main/src/console/state.py): `src/console/state.py`
- [Browser console](https://github.com/udbhav07/edge-smart-space/blob/main/console/web/src/App.tsx): `console/web/src/App.tsx`

### Other components

- **Occupant**
- **Operator**
- **Inference server**
- **Google services**

## Connections

- Occupant → Speech pipeline: speaks to (evidence: `README.md`)
- Occupant → Browser console: uses (evidence: `README.md`)
- Operator → Browser console: operates (evidence: `README.md`)
- Sensor adapters → MQTT blackboard: publishes readings (evidence: `src/io/devices.py`)
- Room simulator → MQTT blackboard: publishes simulated state (evidence: `sim/run_sim.py`)
- MQTT blackboard → Thermal estimator: delivers readings (evidence: `src/estimation/service.py`)
- Thermal estimator → RLS model: updates model (evidence: `src/estimation/service.py`)
- Thermal estimator → Coefficient persistence: loads and persists (evidence: `src/estimation/service.py`)
- Thermal estimator → MQTT blackboard: publishes estimates (evidence: `src/estimation/service.py`)
- MQTT blackboard → Fault detection: delivers sensor data (evidence: `src/faults/service.py`)
- Fault detection → MQTT blackboard: publishes health and faults (evidence: `src/faults/service.py`)
- MQTT blackboard → Goal and regulatory control: delivers control inputs (evidence: `src/control/service.py`)
- Goal and regulatory control → Goal validation: validates goals (evidence: `src/control/service.py`)
- Goal and regulatory control → MQTT blackboard: publishes commands (evidence: `src/control/service.py`)
- Reasoning assistant → Tool registry: invokes tools (evidence: `src/reasoning/assistant.py`)
- Reasoning assistant → Inference server: requests reasoning (evidence: `README.md`)
- Reasoning assistant → MQTT blackboard: proposes setpoints (evidence: `README.md`)
- Tool registry → Device services: dispatches device actions (evidence: `src/devices/service.py`)
- Reasoning assistant → Assistance memory: uses assistance memory
- Reasoning assistant → Google calendar and mail: uses account integrations
- Google calendar and mail → Google services: accesses (evidence: `README.md`)
- Speech pipeline → Reasoning assistant: passes spoken requests (evidence: `src/speech/pipeline.py`)
- Console server → MQTT blackboard: subscribes and publishes (evidence: `src/console/server.py`)
- Console server → Console state: updates state (evidence: `src/console/server.py`)
- Browser console → Console server: uses console API
- Console state → MQTT blackboard: reads room state (evidence: `src/console/state.py`)
- Topics and schemas → MQTT blackboard: defines topic contracts (evidence: `src/common/mqtt_client.py`)