# rakesh-18112006/smarthome architecture

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

- Interactive diagram: https://gitdiagram.com/rakesh-18112006/smarthome
- Repository: https://github.com/rakesh-18112006/smarthome

## Overview

1. This repository is a multi-part smart home system with three main layers: a Node.js backend API/orchestrator, a React/Vite frontend dashboard, and a separate “stair case” edge subsystem with firmware and a small Python web service.

2. The backend is the central control plane. It exposes feature routes for homes, rooms, devices, sensors, automations, and Google Smart Home integration, and it likely acts as the place where user actions are translated into device commands and persisted configuration.

3. MongoDB is the main persistence boundary. `backend/src/infrastructure/mongodb/db.js` sits below the feature modules, and the entity files (`Device`, `Room`, `Sensor`, `Automation`) suggest the backend stores the home model, device metadata, sensor records, and automation definitions there.

4. Real-time updates are handled separately from REST-style routes. `backend/src/core/websocket/socketService.js` indicates a websocket channel used to push live device/state changes to the UI instead of relying only on polling.

5. MQTT is the primary device messaging bus. The backend has a dedicated MQTT integration (`mqtt.js`, `mqttManager.js`), and the included PDF about firmware/MQTT topics suggests physical devices publish telemetry and subscribe to control topics through this broker-oriented path.

6. Home Assistant is treated as an external interoperability layer. The `homeassistant` integration includes client, discovery, and mapping modules, which implies the backend can register entities with Home Assistant, translate between internal device models and HA entities, and keep discovery/state in sync.

7. Google Smart Home is exposed as a separate integration route. `googleSmartHome.routes.js` suggests the backend also supports cloud voice-assistant style control, likely translating Google requests into the same internal device/automation actions used elsewhere.

8. Automations are a first-class subsystem. `automationEngine.js`, `schedulerService.js`, and the automation routes indicate the backend can evaluate rules and time-based schedules, then trigger device actions or scene-like behaviors automatically.

9. The frontend is a single-page React app built with Vite. Its component set is centered on home management and control surfaces: devices, rooms, sensors, scenes, staircase control, audio/music, and several modals for adding/configuring entities and provisioning devices.

10. The UI is likely organized around a dashboard with a sidebar and entity cards. Components like `DeviceCard`, `SensorCard`, `DeviceStatus`, `Scenes`, and the add/configure modals imply the frontend is the operator console for viewing state and issuing commands back to the backend.

11. The “stair case” folder is a separate embedded/local-control subsystem. It contains Arduino firmware (`stair_case.ino`, `motion_sensors.ino`) plus a Python `led_web_server` with templates and static assets, which suggests local motion-sensor input and LED control are handled outside the main Node app, then integrated into the broader smart home system.

12. Data flow is therefore split by responsibility: user interactions go from React to backend routes, backend writes/reads MongoDB, backend emits live updates over websockets, and backend sends commands or consumes telemetry over MQTT and Home Assistant/Google integration boundaries.

13. The most important architectural boundaries to draw are: frontend vs backend API, backend vs persistent database, backend vs external messaging/integration systems (MQTT, Home Assistant, Google Smart Home), and backend vs edge firmware/web server for staircase automation.

14. Overall, this is not just a UI plus API; it is a home-automation hub that normalizes device/room/sensor/automation state in MongoDB, coordinates event-driven device control via MQTT and websockets, and bridges to third-party ecosystems and embedded staircase hardware.

