# i8beef/homeautio.mqtt.googlehome architecture

> Architecture diagram of the GitHub repository i8beef/homeautio.mqtt.googlehome, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/i8beef/homeautio.mqtt.googlehome
- Repository: https://github.com/i8beef/homeautio.mqtt.googlehome

## Overview

##### Main Components and Their Roles
- API/Controller Layer:
- Controllers (GoogleDeviceController, GoogleHomeController, GoogleTraitController) that expose endpoints for Google Actions intents.
- This layer handles HTTP requests coming from Google’s fulfillment mechanism.
- Intent Handling and Business Logic:
- IntentHandlers (for SYNC, QUERY, EXECUTE, DISCONNECT) that process incoming intents.
- Model transformation components (found in Models, Request, and Response folders) that convert Google requests/responses into an internal structure.
- Service Layer:
- Services such as GoogleHomeGraphService, MqttService, and TokenCleanupService.
- These services perform the core logic of sending commands to MQTT and interfacing with Google’s home graph via the GoogleHomeGraphClient.
- Authentication and Identity:
- In-process OAuth2 server elements along with the Identity folder components.
- Related UI project (IdentityServerHost.Quickstart.UI) which helps with account linking and user interactions.
- Persistence and Data Management:
- Repositories (for example, GoogleDeviceRepository) managing device metadata and state.
- Integration with External Systems:
- Connection to Google Home (external using the Actions API) on one side.
- MQTT broker as a target for command translation and state reporting.
- Configuration and Schema Definitions:
- Smart-home-schema folder that contains all JSON/YAML definitions for intents, traits, and device types; these are essential to defining how commands and states are represented.
- Testing and CI/CD:
- Though not the focus of production architecture, note that there is a dedicated test project and continuous integration workflows using GitHub Actions, as well as Dockerfiles for deployment (including multi-architecture support).

##### Interactions and Data Flow
- Incoming Google Home Requests:
- The controllers receive the SYNC, QUERY, EXECUTE, and other intent requests.
- Processing and Intent Handling:
- These handlers validate the data, interact with the service layer, and in some cases raise events (e.g., ReportStateEvent or RequestSyncEvent).
- Service Operations:
- The services then call the GoogleHomeGraphClient (for exchanging OAuth tokens or maintaining session state) and the MqttService to publish/subscribe to MQTT topics.
- OAuth2 and Identity Flow:
- A side-chain where an OAuth2 process is handled internally.
- Integration with the Identity components and the separate UI project (IdentityServerHost.Quickstart.UI) that provides the user interface for account linking.
- Data and Domain Model Conversion:
- Outbound Communication:
- Finally, illustrate how processed intents lead to MQTT messages being sent to the home automation system, and how state changes or errors are reported back to Google Home.

