# homsai-smart-home/homsai-app architecture

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

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

## Overview

##### Main Components
- Presentation (UI) Layer:
- Flutter pages and widgets, which reside under the lib/ui directory.
- Screens such as login, dashboard, add plant, add sensor, scan, and more.
- Auto_route usage for navigation and route generation (e.g., lib/app.router.dart, lib/app.router.gr.dart).

- Business Logic Layer:
- Centers around the BLoC pattern implementation. This layer is found in lib/business and parts of lib/ui (where BLoC classes are defined for each page).
- Covers domain-specific features such as home assistant integration, AI service processing, sensor and light management, and authentication.
- Use of dependency injection via get_it to wire up services.

- Data Access (Persistence and Communication) Layer:
- Represents local storage (using sqflite, Floor, and related DAOs under lib/datastore/local) and remote data interactions.
- Contains remote API interactions using HTTP and WebSocket. Look in lib/datastore/remote for REST and websocket-related repositories.
- Includes data transfer objects (DTOs) for both remote (HTTP/Websocket) and local database communication, based on the organized DTO folders.
- Contains models for home assistant, sensor entities, and other domain-specific data.

- External Services and Libraries:
- External integrations like flutter_web_auth, connectivity_plus, network_info_plus, url_launcher, and third-party packages for animations, charts, and localization.

- Platform-specific Modules:
- Native Android and iOS modules (directories “android” and “ios”) that handle platform-specific configuration, deployment, and integration with native services like splash screens.

##### Relationships and Interactions
- The Business Logic layer communicates with the Data Access tier by calling repository methods to fetch, persist, or update data. Both local (database) and remote (REST/WebSocket) services should be depicted.
- The dependency injection (using get_it) centrally manages the instantiation and wiring between the UI, business, and data layers—this can be shown as an “Infrastructure/DI” component that connects these layers.

##### Architectural Patterns and Key Design Principles
- Use the BLoC pattern as a primary mechanism for state management; clearly indicate that UI components send events which are processed by BLoCs that then react and update the UI.
- Separation of concerns between the presentation, business logic, and data layers.
- Mention the use of dependency injection (get_it) to decouple components.
- Local caching or persistence via SQFLite-related components (using Floor as an ORM-like abstraction).
- Routing and navigation pattern managed by auto_route as a separate navigation module.

##### Relevant Technologies and Frameworks
- Flutter as the base framework.
- BLoC, flutter_bloc, and bloc_concurrency for state management.
- Dependency Injection via get_it.
- Persistence: sqflite, Floor.
- Networking: http and WebSocket components.
- Localization: intl, flutter_localizations, and auto-generated l10n files.
- External utilities for animations (rive), charts (fl_chart), and SVG rendering.

##### Specific Elements
- Clear labels for each component (e.g., “UI Layer – Dashboard Page”, “Business Logic – Home Assistant Service”, “Data Access – REST Repository”, “Local Database – Floor ORM”).
- Annotations to indicate dependency injection handling and routing logic (auto_route).

