# bahaaio/pomo architecture

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

- Interactive diagram: https://gitdiagram.com/bahaaio/pomo
- Repository: https://github.com/bahaaio/pomo

## Overview

##### Project type and purpose
- This is a command-line Pomodoro timer written in Go. It’s a single-binary Terminal UI tool that tracks work/break sessions, renders a live progress bar, responds to keyboard shortcuts, reads a YAML config, emits desktop notifications, and optionally runs user commands when a session ends.

##### File structure
- Top-level:
- cmd/ — three entry points (root.go, break.go, runner.go) implementing CLI commands via Cobra or a similar parser
- config/ — config loader and utilities for finding/parsing `pomo.yaml`
- ui/ — Bubble Tea-based view layer (keys.go, ui.go)
- `pomo.go` + `pomo.yml` — default values and full-example config
- CI/CD (`.github/…`, `.goreleaser.yaml`, build workflows)
- Patterns:
- CLI command dispatcher → core timer/runner → UI event loop → side-effects (notifications, hooks)
- Config lookup chain → loader → in-memory struct

##### README
- Confirms architecture: CLI commands map to work/break sessions, uses Bubble Tea for TUI, reads YAML in a defined search order, cross-platform notifications, supports custom shell commands.

##### Details
- Config lookup chain (current dir → system dir → defaults)
- That UI Renderer subscribes to Timer Engine events

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraph for CLI Frontend
    subgraph "CLI Frontend"
        direction TB
        RootCmd["root.go"]:::internal
        BreakCmd["break.go"]:::internal
        RunnerCmd["runner.go"]:::internal
    end

    %% Subgraph for Config Loader
    subgraph "Config Loader"
        direction TB
        ConfigCore["config.go"]:::internal
        ConfigUtils["utils.go"]:::internal
        ConfigFile["pomo.yml"]:::config
    end

    %% Core Timer Engine
    TimerEngine["Timer Engine"]:::core

    %% Subgraph for UI Renderer
    subgraph "UI Renderer"
        direction TB
        UICore["ui.go"]:::internal
        UIKeys["keys.go"]:::internal
    end

    %% Side-effect Services
    NotificationService["Notification Service"]:::external
    HookExecutor["Hook Executor"]:::external
    OSShell["OS Shell"]:::external
    OSNotify["Notification Daemon"]:::external

    %% Flows
    User["User"]:::external
    User -->|"invoke CLI"| RootCmd
    User --> BreakCmd
    User --> RunnerCmd

    RootCmd -->|"load config"| ConfigCore
    BreakCmd -->|"load config"| ConfigCore
    RunnerCmd -->|"load config"| ConfigCore
    ConfigCore -->|"uses utils"| ConfigUtils
    ConfigCore -->|"reads file"| ConfigFile
    ConfigFile --> ConfigCore

    RootCmd -->|"start session"| TimerEngine
    BreakCmd -->|"start break"| TimerEngine
    RunnerCmd -->|"start runner"| TimerEngine

    TimerEngine -->|"tick events"| UICore
    TimerEngine -->|"tick events"| UIKeys

    TimerEngine -->|"session end"| NotificationService
    TimerEngine -->|"session end"| HookExecutor

    NotificationService -->|"send notification"| OSNotify
    HookExecutor -->|"exec command"| OSShell

    %% Click Events
    click RootCmd "https://github.com/bahaaio/pomo/blob/main/cmd/root.go"
    click BreakCmd "https://github.com/bahaaio/pomo/blob/main/cmd/break.go"
    click RunnerCmd "https://github.com/bahaaio/pomo/blob/main/cmd/runner.go"
    click ConfigCore "https://github.com/bahaaio/pomo/blob/main/config/config.go"
    click ConfigUtils "https://github.com/bahaaio/pomo/blob/main/config/utils.go"
    click ConfigFile "https://github.com/bahaaio/pomo/blob/main/pomo.yml"
    click TimerEngine "https://github.com/bahaaio/pomo/blob/main/pomo.go"
    click UICore "https://github.com/bahaaio/pomo/blob/main/ui/ui.go"
    click UIKeys "https://github.com/bahaaio/pomo/blob/main/ui/keys.go"
    click HookExecutor "https://github.com/bahaaio/pomo/blob/main/cmd/runner.go"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#F0E68C,stroke:#333,stroke-width:1px
```
