# motchiecmeowber/smart-home architecture

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

- Interactive diagram: https://gitdiagram.com/motchiecmeowber/smart-home
- Repository: https://github.com/motchiecmeowber/smart-home

## Overview

Smart Home is a web-based IoT monitoring and control system. Users authenticate, manage devices and locations, view live environmental readings and history, control actuators, create schedules, and submit service requests; administrators also manage devices, users, and requests. The client routes role-specific screens to backend APIs, while the server coordinates persistence and ThingsBoard connectivity. The graph preserves documented telemetry, emergency alerts, profile/settings, and reporting capabilities. Some client-to-endpoint and live-event wiring is not shown in the excerpts, so those relationships are omitted or marked unverified.

Main entry points: [`app/server/src/app.ts`](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/app.ts) (HTTP and WS server), [`app/client/src/App.tsx`](https://github.com/motchiecmeowber/smart-home/blob/main/app/client/src/App.tsx) (Route and role app), [`app/server/src/modules/hardware/hardware.controller.ts`](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/hardware.controller.ts) (Hardware API), [`app/server/src/modules/hardware/actuator.service.ts`](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/actuator.service.ts) (Actuator service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Route and role app<br/>[App.tsx]"]
  node_authui["Login and registration"]
  node_customerui["Customer screens"]
  node_adminui["Admin screens"]
  node_clientauth["Auth state and API<br/>[authStore.ts]"]
  node_clientdevice["Device API<br/>[deviceApi.ts]"]
end

subgraph group_identity["Identity and access"]
  node_identityroutes["Identity routes<br/>[identity.routes.ts]"]
  node_identitycontroller["Identity controller"]
  node_identityservice["Identity service"]
end

subgraph group_devices["IoT device domain"]
  node_hardware["Hardware API"]
  node_deviceservice["Device service<br/>[device.service.ts]"]
  node_actuator["Actuator service"]
  node_sensors["Sensor service<br/>[sensor.service.ts]"]
end

subgraph group_operations["Home operations"]
  node_automation["Schedule automation"]
  node_requests["Service requests"]
  node_interaction["Notifications and control"]
  node_locations["Home locations"]
  node_analytics["Environmental analytics"]
end

subgraph group_platform["Server platform"]
  node_server["HTTP and WS server<br/>[app.ts]"]
  node_database[("Postgres database")]
  node_redis[("Redis")]
  node_clientws["Client WebSocket<br/>[client-ws.ts]"]
  node_tbws["ThingsBoard WebSocket<br/>[tb-ws.ts]"]
end

node_user(("Home user"))
node_thingsboard{{"ThingsBoard Cloud"}}
node_iot{{"Sensors and actuators"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_customerui
node_app -->|"routes to"| node_adminui
node_app -->|"restores session"| node_clientauth
node_clientauth -.->|"calls auth API"| node_identityroutes
node_customerui -.->|"uses device API"| node_clientdevice
node_app -->|"HTTP and WS"| node_server
node_server -->|"mounts routes"| node_identityroutes
node_identityroutes -->|"dispatches"| node_identitycontroller
node_identitycontroller -->|"calls"| node_identityservice
node_identityservice -.->|"persists identity"| node_database
node_server -->|"mounts routes"| node_hardware
node_hardware -->|"calls"| node_deviceservice
node_hardware -->|"controls actuator"| node_actuator
node_hardware -->|"reads sensor service"| node_sensors
node_deviceservice -.->|"syncs devices"| node_thingsboard
node_deviceservice -.->|"persists devices"| node_database
node_actuator -.->|"sends commands"| node_thingsboard
node_thingsboard -->|"coordinates telemetry"| node_iot
node_server -->|"initializes scheduler"| node_automation
node_automation -->|"controls scheduled devices"| node_actuator
node_automation -.->|"stores schedules"| node_database
node_server -->|"mounts request routes"| node_requests
node_requests -.->|"stores requests"| node_database
node_server -->|"mounts interaction routes"| node_interaction
node_interaction -->|"controls actuator"| node_actuator
node_interaction -.->|"stores interactions"| node_database
node_server -->|"mounts location routes"| node_locations
node_server -->|"mounts analytics routes"| node_analytics
node_server -->|"connects at startup"| node_redis
node_server -->|"initializes WS"| node_clientws
node_server -->|"connects listener"| node_tbws
node_tbws -.->|"receives telemetry"| node_thingsboard
node_clientws -.->|"streams live data"| node_customerui

click node_app "https://github.com/motchiecmeowber/smart-home/blob/main/app/client/src/App.tsx"
click node_authui "https://github.com/motchiecmeowber/smart-home/tree/main/app/client/src/pages/auth"
click node_customerui "https://github.com/motchiecmeowber/smart-home/tree/main/app/client/src/pages/customer"
click node_adminui "https://github.com/motchiecmeowber/smart-home/tree/main/app/client/src/pages/admin"
click node_clientauth "https://github.com/motchiecmeowber/smart-home/blob/main/app/client/src/lib/authStore.ts"
click node_clientdevice "https://github.com/motchiecmeowber/smart-home/blob/main/app/client/src/lib/deviceApi.ts"
click node_server "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/app.ts"
click node_identityroutes "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/identity/identity.routes.ts"
click node_identitycontroller "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/identity/identity.controller.ts"
click node_identityservice "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/identity/identity.service.ts"
click node_hardware "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/hardware.controller.ts"
click node_deviceservice "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/device.service.ts"
click node_actuator "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/actuator.service.ts"
click node_sensors "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/sensor.service.ts"
click node_automation "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/automation/automation.service.ts"
click node_requests "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/request/request.controller.ts"
click node_interaction "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/interaction/interaction.service.ts"
click node_locations "https://github.com/motchiecmeowber/smart-home/tree/main/app/server/src/modules/location"
click node_analytics "https://github.com/motchiecmeowber/smart-home/tree/main/app/server/src/modules/analytics"
click node_clientws "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/lib/ws/client-ws.ts"
click node_tbws "https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/lib/ws/tb-ws.ts"

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_app,node_authui,node_customerui,node_adminui,node_clientauth,node_clientdevice,node_user toneBlue
class node_identityroutes,node_identitycontroller,node_identityservice toneAmber
class node_hardware,node_deviceservice,node_actuator,node_sensors toneMint
class node_automation,node_requests,node_interaction,node_locations,node_analytics toneRose
class node_server,node_database,node_redis,node_clientws,node_tbws,node_thingsboard,node_iot toneIndigo
```

## Components

### Web client

- [Route and role app](https://github.com/motchiecmeowber/smart-home/blob/main/app/client/src/App.tsx): `app/client/src/App.tsx`
- [Login and registration](https://github.com/motchiecmeowber/smart-home/tree/main/app/client/src/pages/auth): `app/client/src/pages/auth`
- [Customer screens](https://github.com/motchiecmeowber/smart-home/tree/main/app/client/src/pages/customer): `app/client/src/pages/customer`
- [Admin screens](https://github.com/motchiecmeowber/smart-home/tree/main/app/client/src/pages/admin): `app/client/src/pages/admin`
- [Auth state and API](https://github.com/motchiecmeowber/smart-home/blob/main/app/client/src/lib/authStore.ts): `app/client/src/lib/authStore.ts`
- [Device API](https://github.com/motchiecmeowber/smart-home/blob/main/app/client/src/lib/deviceApi.ts): `app/client/src/lib/deviceApi.ts`

### Identity and access

- [Identity routes](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/identity/identity.routes.ts): `app/server/src/modules/identity/identity.routes.ts`
- [Identity controller](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/identity/identity.controller.ts): `app/server/src/modules/identity/identity.controller.ts`
- [Identity service](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/identity/identity.service.ts): `app/server/src/modules/identity/identity.service.ts`

### IoT device domain

- [Hardware API](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/hardware.controller.ts): `app/server/src/modules/hardware/hardware.controller.ts`
- [Device service](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/device.service.ts): `app/server/src/modules/hardware/device.service.ts`
- [Actuator service](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/actuator.service.ts): `app/server/src/modules/hardware/actuator.service.ts`
- [Sensor service](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/hardware/sensor.service.ts): `app/server/src/modules/hardware/sensor.service.ts`

### Home operations

- [Schedule automation](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/automation/automation.service.ts): `app/server/src/modules/automation/automation.service.ts`
- [Service requests](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/request/request.controller.ts): `app/server/src/modules/request/request.controller.ts`
- [Notifications and control](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/modules/interaction/interaction.service.ts): `app/server/src/modules/interaction/interaction.service.ts`
- [Home locations](https://github.com/motchiecmeowber/smart-home/tree/main/app/server/src/modules/location): `app/server/src/modules/location`
- [Environmental analytics](https://github.com/motchiecmeowber/smart-home/tree/main/app/server/src/modules/analytics): `app/server/src/modules/analytics`

### Server platform

- [HTTP and WS server](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/app.ts): `app/server/src/app.ts`
- **Postgres database**
- **Redis**
- [Client WebSocket](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/lib/ws/client-ws.ts): `app/server/src/lib/ws/client-ws.ts`
- [ThingsBoard WebSocket](https://github.com/motchiecmeowber/smart-home/blob/main/app/server/src/lib/ws/tb-ws.ts): `app/server/src/lib/ws/tb-ws.ts`

### Other components

- **Home user**
- **ThingsBoard Cloud**
- **Sensors and actuators**

## Connections

- Home user → Route and role app: uses (evidence: `app/client/src/App.tsx`)
- Route and role app → Login and registration: routes to (evidence: `app/client/src/App.tsx`)
- Route and role app → Customer screens: routes to (evidence: `app/client/src/App.tsx`)
- Route and role app → Admin screens: routes to (evidence: `app/client/src/App.tsx`)
- Route and role app → Auth state and API: restores session (evidence: `app/client/src/App.tsx`)
- Auth state and API → Identity routes: calls auth API
- Customer screens → Device API: uses device API
- Route and role app → HTTP and WS server: HTTP and WS (evidence: `README.md`)
- HTTP and WS server → Identity routes: mounts routes (evidence: `app/server/src/app.ts`)
- Identity routes → Identity controller: dispatches (evidence: `app/server/src/modules/identity/identity.routes.ts`)
- Identity controller → Identity service: calls (evidence: `app/server/src/modules/identity/identity.controller.ts`)
- Identity service → Postgres database: persists identity
- HTTP and WS server → Hardware API: mounts routes (evidence: `app/server/src/app.ts`)
- Hardware API → Device service: calls (evidence: `app/server/src/modules/hardware/hardware.controller.ts`)
- Hardware API → Actuator service: controls actuator (evidence: `app/server/src/modules/hardware/hardware.controller.ts`)
- Hardware API → Sensor service: reads sensor service (evidence: `app/server/src/modules/hardware/hardware.controller.ts`)
- Device service → ThingsBoard Cloud: syncs devices
- Device service → Postgres database: persists devices
- Actuator service → ThingsBoard Cloud: sends commands (evidence: `README.md`)
- ThingsBoard Cloud → Sensors and actuators: coordinates telemetry (evidence: `README.md`)
- HTTP and WS server → Schedule automation: initializes scheduler (evidence: `app/server/src/app.ts`)
- Schedule automation → Actuator service: controls scheduled devices (evidence: `app/server/src/modules/automation/automation.service.ts`)
- Schedule automation → Postgres database: stores schedules
- HTTP and WS server → Service requests: mounts request routes (evidence: `app/server/src/app.ts`)
- Service requests → Postgres database: stores requests
- HTTP and WS server → Notifications and control: mounts interaction routes (evidence: `app/server/src/app.ts`)
- Notifications and control → Actuator service: controls actuator (evidence: `app/server/src/modules/interaction/interaction.service.ts`)
- Notifications and control → Postgres database: stores interactions
- HTTP and WS server → Home locations: mounts location routes (evidence: `app/server/src/app.ts`)
- HTTP and WS server → Environmental analytics: mounts analytics routes (evidence: `app/server/src/app.ts`)
- HTTP and WS server → Redis: connects at startup (evidence: `app/server/src/app.ts`)
- HTTP and WS server → Client WebSocket: initializes WS (evidence: `app/server/src/app.ts`)
- HTTP and WS server → ThingsBoard WebSocket: connects listener (evidence: `app/server/src/app.ts`)
- ThingsBoard WebSocket → ThingsBoard Cloud: receives telemetry (evidence: `README.md`)
- Client WebSocket → Customer screens: streams live data
