# ahsanulhoque22/waifos architecture

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

- Interactive diagram: https://gitdiagram.com/ahsanulhoque22/waifos
- Repository: https://github.com/ahsanulhoque22/waifos

## Overview

##### Project Type and Purpose
- This is an embedded full-stack (firmware) application that implements a lightweight OS (FreeRTOS + Arduino) on an ESP32, providing a modular app framework, display/UI, input handling, WiFi, NTP, and filesystem support.

##### Break Down the File Structure into Architectural Layers
- Top-level files (platformio.ini, sdkconfig, CMakeLists, partitions.csv) define the build/deploy environment.
- The `lib/esp8266-oled-ssd1306` directory holds the display driver (hardware abstraction).
- The `include/` folder contains headers for all managers, the `kernel`, `state_manager`, and individual apps.
- The `src/` folder contains corresponding implementations, plus `main.cpp` (entry point) and `upload_fs.py` (files-to-LittleFS uploader).

##### Extract Core Components from README and Code
a. Hardware Layer
– ESP32 DevKit v1 (WROOM-32)
– SH1106 I2C OLED (SDA=21, SCL=22)
– 6 Buttons (GPIOs 14,25,26,27,32,33)
– Onboard WiFi radio
– LittleFS partition for file storage
b. OS & HAL Layer
– FreeRTOS scheduler (dual-core)
– HAL drivers: `display_manager`, `input_manager`, `bt_keyboard_manager`, `files_app` (LittleFS adapter)
– Mutex (`displayMutex`) for display synchronization
c. System Services Layer
– `kernel` (initialization, task wrapper)
– `state_manager` (UI state machine)
– `app_manager` (launches and tears down app tasks)
– `ui_manager` (coordinates screen updates, app menu)
– `task_manager_app` (in-OS task viewer/manager)
d. Application Layer (Modular Apps)
– `splash_screen` (startup)
– `snake_game`
– `weather_app` (WiFi, NTP, JSON parsing)
– `files_app` (file browser)
– `dummy_app` (template/example)
e. External Services & Libraries
– NTP server (`pool.ntp.org`)
– WiFi network
– PlatformIO build environment & extra_scripts (upload_fs.py)
– Arduino libraries: WiFi, AsyncTCP, PubSubClient, ArduinoJson, BLE Keyboard

##### Component Interactions
- On boot (`main.cpp`): kernel → initialize managers → `splash_screen`.
- `app_manager` spawns each app as a FreeRTOS task.
- Apps call `display_manager` (under `displayMutex`) for drawing.
- User input flows from buttons → `input_manager` → `state_manager` → `ui_manager` → `app_manager`.
- `weather_app` uses WiFi driver → NTP → HTTPClient + JSON parser.
- `files_app` uses `upload_fs.py` to populate LittleFS and then reads via an SPIFFS client.
- BLE input is handled by `bt_keyboard_manager` and presented to the UI layer.

