# sammarxz/pomerode architecture

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

- Interactive diagram: https://gitdiagram.com/sammarxz/pomerode
- Repository: https://github.com/sammarxz/pomerode

## Overview

##### Main Components
- UI Layer
- GTK4/libadwaita front-end built from data/ui/*.ui and data/css/style.css
- Window, Preferences and Help overlays defined in `.ui` files
- Application Core
- Vala source in `src/`
- Timer engine, session management, smart break logic, configuration loader
- Configuration & Resources
- GSettings schemas (`data/com.github.sammarxz.pomerode.gschema.xml`) for storing preferences
- System Integration
- System notifications via libnotify or GTK API
- Autostart via freedesktop service file (`data/com.github.sammarxz.pomerode.service.in`)
- Build & Packaging
- Meson build files at root, `src/`, `data/`, `po/` for translations
- Ninja as build executor
- External Dependencies
- elementary OS platform (Granite)
- GTK4, libadwaita

##### Relationships & Data Flow
- UI Layer → emits signals (Start, Stop, Preferences changed) → Application Core
- Application Core ↔ GSettings store (read/write durations, preferences)
- Application Core → triggers Notifications → System Notification Service
- Application Core → updates UI (session counters, progress bars)
- Build System → compiles Vala → links GTK4, libadwaita, Granite → generates executable with embedded GResource

##### Architectural Patterns & Design Principles
- MVC-like separation:
- View: UI files + CSS (data/ui, data/css)
- Controller/Model: Vala classes in `src/` (application.vala, util.vala, preferences.vala, window.vala)
- Resource bundling via GResource for single-bundle deployment
- Use of GSettings for centralized, persistent configuration

##### Essential Elements
- All Vala classes in the core and their roles (main, application, window, preferences, util)
- UI files and CSS as part of the View layer
- GSettings schema XML and service file templates in the configuration layer
- Build artifacts: meson.build files orchestrating compile/link steps
- External dependencies (GTK4, libadwaita, Granite, elementary-sdk)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        GTK4_UI["GTK4 UI"]:::ui
        Window_UI["Window UI"]:::ui
        Preferences_UI["Preferences UI"]:::ui
        Help_UI["Help Overlay UI"]:::ui
        CSS["CSS Styling"]:::ui
    end

    %% Application Core
    subgraph "Application Core"
        Main["Main (main.vala)"]:::core
        AppLogic["Timer Engine & Session Mgmt\n(application.vala)"]:::core
        WindowCtrl["Window Controller\n(window.vala)"]:::core
        PrefCtrl["Preferences Controller\n(preferences.vala)"]:::core
        Util["Utility Module\n(util.vala)"]:::core
        ConfigLoader["Config Loader Template\n(config.vala.in)"]:::core
    end

    %% Configuration & Resources
    subgraph "Configuration & Resources"
        GSettings[(GSettings Schema)]:::storage
        GResource["GResource Bundle\nDefinition"]:::storage
    end

    %% System Integration
    subgraph "System Integration"
        Notifications["Notifications Service"]:::external
        Autostart["Autostart Service"]:::external
        DesktopFile["Desktop File Template"]:::external
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        Meson["Meson Build"]:::build
        Ninja["Ninja Executor"]:::build
        Translations["Translations (po/)"]:::build
        BuildAux["Build Aux Scripts"]:::build
        Executable["Generated Executable"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        GTK4["GTK4"]:::external
        LibAdwaita["libadwaita"]:::external
        Granite["Granite"]:::external
    end

    %% Connections
    GTK4_UI -->|emits signals| AppLogic
    Preferences_UI -->|emits signals| PrefCtrl
    Window_UI -->|emits signals| WindowCtrl
    Help_UI -->|emits signals| WindowCtrl
    CSS -->|styles UI| GTK4_UI

    Main --> AppLogic
    Main --> WindowCtrl

    AppLogic -->|uses| PrefCtrl
    AppLogic -->|reads/writes prefs| GSettings
    PrefCtrl -->|reads/writes prefs| GSettings
    GSettings <--> PrefCtrl
    AppLogic -->|triggers| Notifications
    AppLogic -->|updates UI| WindowCtrl
    AppLogic -->|updates UI| GTK4_UI

    Meson --> Main
    Meson --> AppLogic
    Meson --> WindowCtrl
    Meson --> PrefCtrl
    Meson --> Util
    Meson --> ConfigLoader
    Meson --> GTK4_UI
    Meson --> GSettings
    Meson --> GResource
    Meson --> Translations
    Meson --> BuildAux
    Meson --> Executable

    Ninja --> Meson
    GResource --> Executable
    Translations --> Executable

    Executable --> GTK4
    Executable --> LibAdwaita
    Executable --> Granite

    %% Click Events
    click GTK4_UI "https://github.com/sammarxz/pomerode/tree/main/data/ui/"
    click Window_UI "https://github.com/sammarxz/pomerode/blob/main/data/ui/window.ui"
    click Preferences_UI "https://github.com/sammarxz/pomerode/blob/main/data/ui/preferences.ui"
    click Help_UI "https://github.com/sammarxz/pomerode/blob/main/data/gtk/help-overlay.ui"
    click CSS "https://github.com/sammarxz/pomerode/blob/main/data/css/style.css"
    click Main "https://github.com/sammarxz/pomerode/blob/main/src/main.vala"
    click AppLogic "https://github.com/sammarxz/pomerode/blob/main/src/application.vala"
    click WindowCtrl "https://github.com/sammarxz/pomerode/blob/main/src/window.vala"
    click PrefCtrl "https://github.com/sammarxz/pomerode/blob/main/src/preferences.vala"
    click Util "https://github.com/sammarxz/pomerode/blob/main/src/util.vala"
    click ConfigLoader "https://github.com/sammarxz/pomerode/blob/main/src/config.vala.in"
    click GSettings "https://github.com/sammarxz/pomerode/blob/main/data/com.github.sammarxz.pomerode.gschema.xml"
    click GResource "https://github.com/sammarxz/pomerode/blob/main/data/com.github.sammarxz.pomerode.gresource.xml"
    click Autostart "https://github.com/sammarxz/pomerode/blob/main/data/com.github.sammarxz.pomerode.service.in"
    click DesktopFile "https://github.com/sammarxz/pomerode/blob/main/data/com.github.sammarxz.pomerode.desktop.in"
    click Translations "https://github.com/sammarxz/pomerode/tree/main/po/"
    click BuildAux "https://github.com/sammarxz/pomerode/blob/main/build-aux/meson/postinstall.py"
    click Meson "https://github.com/sammarxz/pomerode/blob/main/meson.build"

    %% Styles
    classDef ui fill:#d0e1f9,stroke:#4a90e2,color:#000
    classDef core fill:#d4edda,stroke:#28a745,color:#000
    classDef storage fill:#e2d2f4,stroke:#8e44ad,color:#000
    classDef external fill:#ffe5b4,stroke:#f39c12,color:#000
    classDef build fill:#d3d3d3,stroke:#7f8c8d,color:#000
```
