# thailearncoding/smarthousebot architecture

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

- Interactive diagram: https://gitdiagram.com/thailearncoding/smarthousebot
- Repository: https://github.com/thailearncoding/smarthousebot

## Overview

SmartHouseBot is a local-first smart-home dashboard and Vietnamese voice assistant. Users issue device commands or voice/text requests; the backend transcribes audio, resolves and validates intent, performs device or sensor work, then generates and streams a response with optional speech audio. The UI also exposes device status, telemetry history, health, and audit logs. The README documents the major product stages and interfaces; several backend router, voice-pipeline, and telemetry details are unsampled, so those links follow documented behavior and the repository layout.

Main entry points: [`backend/app/services/voice_service.py`](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/voice_service.py) (Voice orchestration), [`backend/app/services/coreiot_service.py`](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/coreiot_service.py) (Device and telemetry service), [`backend/app/main.py`](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/db/repository.py`](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/db/repository.py) (Storage repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard UI"]
  node_app["App routes<br/>[App.jsx]"]
  node_dashboard_store["Dashboard state"]
  node_dashboard_api["Dashboard API<br/>[dashboardApi.js]"]
  node_voice_store["Voice state"]
  node_voice_api["Voice API<br/>[voiceApi.js]"]
end

subgraph group_voice["Voice Assistant"]
  node_voice_router["Voice endpoints<br/>[voice.py]"]
  node_voice_controller["Voice controller"]
  node_voice_service["Voice orchestration<br/>[voice_service.py]"]
  node_whisper["Speech recognition<br/>[whisper_service.py]"]
  node_intent["Intent parsing<br/>[intent_service.py]"]
  node_llm["LLM generation<br/>[llm_service.py]"]
  node_tts["Speech synthesis<br/>[tts_service.py]"]
end

subgraph group_devices["Devices and Telemetry"]
  node_main["FastAPI app<br/>[main.py]"]
  node_device_router["Device endpoints<br/>[devices.py]"]
  node_device_controller["Device controller"]
  node_coreiot_service["Device and telemetry service<br/>[coreiot_service.py]"]
  node_coreiot_client["CoreIoT client<br/>[coreiot_client.py]"]
  node_telemetry_router["Telemetry endpoints<br/>[telemetry.py]"]
  node_sampler["Telemetry sampler"]
end

subgraph group_records["Audit and Storage"]
  node_audit_router["Audit endpoints<br/>[audit.py]"]
  node_audit_controller["Audit controller"]
  node_repository["Storage repository<br/>[repository.py]"]
  node_database[("SQLite database<br/>[database.py]")]
end

node_user(("Home user"))
node_ollama["Ollama LLM"]
node_phowhisper["PhoWhisper"]
node_piper["Piper TTS"]
node_coreiot["CoreIoT platform"]

node_user -->|"uses"| node_app
node_app -->|"opens voice"| node_voice_store
node_app -->|"opens dashboard"| node_dashboard_store
node_voice_store -->|"transcribes audio"| node_voice_api
node_voice_store -->|"streams text"| node_voice_router
node_dashboard_store -->|"requests data"| node_dashboard_api
node_main -->|"mounts routes"| node_voice_router
node_main -->|"mounts routes"| node_device_router
node_main -->|"mounts routes"| node_telemetry_router
node_main -->|"mounts routes"| node_audit_router
node_voice_router -->|"dispatches"| node_voice_controller
node_voice_controller -->|"processes turn"| node_voice_service
node_voice_service -->|"transcribes audio"| node_whisper
node_voice_service -->|"resolves intent"| node_intent
node_voice_service -->|"generates response"| node_llm
node_voice_service -->|"synthesizes speech"| node_tts
node_whisper -->|"transcribes with"| node_phowhisper
node_llm -.->|"requests generation"| node_ollama
node_tts -.->|"synthesizes with"| node_piper
node_voice_service -->|"executes device intent"| node_device_controller
node_voice_service -->|"records interaction"| node_repository
node_device_router -->|"dispatches"| node_device_controller
node_device_controller -->|"controls device"| node_coreiot_service
node_telemetry_router -->|"requests readings"| node_coreiot_service
node_sampler -->|"collects snapshots"| node_coreiot_service
node_coreiot_service -->|"fetches or commands"| node_coreiot_client
node_coreiot_client -->|"RPC and telemetry"| node_coreiot
node_coreiot_service -->|"persists snapshots"| node_repository
node_audit_router -->|"dispatches"| node_audit_controller
node_audit_controller -->|"reads audit logs"| node_repository
node_repository -->|"reads and writes"| node_database

click node_app "https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/App.jsx"
click node_dashboard_store "https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/store/useDashboardStore.js"
click node_dashboard_api "https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/services/dashboardApi.js"
click node_voice_store "https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/store/useVoiceAssistantStore.js"
click node_voice_api "https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/services/voiceApi.js"
click node_main "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/main.py"
click node_voice_router "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/voice.py"
click node_voice_controller "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/controllers/voice_controller.py"
click node_voice_service "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/voice_service.py"
click node_whisper "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/whisper_service.py"
click node_intent "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/intent_service.py"
click node_llm "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/llm_service.py"
click node_tts "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/tts_service.py"
click node_device_router "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/devices.py"
click node_device_controller "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/controllers/device_controller.py"
click node_coreiot_service "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/coreiot_service.py"
click node_coreiot_client "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/clients/coreiot_client.py"
click node_telemetry_router "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/telemetry.py"
click node_sampler "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/telemetry_sampler.py"
click node_audit_router "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/audit.py"
click node_audit_controller "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/controllers/audit_controller.py"
click node_repository "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/db/repository.py"
click node_database "https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/db/database.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_app,node_dashboard_store,node_dashboard_api,node_voice_store,node_voice_api,node_user toneBlue
class node_voice_router,node_voice_controller,node_voice_service,node_whisper,node_intent,node_llm,node_tts toneAmber
class node_main,node_device_router,node_device_controller,node_coreiot_service,node_coreiot_client,node_telemetry_router,node_sampler toneMint
class node_audit_router,node_audit_controller,node_repository,node_database toneRose
class node_ollama,node_phowhisper,node_piper,node_coreiot toneIndigo
```

## Components

### Dashboard UI

- [App routes](https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dashboard state](https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/store/useDashboardStore.js): `frontend/src/store/useDashboardStore.js`
- [Dashboard API](https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/services/dashboardApi.js): `frontend/src/services/dashboardApi.js`
- [Voice state](https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/store/useVoiceAssistantStore.js): `frontend/src/store/useVoiceAssistantStore.js`
- [Voice API](https://github.com/thailearncoding/smarthousebot/blob/main/frontend/src/services/voiceApi.js): `frontend/src/services/voiceApi.js`

### Voice Assistant

- [Voice endpoints](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/voice.py): `backend/app/routers/voice.py`
- [Voice controller](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/controllers/voice_controller.py): `backend/app/controllers/voice_controller.py`
- [Voice orchestration](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/voice_service.py): `backend/app/services/voice_service.py`
- [Speech recognition](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/whisper_service.py): `backend/app/services/whisper_service.py`
- [Intent parsing](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/intent_service.py): `backend/app/services/intent_service.py`
- [LLM generation](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`
- [Speech synthesis](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/tts_service.py): `backend/app/services/tts_service.py`

### Devices and Telemetry

- [FastAPI app](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/main.py): `backend/app/main.py`
- [Device endpoints](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/devices.py): `backend/app/routers/devices.py`
- [Device controller](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/controllers/device_controller.py): `backend/app/controllers/device_controller.py`
- [Device and telemetry service](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/coreiot_service.py): `backend/app/services/coreiot_service.py`
- [CoreIoT client](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/clients/coreiot_client.py): `backend/app/clients/coreiot_client.py`
- [Telemetry endpoints](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/telemetry.py): `backend/app/routers/telemetry.py`
- [Telemetry sampler](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/services/telemetry_sampler.py): `backend/app/services/telemetry_sampler.py`

### Audit and Storage

- [Audit endpoints](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/routers/audit.py): `backend/app/routers/audit.py`
- [Audit controller](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/controllers/audit_controller.py): `backend/app/controllers/audit_controller.py`
- [Storage repository](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/db/repository.py): `backend/app/db/repository.py`
- [SQLite database](https://github.com/thailearncoding/smarthousebot/blob/main/backend/app/db/database.py): `backend/app/db/database.py`

### Other components

- **Home user**
- **Ollama LLM**
- **PhoWhisper**
- **Piper TTS**
- **CoreIoT platform**

## Connections

- Home user → App routes: uses
- App routes → Voice state: opens voice
- App routes → Dashboard state: opens dashboard
- Voice state → Voice API: transcribes audio
- Voice state → Voice endpoints: streams text
- Dashboard state → Dashboard API: requests data
- FastAPI app → Voice endpoints: mounts routes
- FastAPI app → Device endpoints: mounts routes
- FastAPI app → Telemetry endpoints: mounts routes
- FastAPI app → Audit endpoints: mounts routes
- Voice endpoints → Voice controller: dispatches
- Voice controller → Voice orchestration: processes turn
- Voice orchestration → Speech recognition: transcribes audio
- Voice orchestration → Intent parsing: resolves intent
- Voice orchestration → LLM generation: generates response
- Voice orchestration → Speech synthesis: synthesizes speech
- Speech recognition → PhoWhisper: transcribes with
- LLM generation → Ollama LLM: requests generation
- Speech synthesis → Piper TTS: synthesizes with
- Voice orchestration → Device controller: executes device intent
- Voice orchestration → Storage repository: records interaction
- Device endpoints → Device controller: dispatches
- Device controller → Device and telemetry service: controls device
- Telemetry endpoints → Device and telemetry service: requests readings
- Telemetry sampler → Device and telemetry service: collects snapshots
- Device and telemetry service → CoreIoT client: fetches or commands
- CoreIoT client → CoreIoT platform: RPC and telemetry
- Device and telemetry service → Storage repository: persists snapshots
- Audit endpoints → Audit controller: dispatches
- Audit controller → Storage repository: reads audit logs
- Storage repository → SQLite database: reads and writes