Main entry points: [`frontend/src/App.jsx`](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/App.jsx) (UI Shell), [`backend/src/modules/homes/smarthome.routes.js`](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/homes/smarthome.routes.js) (Homes), [`backend/src/app.js`](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/app.js) (API Host), [`backend/src/modules/devices/Device.js`](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/devices/Device.js) (Domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["UI Shell<br/>React/Vite app<br/>[App.jsx]"]
  node_frontend_sidebar["Sidebar<br/>navigation<br/>[Sidebar.jsx]"]
  node_frontend_devices["Devices<br/>device UI<br/>[DeviceCard.jsx]"]
  node_frontend_rooms["Rooms<br/>room UI<br/>[AddRoomModal.jsx]"]
  node_frontend_sensors["Sensors<br/>sensor UI<br/>[SensorCard.jsx]"]
  node_frontend_scenes["Scenes<br/>scene UI<br/>[Scenes.jsx]"]
  node_frontend_staircase["Staircase<br/>edge UI<br/>[Staircase.jsx]"]
  node_frontend_music["Music Deck<br/>audio UI<br/>[MusicDeck.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_app["API Host<br/>Node.js server<br/>[app.js]"]
  node_backend_homes["Homes<br/>home API"]
  node_backend_domain["Domain<br/>home model<br/>[Device.js]"]
  node_backend_automations["Automations<br/>rules engine"]
  node_backend_realtime["WebSocket<br/>push channel<br/>[socketService.js]"]
  node_backend_storage[("MongoDB<br/>persistence<br/>[db.js]")]
end

subgraph group_integrations["Integrations"]
  node_integration_mqtt["MQTT<br/>device bus<br/>[mqttManager.js]"]
  node_integration_ha["Home Assistant<br/>ecosystem bridge<br/>[ha-mapper.js]"]
  node_integration_google["Google Smart Home<br/>voice integration"]
end

subgraph group_edge["Staircase Edge"]
  node_edge_fw["Firmware<br/>Arduino<br/>[stair_case.ino]"]
  node_edge_motion["Motion Sensors<br/>Arduino input<br/>[motion_sensors.ino]"]
  node_edge_web["LED Web Server<br/>Python service<br/>[app.py]"]
end

node_frontend_app -->|"uses"| node_frontend_sidebar
node_frontend_app -->|"shows"| node_frontend_devices
node_frontend_app -->|"shows"| node_frontend_rooms
node_frontend_app -->|"shows"| node_frontend_sensors
node_frontend_app -->|"shows"| node_frontend_scenes
node_frontend_app -->|"shows"| node_frontend_staircase
node_frontend_app -->|"shows"| node_frontend_music
node_frontend_devices -->|"api"| node_backend_homes
node_frontend_rooms -->|"api"| node_backend_homes
node_frontend_sensors -->|"api"| node_backend_homes
node_frontend_scenes -->|"api"| node_backend_automations
node_frontend_staircase -.->|"local control"| node_edge_web
node_backend_app -->|"routes"| node_backend_homes
node_backend_app -->|"modules"| node_backend_domain
node_backend_app -->|"modules"| node_backend_automations
node_backend_app -->|"push"| node_backend_realtime
node_backend_app -->|"persistence"| node_backend_storage
node_backend_domain -->|"read/write"| node_backend_storage
node_backend_automations -->|"triggers"| node_backend_domain
node_backend_realtime -->|"updates"| node_frontend_app
node_backend_homes -->|"commands"| node_integration_mqtt
node_backend_domain -->|"telemetry"| node_integration_mqtt
node_backend_domain -->|"sync"| node_integration_ha
node_backend_homes -->|"voice"| node_integration_google
node_backend_automations -->|"actuate"| node_integration_mqtt
node_edge_fw -->|"reads"| node_edge_motion
node_edge_motion -->|"signals"| node_edge_web
node_edge_web -.->|"bridge"| node_integration_mqtt

click node_frontend_app "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/App.jsx"
click node_frontend_sidebar "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/Sidebar.jsx"
click node_frontend_devices "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/DeviceCard.jsx"
click node_frontend_rooms "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/AddRoomModal.jsx"
click node_frontend_sensors "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/SensorCard.jsx"
click node_frontend_scenes "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/Scenes.jsx"
click node_frontend_staircase "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/Staircase.jsx"
click node_frontend_music "https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/MusicDeck.jsx"
click node_backend_app "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/app.js"
click node_backend_homes "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/homes/smarthome.routes.js"
click node_backend_domain "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/devices/Device.js"
click node_backend_automations "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/automations/automationEngine.js"
click node_backend_realtime "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/core/websocket/socketService.js"
click node_backend_storage "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/infrastructure/mongodb/db.js"
click node_integration_mqtt "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/integrations/mqtt/mqttManager.js"
click node_integration_ha "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/integrations/homeassistant/ha-mapper.js"
click node_integration_google "https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/integrations/google/googleSmartHome.routes.js"
click node_edge_fw "https://github.com/rakesh-18112006/smarthome/blob/main/stair case/stair_case.ino"
click node_edge_motion "https://github.com/rakesh-18112006/smarthome/blob/main/stair case/motion_sensors/motion_sensors.ino"
click node_edge_web "https://github.com/rakesh-18112006/smarthome/blob/main/stair case/led_web_server/app.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_app,node_frontend_sidebar,node_frontend_devices,node_frontend_rooms,node_frontend_sensors,node_frontend_scenes,node_frontend_staircase,node_frontend_music toneBlue
class node_backend_app,node_backend_homes,node_backend_domain,node_backend_automations,node_backend_realtime,node_backend_storage toneAmber
class node_integration_mqtt,node_integration_ha,node_integration_google toneMint
class node_edge_fw,node_edge_motion,node_edge_web toneRose
```

## Components

### Frontend

React/Vite operator dashboard and controls

- [UI Shell](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/App.jsx): React/Vite app · Main single-page dashboard entry and layout · `frontend/src/App.jsx`
- [Sidebar](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/Sidebar.jsx): navigation · Primary app navigation and section switching · `frontend/src/components/Sidebar.jsx`
- [Devices](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/DeviceCard.jsx): device UI · Device cards and status controls · `frontend/src/components/DeviceCard.jsx`
- [Rooms](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/AddRoomModal.jsx): room UI · Room management and add-room flow · `frontend/src/components/AddRoomModal.jsx`
- [Sensors](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/SensorCard.jsx): sensor UI · Sensor cards and add-sensor flow · `frontend/src/components/SensorCard.jsx`
- [Scenes](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/Scenes.jsx): scene UI · Scene and automation-facing controls · `frontend/src/components/Scenes.jsx`
- [Staircase](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/Staircase.jsx): edge UI · Staircase control surface and visualization · `frontend/src/components/Staircase.jsx`
- [Music Deck](https://github.com/rakesh-18112006/smarthome/blob/main/frontend/src/components/MusicDeck.jsx): audio UI · Audio control and follow-me music interface · `frontend/src/components/MusicDeck.jsx`

### Backend

Node.js API, orchestration, and domain modules

- [API Host](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/app.js): Node.js server · Backend entrypoint and application composition · `backend/src/app.js`
- [Homes](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/homes/smarthome.routes.js): home API · Home-level controller and routes · `backend/src/modules/homes/smarthome.routes.js`
- [Domain](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/devices/Device.js): home model · Room, device, sensor, and automation modules · `backend/src/modules/devices/Device.js`
- [Automations](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/modules/automations/automationEngine.js): rules engine · Automation rules, scheduler, and triggers · `backend/src/modules/automations/automationEngine.js`
- [WebSocket](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/core/websocket/socketService.js): push channel · Live state updates to connected clients · `backend/src/core/websocket/socketService.js`
- [MongoDB](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/infrastructure/mongodb/db.js): persistence · Database access and storage boundary · `backend/src/infrastructure/mongodb/db.js`

### Integrations

External messaging and ecosystem bridges

- [MQTT](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/integrations/mqtt/mqttManager.js): device bus · Broker integration for telemetry and commands · `backend/src/integrations/mqtt/mqttManager.js`
- [Home Assistant](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/integrations/homeassistant/ha-mapper.js): ecosystem bridge · Client, discovery, and entity mapping bridge · `backend/src/integrations/homeassistant/ha-mapper.js`
- [Google Smart Home](https://github.com/rakesh-18112006/smarthome/blob/main/backend/src/integrations/google/googleSmartHome.routes.js): voice integration · Cloud smart-home request route · `backend/src/integrations/google/googleSmartHome.routes.js`

### Staircase Edge

Embedded firmware and local Python control service

- [Firmware](https://github.com/rakesh-18112006/smarthome/blob/HEAD/stair%20case/stair_case.ino): Arduino · Staircase firmware for motion and LED control · `stair case/stair_case.ino`
- [Motion Sensors](https://github.com/rakesh-18112006/smarthome/blob/HEAD/stair%20case/motion_sensors/motion_sensors.ino): Arduino input · Local motion sensor firmware module · `stair case/motion_sensors/motion_sensors.ino`
- [LED Web Server](https://github.com/rakesh-18112006/smarthome/blob/HEAD/stair%20case/led_web_server/app.py): Python service · Local web UI and control service for staircase LEDs · `stair case/led_web_server/app.py`

## Connections

- UI Shell → Sidebar: uses · App shell renders navigation
- UI Shell → Devices: shows · Dashboard includes device controls
- UI Shell → Rooms: shows · Dashboard includes room management
- UI Shell → Sensors: shows · Dashboard includes sensor views
- UI Shell → Scenes: shows · Dashboard includes scene controls
- UI Shell → Staircase: shows · Dashboard includes staircase controls
- UI Shell → Music Deck: shows · Dashboard includes audio controls
- Devices → Homes: api · Device actions and state flow through backend routes
- Rooms → Homes: api · Room management calls backend routes
- Sensors → Homes: api · Sensor management calls backend routes
- Scenes → Automations: api · Scene and automation UI drive backend rules
- Staircase → LED Web Server: local control · Staircase UI may coordinate with the local web service
- API Host → Homes: routes · Application mounts home-level API
- API Host → Domain: modules · Application composes core domain modules
- API Host → Automations: modules · Application composes automation subsystem
- API Host → WebSocket: push · Application exposes websocket updates
- API Host → MongoDB: persistence · Application uses MongoDB boundary
- Domain → MongoDB: read/write · Domain state is persisted in MongoDB
- Automations → Domain: triggers · Automation engine acts on devices, rooms, and sensors
- WebSocket → UI Shell: updates · Live state changes are pushed to the UI
- Homes → MQTT: commands · Home actions can be translated to MQTT device commands
- Domain → MQTT: telemetry · Device state and sensor updates flow over MQTT
- Domain → Home Assistant: sync · Internal entities are mapped to Home Assistant
- Homes → Google Smart Home: voice · Smart-home requests arrive through Google integration
- Automations → MQTT: actuate · Automations can emit device commands on MQTT
- Firmware → Motion Sensors: reads · Firmware consumes motion sensing input
- Motion Sensors → LED Web Server: signals · Local sensor events can be surfaced to the Python service
- LED Web Server → MQTT: bridge · Edge service can bridge staircase events into the main device bus
