# firoziya/limma architecture

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

- Interactive diagram: https://gitdiagram.com/firoziya/limma
- Repository: https://github.com/firoziya/limma

## Overview

##### Project Type & Purpose
- LIMMA is an open-source Python SDK (library) designed to translate natural-language commands into control signals for ESP8266/ESP32 IoT devices. It sits between user code (or voice input) and the actual ESP devices, optionally calling out to a cloud NLP/AI service.

##### File Structure Analysis
- Top-level files (README.md, setup.py, pyproject.toml, requirements.txt) identify this as a distributable Python package.
- limma/ contains __init__.py and core.py, indicating a single-package library.
- core.py likely houses:
- LimmaConfig & Limma entry classes
- Methods for communicating with the AI/NLP server (send_to_server)
- Methods for communicating with ESP devices (send_to_esp, ESPManager)
- Utility modules (NetworkUtils)

##### Architecture Insights from README
- Core components:
- LimmaConfig – holds API key, device map, ESP IP, etc.
- Limma – main facade for execute_command, auto_discovery, context management
- ESPManager – check_connection, configure_wifi, get_esp_status
- NetworkUtils – scan_network_for_esp, get_local_ip
- Optional voice I/O via pyvoicekit
- External dependencies:
- LIMMA cloud API (pylimma.vercel.app) for natural-language parsing
- ESP8266/ESP32 devices running a simple HTTP server

1. Developer Application
- CLI / script / voice loop
2. LIMMA SDK (your code)
- Sub-modules (see below)
3. External AI/NLP Service
4. IoT Devices (ESP8266/ESP32)
b. Sub-components inside “LIMMA SDK”:
- Configuration Layer (LimmaConfig)
- Command Processing Layer
– execute_command → parse intent/context
- API Client Layer
– send_to_server (HTTP to Cloud API)
- Device Communication Layer
– ESPManager.send_to_esp (HTTP calls to device routes)
- Network Utilities
– auto_discover_esp via NetworkUtils.scan_network_for_esp
- Context Manager
– get_context_info, clear_context
- (Optional) Voice I/O Adapter
– Integrates pyvoicekit.listen / speak
c. Relationships & Data Flow:
1. Developer App calls Limma.execute_command(command_str).
2. SDK’s Command Processor invokes API Client → Cloud AI/NLP Service.
3. Service returns a list of device function calls (e.g., ["ch01on", "ch02off"]).
4. SDK’s Device Communication Layer issues HTTP requests to each ESP device using mapped endpoints (/ch01on, /ch02off).
5. ESP device web server updates GPIO pins, returns status.
6. SDK aggregates responses, returns (success, reply) to Developer App.
7. Auto-discover and network utilities scan LAN for ESP devices, feeding back into LimmaConfig.
8. Optional voice path wraps step 1 & 6 with listen/speak.
d. Architectural Patterns & Principles:
- Layered Architecture: clear separation between configuration, business logic (command parsing), external calls (API, device), and utilities.
- Facade Pattern: Limma class provides a simple API.
- Dependency Injection: LimmaConfig injected into Limma.

##### Detailed Checklist
- Technology/port info:
- Cloud API (HTTPS :443)
- ESP WebServer (HTTP :80)
- Related modules (e.g., all SDK sub-modules inside a large “LIMMA SDK” container).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing components
    DeveloperApp["Developer App"]:::user
    VoiceAdapter["Voice I/O Adapter"]:::user

    %% Top-level project metadata
    subgraph "Project Metadata"
      ProjectMeta["setup.py, pyproject.toml, requirements.txt, README.md, LICENSE, MANIFEST.in, CHANGELOG.md"]:::infra
    end

    %% SDK Container
    subgraph "LIMMA SDK"
      direction TB
      Init["Package Initialization"]:::internal
      LimmaConfig["LimmaConfig"]:::internal
      LimmaFacade["Limma (Facade)"]:::internal
      CommandProcessor["Command Processor"]:::internal
      APIClient["API Client (send_to_server)"]:::internal
      DeviceComm["Device Communication (ESPManager)"]:::internal
      NetworkUtils["Network Utilities"]:::internal
      ContextMgr["Context Manager"]:::internal
    end

    %% External systems
    ExternalAPI["External AI/NLP Service\n(HTTPS :443)"]:::external
    ESPDevices["ESP8266/ESP32 Devices\n(HTTP :80)"]:::external

    %% Main flow
    DeveloperApp -->|"execute_command(cmd)"| LimmaFacade
    LimmaFacade -->|"use config"| LimmaConfig
    LimmaFacade -->|"process command"| CommandProcessor
    CommandProcessor -->|"HTTP request"| APIClient
    APIClient -->|"parse intent"| ExternalAPI
    ExternalAPI -->|"function list"| APIClient
    APIClient -->|"intent payload"| DeviceComm
    DeviceComm -->|"GPIO Toggle"| ESPDevices
    ESPDevices -->|"status response"| DeviceComm
    DeviceComm -->|"aggregate responses"| LimmaFacade
    LimmaFacade -->|"return (success, reply)"| DeveloperApp

    %% Auto-discovery flow
    NetworkUtils -->|"scan LAN"| ESPDevices
    NetworkUtils -->|"update config"| LimmaConfig
    LimmaFacade -->|"auto_discovery()"| NetworkUtils

    %% Optional voice path
    DeveloperApp -.->|listen/speak| VoiceAdapter
    VoiceAdapter -.->|execute_command/results| LimmaFacade

    %% Click Events
    click LimmaConfig "https://github.com/firoziya/limma/blob/main/limma/core.py"
    click LimmaFacade "https://github.com/firoziya/limma/blob/main/limma/core.py"
    click APIClient "https://github.com/firoziya/limma/blob/main/limma/core.py"
    click DeviceComm "https://github.com/firoziya/limma/blob/main/limma/core.py"
    click NetworkUtils "https://github.com/firoziya/limma/blob/main/limma/core.py"
    click Init "https://github.com/firoziya/limma/blob/main/limma/__init__.py"
    click ProjectMeta "https://github.com/firoziya/limma/blob/main/setup.py"

    %% Styles
    classDef internal fill:#bbf,stroke:#888,stroke-width:1px
    classDef external fill:#bfb,stroke:#080,stroke-width:1px
    classDef user fill:#ffb,stroke:#aa0,stroke-width:1px
    classDef infra fill:#ddd,stroke:#444,stroke-width:1px,stroke-dasharray: 2 2
```