##### Architectural Patterns and Technologies
- MVC and Layered Architecture:
- Clear separations: Presentation (controllers/UI), Business Logic (services and intent handlers), Data (models and repositories), and Integration (external systems).
- API Gateway/Bridge Pattern:
- That the project acts as a gateway, translating between HTTP-based Google Actions calls and MQTT messaging.
- Dependency Injection/Modularity:
- Although not explicitly named, demonstrate that the components (especially services and identity) are modular and likely injected via an inversion-of-control container.
- Deployment Considerations:
- Deployment artifacts such as Dockerfiles (for x86, ARM32/ARM64) indicating that the system is containerized and supports multiple architectures.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Systems
    subgraph "External Systems"
        GH["Google Home (Actions API)"]:::external
        MQTT["MQTT Broker"]:::external
    end

    %% API/Controller Layer
    subgraph "API/Controller Layer"
        GDC["GoogleDeviceController"]:::controller
        GHC["GoogleHomeController"]:::controller
        GTC["GoogleTraitController"]:::controller
    end

    %% Intent Handling and Business Logic
    subgraph "Intent Handling and Business Logic"
        SI["SyncIntentHandler"]:::intent
        QI["QueryIntentHandler"]:::intent
        EI["ExecuteIntentHandler"]:::intent
        DI["DisconnectIntentHandler"]:::intent
    end

    %% Model Transformation
    subgraph "Model Transformation"
        MT["Models Transformation"]:::model
    end

    %% Service Layer
    subgraph "Service Layer"
        GHG["GoogleHomeGraphService"]:::service
        MS["MqttService"]:::service
        TCS["TokenCleanupService"]:::service
        GHGClient["GoogleHomeGraphClient"]:::service
    end

    %% Authentication and Identity
    subgraph "Authentication and Identity"
        OAuth["OAuth2 Server"]:::auth
        IdentityUI["Identity UI"]:::auth
    end

    %% Persistence and Data Management
    subgraph "Persistence"
        GDR["GoogleDeviceRepository"]:::persistence
    end

    %% Configuration and Schema Definitions
    subgraph "Configuration & Schema"
        Schema["Smart Home Schema"]:::config
    end

    %% Testing and CI/CD
    subgraph "Testing & CI/CD"
        Tests["Test Suite"]:::testing
        CICD["CI/CD & Docker"]:::testing
    end

    %% Data Flow
    GH -->|"HTTPRequest"| GDC
    %% Controllers to Intent Handlers
    GDC -->|"process_intent"| SI
    GHC -->|"process_intent"| QI
    GTC -->|"process_intent"| EI
    %% (Disconnect handled by DI, triggered as needed)
    
    %% API Controllers for Account Linking
    GHC -->|"account_link"| IdentityUI

    %% Intent Handlers call Model Transformation
    SI --> MT
    QI --> MT
    EI --> MT
    DI --> MT

    %% Model Transformation triggers Service Layer operations
    MT -->|"forward_sync"| GHG
    MT -->|"publish_command"| MS
    MT -->|"token_cleanup"| TCS
    MT -->|"update_graph"| GHGClient

    %% Service Layer Integration
    GHGClient -->|"update_state"| GH
    MS -->|"send_MQTT"| MQTT
    GHG --> GDR
    TCS -->|"cleanup_tokens"| OAuth

    %% Authentication Flow
    OAuth -->|"ui_flow"| IdentityUI

    %% Configuration Usage
    Schema --- MT

    %% Testing and CI/CD interactions (non-runtime)
    CICD --- Tests

    %% Styles
    classDef controller fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef intent fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef model fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef service fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef auth fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef persistence fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef testing fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#000,stroke-width:2px;

    %% Click Events for API/Controller Layer
    click GDC "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/Controllers"
    click GHC "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/Controllers"
    click GTC "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/Controllers"

    %% Click Events for Intent Handlers
    click SI "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/IntentHandlers"
    click QI "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/IntentHandlers"
    click EI "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/IntentHandlers"
    click DI "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/IntentHandlers"

    %% Click Event for Model Transformation
    click MT "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/Models"

    %% Click Events for Service Layer
    click GHG "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/Services"
    click MS "https://github.com/i8beef/homeautio.mqtt.googlehome/blob/master/src/HomeAutio.Mqtt.GoogleHome/Services/MqttService.cs"
    click TCS "https://github.com/i8beef/homeautio.mqtt.googlehome/blob/master/src/HomeAutio.Mqtt.GoogleHome/Services/TokenCleanupService.cs"
    click GHGClient "https://github.com/i8beef/homeautio.mqtt.googlehome/blob/master/src/HomeAutio.Mqtt.GoogleHome/GoogleHomeGraphClient.cs"

    %% Click Events for Authentication and Identity
    click OAuth "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/HomeAutio.Mqtt.GoogleHome/Identity"
    click IdentityUI "https://github.com/i8beef/homeautio.mqtt.googlehome/blob/master/src/IdentityServerHost.Quickstart.UI"

    %% Click Event for Persistence
    click GDR "https://github.com/i8beef/homeautio.mqtt.googlehome/blob/master/src/HomeAutio.Mqtt.GoogleHome/GoogleDeviceRepository.cs"

    %% Click Event for Configuration
    click Schema "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/src/smart-home-schema"

    %% Click Events for Testing and CI/CD
    click Tests "https://github.com/i8beef/homeautio.mqtt.googlehome/blob/master/src/HomeAutio.Mqtt.GoogleHome.Tests"
    click CICD "https://github.com/i8beef/homeautio.mqtt.googlehome/tree/master/.github/workflows"
```