- Within each layer, further decompose into sub-components (e.g., list out the relevant pages/widgets, BLoC components, and repository modules).
- External interactions (e.g., API endpoints, WebSocket connections, local database) as separate modules that connect into the Data Access layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Flutter UI (lib/ui)"]:::presentation
        LoginPage["Login Page"]:::presentation
        LoginRoutes["Login Routes"]:::presentation
        DashboardPage["Dashboard Page"]:::presentation
        DashboardRoutes["Dashboard Routes"]:::presentation
        AddPlantPage["Add Plant Page"]:::presentation
        AddPlantRoutes["Add Plant Routes"]:::presentation
        AddSensorPage["Add Sensor Page"]:::presentation
        AddSensorRoutes["Add Sensor Routes"]:::presentation
        ScanPage["Scan Page"]:::presentation
        ScanRoutes["Scan Routes"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Business["Business Logic (lib/business)"]:::business
        HomeAssistantService["Home Assistant Service"]:::business
        HomeAssistantScanner["Home Assistant Scanner"]:::business
        AIService["AI Service Integration"]:::business
        ExternalAuth["External Auth Service"]:::business
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        subgraph "Remote Data Access"
            RESTRepo["REST API Repository"]:::dataaccess
            WebSocketRepo["WebSocket Repository"]:::dataaccess
        end
        subgraph "Local Data Access"
            LocalDB["Local Persistence (SQLite/Floor)"]:::dataaccess
            DTO["Data Transfer Objects (DTOs)"]:::dataaccess
        end
    end

    %% Dependency Injection & Routing
    subgraph "Infrastructure"
        AutoRouter["Auto Route Config"]:::infrastructure
        AutoRouterGR["Auto Generated Router"]:::infrastructure
    end

    %% Platform-specific Modules
    subgraph "Platform Modules"
        Android["Android Config"]:::platform
        iOS["iOS Config"]:::platform
    end

    %% External Services Block
    ExternalServices["External Services & APIs"]:::external

    %% Connections between Layers
    UI -->|"dispatches events"| Business
    Business -->|"fetch/persist data"| RESTRepo
    Business -->|"fetch/persist data"| WebSocketRepo
    Business -->|"cache/store data"| LocalDB
    Business -->|"uses DTOs"| DTO

    %% Wiring via Dependency Injection & Routing
    AutoRouter --- UI
    AutoRouter --- Business
    AutoRouterGR --- UI
    AutoRouterGR --- Business

    %% External integrations
    RESTRepo ---|"calls"| ExternalServices
    WebSocketRepo ---|"calls"| ExternalServices

    %% Styling: Vertical separation between layers
    Business --- UI
    RESTRepo --- Business
    LocalDB --- Business

    %% Click Events for Presentation Layer
    click UI "https://github.com/homsai-smart-home/homsai-app/tree/develop/lib/ui"
    click LoginPage "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/login/login.page.dart"
    click LoginRoutes "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/login/login.routes.dart"
    click DashboardPage "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/dashboard/dashboard.page.dart"
    click DashboardRoutes "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/dashboard/dashboard.router.dart"
    click AddPlantPage "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/add_plant/add_plant.page.dart"
    click AddPlantRoutes "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/add_plant/add_plant.router.dart"
    click AddSensorPage "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/add_sensor/add_sensor.page.dart"
    click AddSensorRoutes "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/add_sensor/add_sensor.router.dart"
    click ScanPage "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/scan/home_assistant_scan.page.dart"
    click ScanRoutes "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/ui/pages/scan/home_assistant_scan.router.dart"

    %% Click Events for Business Logic Layer
    click Business "https://github.com/homsai-smart-home/homsai-app/tree/develop/lib/business"
    click HomeAssistantService "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/business/home_assistant/home_assistant.repository.dart"
    click HomeAssistantScanner "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/business/home_assistant_scanner/home_assistant_scanner.repository.dart"
    click AIService "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/business/ai_service/ai_service.repository.dart"
    click ExternalAuth "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/business/flutter_web_auth/flutter_web_auth.repository.dart"

    %% Click Events for Data Access Layer
    click RESTRepo "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/datastore/remote/rest/remote.repository.dart"
    click WebSocketRepo "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/datastore/remote/websocket/home_assistant_websocket.repository.dart"
    click LocalDB "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/datastore/local/app.database.dart"
    click DTO "https://github.com/homsai-smart-home/homsai-app/tree/develop/lib/datastore/DTOs"

    %% Click Events for Dependency Injection & Routing
    click AutoRouter "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/app.router.dart"
    click AutoRouterGR "https://github.com/homsai-smart-home/homsai-app/blob/develop/lib/app.router.gr.dart"

    %% Click Events for Platform Modules
    click Android "https://github.com/homsai-smart-home/homsai-app/tree/develop/android"
    click iOS "https://github.com/homsai-smart-home/homsai-app/tree/develop/ios"

    %% Styles
    classDef presentation fill:#FFEECC,stroke:#D2691E,stroke-width:2px;
    classDef business fill:#CCE5FF,stroke:#003366,stroke-width:2px;
    classDef dataaccess fill:#CCFFCC,stroke:#006400,stroke-width:2px;
    classDef infrastructure fill:#FFD1DC,stroke:#FF1493,stroke-width:2px;
    classDef platform fill:#E0FFFF,stroke:#008B8B,stroke-width:2px;
    classDef external fill:#FFFACD,stroke:#B8860B,stroke-width:2px;
```
