# pavelanni/geekhouse architecture

> Architecture diagram of the GitHub repository pavelanni/geekhouse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pavelanni/geekhouse
- Repository: https://github.com/pavelanni/geekhouse

## Overview

Key Components to Include:

##### Hardware Layer
- Supported sensors (ADC and Digital) and actuators (LEDs, motors, buzzers)
- Components to their respective GPIO pins

##### Software Stack
- MicroPython Runtime Environment
- Microdot Web Framework
- Custom Server Implementation
- Configuration Management System

##### Application Architecture
Create three main sections:

a. Core Server Components:
- Main Application (src/server/main.py)
- Server Handler (src/server/server.py)
- Route Definitions (src/server/routes.py)
- Configuration Handler (src/server/config_handler.py)
- Utility Functions (src/server/utils.py)

b. Device Management:
- Sensor Management
- LED Control
- Calibration System

c. External Interface:
- HATEOAS REST API
- WiFi Connection

##### Use a layered architecture approach
- [Client Layer]
- ↕ HTTP/REST
- [API Layer (HATEOAS)]
- ↕
- [Application Layer]
- ↕
- [Hardware Abstraction Layer]
- ↕
- [Physical Hardware Layer]

##### Data Flow Indicators

Special Considerations:

##### Configuration Management
- Relationship between TOML config files and runtime JSON
- Deployment process flow
- Calibration parameter handling

##### API Structure
- HATEOAS links between endpoints
- Filtering capabilities for sensors and LEDs
- Supported HTTP methods

##### Sensor Integration
- ADC conversion flow
- Calibration formula processing
- Demonstrate sensor data paths

##### Device Management
- Device discovery
- State management for actuators
- Error handling paths

Implementation Details:

##### Use standardized symbols
- ⬡ : Microcontroller
- ⬢ : Sensors/Actuators
- □ : Software Components
- ○ : API Endpoints
- ⟳ : Processing Units

- Sensor calibration flow
- Configuration deployment process
- API interaction patterns

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Client1[Web Client]
        Client2[IoT Device]
    end

    subgraph "API Layer"
        API["/api"]:::api
        API_Sensors["/api/sensors"]:::api
        API_LEDs["/api/leds"]:::api
        API_Config["/api/config"]:::api
        HATEOAS[HATEOAS Links]:::api
    end

    subgraph "Application Layer"
        Main["Main Application"]:::core
        Server["Server Handler"]:::core
        Routes["Route Definitions"]:::core
        ConfigHandler["Configuration Handler"]:::config
        Utils["Utility Functions"]:::core
        LLM["LLM Integration"]:::core
    end

    subgraph "Configuration Management"
        TOML["TOML Config"]:::config
        JSON["Runtime JSON"]:::config
        Deploy["Deployment Script"]:::config
        Converter["Config Converter"]:::config
    end

    subgraph "Hardware Layer"
        PicoW[("Raspberry Pi Pico W")]:::hw
        subgraph "Sensors"
            ADC["ADC Sensors"]:::hw
            Digital["Digital Sensors"]:::hw
            LCD["LCD Display"]:::hw
        end
        subgraph "Actuators"
            LED["LEDs"]:::hw
            Motors["Motors"]:::hw
            Buzzer["Buzzer"]:::hw
        end
    end

    %% Connections
    Client1 & Client2 --> API
    API --> API_Sensors & API_LEDs & API_Config
    API_Sensors & API_LEDs & API_Config --> HATEOAS

    HATEOAS --> Routes
    Routes --> Server
    Server --> Main
    Main --> ConfigHandler
    Main --> Utils
    Main --> LLM

    TOML --> Converter
    Converter --> JSON
    Deploy --> JSON
    JSON --> ConfigHandler

    ConfigHandler --> PicoW
    Server --> PicoW
    PicoW --> ADC & Digital & LCD & LED & Motors & Buzzer

    %% Styles
    classDef api fill:#6495ED,stroke:#333,stroke-width:2px
    classDef core fill:#FFA500,stroke:#333,stroke-width:2px
    classDef config fill:#FFD700,stroke:#333,stroke-width:2px
    classDef hw fill:#90EE90,stroke:#333,stroke-width:2px

    %% Click Events
    click Main "https://github.com/pavelanni/geekhouse/blob/main/src/server/main.py"
    click Server "https://github.com/pavelanni/geekhouse/blob/main/src/server/server.py"
    click Routes "https://github.com/pavelanni/geekhouse/blob/main/src/server/routes.py"
    click ConfigHandler "https://github.com/pavelanni/geekhouse/blob/main/src/server/config_handler.py"
    click Utils "https://github.com/pavelanni/geekhouse/blob/main/src/server/utils.py"
    click TOML "https://github.com/pavelanni/geekhouse/blob/main/config/config_example.toml"
    click Deploy "https://github.com/pavelanni/geekhouse/blob/main/deploy/deploy.sh"
    click Converter "https://github.com/pavelanni/geekhouse/blob/main/deploy/toml_to_json.py"
    click LCD "https://github.com/pavelanni/geekhouse/blob/main/lib/lcd1602.py"
    click LLM "https://github.com/pavelanni/geekhouse/blob/main/src/llm_iot/dialogue.py"

    %% Legend
    subgraph Legend
        L1[API Components]:::api
        L2[Core Components]:::core
        L3[Configuration Components]:::config
        L4[Hardware Components]:::hw
    end
```