##### Architectural Patterns & Design Principles
– Layered architecture (Hardware → HAL → Kernel/Services → App)
– Modular apps loaded/unloaded at runtime via a central `app_manager`
– FreeRTOS task-based concurrency with per-app tasks
– Mutex-protected shared resources (OLED display)
– State machine for UI navigation (`state_manager`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        style Hardware Layer fill:#e0f7e9,stroke:#333,stroke-width:1px
        ESP32["ESP32 DevKit v1\n(WROOM-32)"]:::hardware
        OLED["SH1106 I2C OLED\n(SDA=21, SCL=22)"]:::hardware
        Buttons["6 Buttons\n(GPIO14,25,26,27,32,33)"]:::hardware
        WiFiRadio["Onboard WiFi Radio"]:::hardware
        LittleFS["LittleFS Partition"]:::storage
    end

    %% HAL Drivers Layer
    subgraph "HAL Drivers"
        style HAL Drivers fill:#d0e4fc,stroke:#333,stroke-width:1px
        DM["Display Manager"]:::hal
        IM["Input Manager"]:::hal
        BTKM["BLE Keyboard Manager"]:::hal
        FSAdapter["Filesystem Adapter\n(LittleFS)"]:::hal
    end

    %% RTOS Kernel Layer
    subgraph "RTOS Kernel"
        style RTOS Kernel fill:#ffe5b4,stroke:#333,stroke-width:1px
        Scheduler["FreeRTOS Scheduler\n(Dual-Core)"]:::kernel
        Mutex["displayMutex\n(xSemaphore)"]:::kernel
        KernelInit["Kernel Init & Task Wrapper"]:::kernel
    end

    %% System Services Layer
    subgraph "System Services"
        style System Services fill:#ffd6f7,stroke:#333,stroke-width:1px
        StateMgr["State Manager\n(UI State Machine)"]:::service
        AppMgr["App Manager\n(Task Launcher/Teardown)"]:::service
        UIMgr["UI Manager\n(Screen Updates & Menu)"]:::service
        TaskApp["Task Manager App\n(In-OS Task Viewer)"]:::service
    end

    %% Application Layer
    subgraph "Applications"
        style Applications fill:#e0d1ff,stroke:#333,stroke-width:1px
        Splash["Splash Screen"]:::app
        Snake["Snake Game"]:::app
        Weather["Weather App"]:::app
        FilesAppUI["Files App"]:::app
        Dummy["Dummy App"]:::app
    end

    %% External Services
    subgraph "External Services"
        style External Services fill:#f0f0f0,stroke:#333,stroke-width:1px
        NTP["NTP Server\n(pool.ntp.org)"]:::external
        WiFiAP["WiFi Network"]:::external
        UploadFS["upload_fs.py Script"]:::external
    end

    %% Connections Boot Sequence
    src_main["main.cpp\n(Entry Point)"]:::entry
    src_main -->|"boot"| KernelInit
    KernelInit -->|"init HAL"| DM
    KernelInit --> IM
    KernelInit --> BTKM
    KernelInit --> FSAdapter
    KernelInit --> Scheduler
    KernelInit --> StateMgr
    KernelInit --> AppMgr
    KernelInit --> UIMgr
    KernelInit --> Splash

    %% Input Flow
    Buttons -->|"GPIO Read"| IM
    IM -->|"input events"| StateMgr
    StateMgr -->|"state update"| UIMgr
    UIMgr -->|"menu selection"| AppMgr

    %% Display Flow
    subgraph DisplayPath
        Splash -->|"draw() xSemaphoreTake/displayMutex"| DM
        Snake -->|"draw() xSemaphoreTake/displayMutex"| DM
        Weather -->|"draw() xSemaphoreTake/displayMutex"| DM
        FilesAppUI -->|"draw() xSemaphoreTake/displayMutex"| DM
        Dummy -->|"draw() xSemaphoreTake/displayMutex"| DM
        TaskApp -->|"draw() xSemaphoreTake/displayMutex"| DM
        DM -->|"I2C"| OLED
        Scheduler -.-> Mutex
    end

    %% Network Flow
    Weather -->|"HTTP GET"| WiFiRadio
    WiFiRadio -->|"NTP request"| NTP
    WiFiRadio -->|"WiFi AP connect"| WiFiAP
    Weather -->|"JSON parse"| ArduinoJson["ArduinoJson Lib"]:::external

    %% Filesystem Flow
    UploadFS -->|"populate"| LittleFS
    FilesAppUI -->|"SPIFFS read"| LittleFS
    FSAdapter -->|"LittleFS API"| LittleFS

    %% Styles
    classDef hardware fill:#a8e6cf,stroke:#333,stroke-width:1px
    classDef hal fill:#87cefa,stroke:#333,stroke-width:1px
    classDef kernel fill:#ffa500,stroke:#333,stroke-width:1px
    classDef service fill:#ffb6c1,stroke:#333,stroke-width:1px
    classDef app fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef storage fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef entry fill:#fffacd,stroke:#333,stroke-width:1px

    %% Click Events
    click DM "https://github.com/ahsanulhoque22/waifos/blob/main/include/display_manager.h"
    click IM "https://github.com/ahsanulhoque22/waifos/blob/main/include/input_manager.h"
    click BTKM "https://github.com/ahsanulhoque22/waifos/blob/main/include/bt_keyboard_manager.h"
    click FSAdapter "https://github.com/ahsanulhoque22/waifos/blob/main/include/files_app.h"
    click KernelInit "https://github.com/ahsanulhoque22/waifos/blob/main/include/kernel.h"
    click StateMgr "https://github.com/ahsanulhoque22/waifos/blob/main/include/state_manager.h"
    click AppMgr "https://github.com/ahsanulhoque22/waifos/blob/main/include/app_manager.h"
    click UIMgr "https://github.com/ahsanulhoque22/waifos/blob/main/include/ui_manager.h"
    click TaskApp "https://github.com/ahsanulhoque22/waifos/blob/main/include/task_manager_app.h"
    click Splash "https://github.com/ahsanulhoque22/waifos/blob/main/include/splash_screen.h"
    click Snake "https://github.com/ahsanulhoque22/waifos/blob/main/include/snake_game.h"
    click Weather "https://github.com/ahsanulhoque22/waifos/blob/main/include/weather_app.h"
    click FilesAppUI "https://github.com/ahsanulhoque22/waifos/blob/main/include/files_app.h"
    click Dummy "https://github.com/ahsanulhoque22/waifos/blob/main/include/dummy_app.h"
    click src_main "https://github.com/ahsanulhoque22/waifos/blob/main/src/main.cpp"
```
