# rukenshia/pomodoro architecture

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

- Interactive diagram: https://gitdiagram.com/rukenshia/pomodoro
- Repository: https://github.com/rukenshia/pomodoro

## Overview

##### Project Type and Purpose
- This is an embedded/full-stack application built for an ESP32 microcontroller.
- Its primary function is as a focus timer that uses a 4.26-inch ePaper display, a rotary encoder with an integrated push button for user input, and a WS2812 LED for visual feedback.
- The README also shows that the project includes customizable presets, statistics display, and fun easter eggs, as well as hardware aspects (case files in STL, pin mapping, etc.). This indicates that the system straddles both the physical hardware integration and embedded software development using the Arduino platform (managed through PlatformIO).

##### Key Components
- Hardware Components:
- ESP32 microcontroller (central device)
- ePaper Display (WaveShare 4.26" HAT with specific pin connections)
- Rotary Encoder (KY-040 with directional input and a push switch)
- WS2812 LED (for status indication – connected to digital pin)
- Additional hardware elements such as USB-C power connector and 3D printed case parts (STL files indicate physical enclosure design)
- Software Components:
- Main application logic (timer functionality and presets defined in src/main.cpp)
- Modules managing different functionalities: states (with separate source files for “timer_running”, “timer_selecting_preset”, etc.), menu management, preferences handling, and statistics display.
- Debug and configuration code (various header files like defs.h, debug.h)
- External Libraries and Frameworks:
- Arduino framework via PlatformIO (indicated in platformio.ini and README installation instructions)
- GxEPD2 library for controlling the ePaper display
- Possibly NeoPixel library for managing LED animations.

##### Relationships and Interactions
- The ESP32 serves as the central controller, interfacing with all hardware peripherals using its GPIOs as mapped (detailed pin mapping provided in the README).
- The user interacts via the rotary encoder (to navigate menus and choose presets) which feeds input into the timer’s state machine.
- The software on the ESP32 selects and displays the appropriate UI on the ePaper display, updates the LED, and manages timing based on user presets.
- The state machine is an important architectural pattern here. The project organizes different timer states (e.g., timer running, selecting preset, waiting for confirmation) in separate files that clearly modularize its behavior.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different directories and modules handle distinct functionality (states, asset utilities, hardware pin mapping).
- State Machine: The timer’s behavior is split into several states (each with its own file) demonstrating a state-driven design.
- Hardware Abstraction: The code isolates hardware-specific code (e.g., dealing with LED control, rotary encoder debouncing, and interfacing with the display) from the application logic.

##### Emphasizing Details for the Specific Project
- As this is a full-stack embedded project, clearly delineate the hardware and the embedded software layers.
- Physical pins and interactions as per the README’s pin mapping section.
- Modular design of the firmware by showing individual state modules, asset management, and utility support.
- Do not over-simplify: ensure that every logical component and data flow (e.g., from input -> processing -> output) is represented.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        esp32["ESP32 Microcontroller"]:::hardware
        epaper["ePaper Display"]:::hardware
        rotary["Rotary Encoder (+Push Button)"]:::hardware
        led["WS2812 LED"]:::hardware
        enclosure["3D Printed Case Files"]:::hardware
    end

    %% Firmware Software Modules
    subgraph "Firmware Software Modules"
        mainApp["Main Application Logic"]:::software
        timerState["Timer State Machine"]:::software
            subgraph "Timer States"
                timerRunning["Timer Running"]:::software
                timerBreak["Timer Running Break"]:::software
                timerPreset["Timer Selecting Preset"]:::software
                timerConfirm["Timer Waiting for Confirmation"]:::software
            end
        menuPrefs["Menu & Preferences Manager"]:::software
        stats["Statistics Display Module"]:::software
        utilities["Utility Functions (GFX, Icon Provider, Asset Headers)"]:::software
        debugCfg["Debug & Configuration"]:::software
    end

    %% Asset Management Pipeline
    subgraph "Asset Management Pipeline"
        assetScript["Asset Generation Script"]:::asset
        assets["Generated Assets\n(Icons, Images, Fonts)"]:::asset
    end

    %% External Libraries & Tools
    subgraph "External Libraries & Tools"
        platformio["Arduino/PlatformIO\nGxEPD2 & NeoPixel Libraries"]:::external
    end

    %% Connections between Hardware and Software
    esp32 -->|"hosts"| mainApp
    mainApp -->|"controls"| epaper
    mainApp -->|"reads input from"| rotary
    mainApp -->|"updates"| led
    esp32 -->|"housed in"| enclosure

    %% Software internal connections
    mainApp -->|"manages"| timerState
    mainApp -->|"invokes"| menuPrefs
    mainApp -->|"updates"| stats
    mainApp -->|"logs via"| debugCfg
    timerState -->|"state flow"| timerRunning
    timerRunning -->|"to"| timerBreak
    timerBreak -->|"to"| timerPreset
    timerPreset -->|"to"| timerConfirm
    timerConfirm -->|"loops to"| timerRunning

    %% Asset pipeline connections
    assetScript -->|"generates"| assets
    assets -->|"supplies"| utilities

    %% External libraries building the firmware
    platformio -->|"builds"| mainApp

    %% Styling definitions
    classDef hardware fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef software fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef asset fill:#FDFD96,stroke:#000,stroke-width:2px;
    classDef external fill:#FFCCCB,stroke:#000,stroke-width:2px;

    %% Click Events for component mappings
    click mainApp "https://github.com/rukenshia/pomodoro/blob/main/src/main.cpp"
    click epaper "https://github.com/rukenshia/pomodoro/blob/main/src/GxEPD2_display_selection_new_style.h"
    click rotary "https://github.com/rukenshia/pomodoro/blob/main/src/button.cpp"
    click led "https://github.com/rukenshia/pomodoro/blob/main/src/led.cpp"
    click timerRunning "https://github.com/rukenshia/pomodoro/blob/main/src/states/timer_running.cpp"
    click timerBreak "https://github.com/rukenshia/pomodoro/blob/main/src/states/timer_running_break.cpp"
    click timerPreset "https://github.com/rukenshia/pomodoro/blob/main/src/states/timer_selecting_preset.cpp"
    click timerConfirm "https://github.com/rukenshia/pomodoro/blob/main/src/states/timer_waiting_for_confirmation.cpp"
    click menuPrefs "https://github.com/rukenshia/pomodoro/blob/main/src/menu.cpp"
    click stats "https://github.com/rukenshia/pomodoro/blob/main/src/statistics.cpp"
    click utilities "https://github.com/rukenshia/pomodoro/blob/main/src/gfx_utils.cpp"
    click debugCfg "https://github.com/rukenshia/pomodoro/blob/main/src/debug.h"
    click assetScript "https://github.com/rukenshia/pomodoro/blob/main/scripts/gen_assets.py"
    click assets "https://github.com/rukenshia/pomodoro/tree/main/src/icons"
    click enclosure "https://github.com/rukenshia/pomodoro/tree/main/stl/"
    click platformio "https://github.com/rukenshia/pomodoro/blob/main/platformio.ini"
```
