# johnnysgithubaccount/smart-home-virtual-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/johnnysgithubaccount/smart-home-virtual-assistant
- Repository: https://github.com/johnnysgithubaccount/smart-home-virtual-assistant

## Overview

##### Project Type and Purpose
- From the README and file tree, **Marvin** is a voice-activated, multi-agent smart-home assistant. It’s a full-stack, graph-based AI system that listens for a wake word, classifies intent via SLMs, routes to chat or device-control agents, and persists context in a graph database. It also includes a minimal web backend for optional UI or API integrations and low-level hardware control for ESP32 devices.

##### File Structure
Top-level files/directories:
- Home Assistant/ – main Python package
– components/ – core modules (LLM wrappers, scheduler, long-term memory, knowledge-graph, logging, tools)
- hardware/ – device-control adapters & ESP32 C programs
- voice/ – speech-to-text, text-to-speech, wake-word detection
- llm.py, knowledge_graph.py, scheduler.py, nodes.py, tools.py, utils.py
– init_graph/ – setup scripts for LangGraph workflows (autonomous.py, instance.py)
– main.py – entry point
– deploy.py – deployment orchestration
– configs.json – external service configs
– web/ – lightweight backend (backend.py) for UI or REST APIs
– test/ – unit tests
- README.md, requirements.txt, .gitignore, etc.

##### README for Architectural Insights
- Components: SLMs served by Ollama, LangGraph for orchestration, Neo4j for memory, Firebase for real-time device control, HuggingFace wake-word engine, ESP32 firmware.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External I/O
    Mic["Microphone"]:::external
    Speaker["Speaker"]:::external

    %% Voice Interface
    subgraph "Voice Interface"
        WWD["Wake-Word Detection"]:::voice
        STT["Speech-to-Text"]:::voice
        TTS["Text-to-Speech"]:::voice
    end

    %% Orchestration Layer
    subgraph "Orchestration"
        Scheduler["Scheduler"]:::orchestrator
        Intent["Intent Classifier Node"]:::orchestrator
        Chat["Chat Agent Node"]:::orchestrator
        Tool["Tool Agent Node"]:::orchestrator
        UserCheck["User-Checking Node"]:::orchestrator
        LTMNode["Long-Term Memory Node"]:::orchestrator
        InitAuto["Autonomous Init"]:::orchestrator
        InitInst["Instance Init"]:::orchestrator
    end

    %% Model Serving
    subgraph "Model Serving"
        Ollama["Ollama Host (SLMs)"]:::model
    end

    %% Persistence Layer
    subgraph "Persistence"
        Neo4j["Neo4j Graph DB"]:::persistence
        Firebase["Firebase RTDB"]:::persistence
    end

    %% Hardware Control
    subgraph "Hardware"
        HWAdapter["Hardware Adapter"]:::hardware
        ESP32["ESP32 Firmware"]:::hardware
    end

    %% Web/API Layer
    subgraph "Web/API"
        WebBackend["Web Backend (REST/UI)"]:::web
    end

    %% Logging & Utilities
    subgraph "Logging & Utilities"
        Logger["Logger"]:::util
    end

    %% Data Flows
    Mic --> WWD
    WWD --> STT
    STT --> Intent
    Intent -->|chat| Chat
    Intent -->|tool| Tool
    Chat --> TTS
    TTS --> Speaker
    Tool --> HWAdapter
    HWAdapter --> Firebase
    Firebase --> ESP32
    Chat --> UserCheck
    Tool --> UserCheck
    UserCheck -->|if no| LTMNode
    LTMNode --> Neo4j

    %% Orchestrator interactions
    Scheduler --> Intent
    Scheduler --> Chat
    Scheduler --> Tool
    Scheduler --> UserCheck
    Ollama --> Intent
    Ollama --> Chat
    Ollama --> Tool
    Intent --> Logger
    Chat --> Logger
    Tool --> Logger
    UserCheck --> Logger
    LTMNode --> Logger

    WebBackend --> Intent
    WebBackend --> Neo4j

    %% Click Events
    click WWD "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/voice/wake_word_detection.py"
    click STT "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/voice/speech_to_text.py"
    click TTS "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/voice/text_to_speech.py"
    click Intent "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/nodes.py"
    click Scheduler "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/scheduler.py"
    click InitAuto "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/init_graph/autonomous.py"
    click InitInst "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/init_graph/instance.py"
    click Ollama "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/llm.py"
    click Neo4j "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/knowledge_graph.py"
    click LTMNode "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/longterm_memory.py"
    click HWAdapter "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/hardware/bedroom.py"
    click ESP32 "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/tree/main/Home Assistant/components/hardware/esp32_C_programming/"
    click WebBackend "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/web/backend.py"
    click Logger "https://github.com/johnnysgithubaccount/smart-home-virtual-assistant/blob/main/Home Assistant/components/logger.py"

    %% Styling
    classDef external fill:#dddddd,stroke:#888888,stroke-width:1px
    classDef voice fill:#bbdefb,stroke:#0b5394,stroke-width:2px
    classDef orchestrator fill:#c8e6c9,stroke:#38755b,stroke-width:2px
    classDef model fill:#ffe0b2,stroke:#a64d00,stroke-width:2px
    classDef persistence fill:#e1bee7,stroke:#5e3568,stroke-width:2px
    classDef hardware fill:#fff9c4,stroke:#a28700,stroke-width:2px
    classDef web fill:#e0e0e0,stroke:#5f5f5f,stroke-width:2px
    classDef util fill:#f5f5f5,stroke:#666666,stroke-width:1px
```
