# juancarlis/py-task-tracker architecture

> Architecture diagram of the GitHub repository juancarlis/py-task-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juancarlis/py-task-tracker
- Repository: https://github.com/juancarlis/py-task-tracker

## Overview

##### Project Type and Purpose
- Pomo Tracker is a CLI-based productivity tool (open-source utility) for Pomodoro time tracking, task management, and alarm notifications.
- Key use cases: managing tasks, tracking work intervals, scheduling one-time or recurring alarms, and notifying users (via `wsl-notify-send` or console output).

##### High-Level Architecture Components
a. CLI Layer (User Interface)
- Entry Point: `src/app.py` invoked via the `uv` runner.
- Subcommands: `taskcli`, `tracker`, `alarm`, `categories`, `utils` — each defined in module-specific `cli.py`.
b. Service Layer (Business Logic)
- TaskService (`src/tasks/service.py`): create, update, complete, delete tasks.
- TrackerService (`src/tracker/service.py`): start/stop timers, track durations.
- AlarmService (`src/alarm/service.py`): schedule alarms, recurring logic, polling.
- CategoryService (`src/categories/service.py`): manage task categories.
c. Data Access Layer (Persistence)
- Database Connector: `src/database/database.py` (likely SQLite via SQLAlchemy or similar).
- Schema Initialization: `src/database/init_db.py`.
- Queries per module: `src/<module>/queries.py`.
- Models per module: `src/<module>/models.py`.
d. Utilities
- General helpers: date calculations, CSV export, display formatting (`src/utils/*`).
- Settings loader: `src/settings/settings.py` (configuration management).
e. External Services
- Notification: `wsl-notify-send.exe` invoked by the AlarmService.
- UV runner: orchestrates command dispatch (`uv install`, `uv run …`).

##### Relationships and Data Flows
- User inputs commands → CLI Layer (`app.py`) dispatches to appropriate module CLI.
- CLI handler calls Service Layer methods.
- Services perform business logic and invoke Data Access Layer.
- Data Access Layer issues SQL queries or ORM operations, returning results to Service Layer.
- AlarmService triggers notifications:
- On Windows/WSL: calls `wsl-notify-send`.
- Fallback: prints alerts to console.
- Utilities are shared by all layers for cross-cutting concerns (formatting, date handling).

##### Architectural Patterns and Design Principles
- Layered Architecture: Clear separation between CLI, services, and data layers.
- Modular Design: Each domain (tasks, tracker, alarm, categories) has its own package with CLI, service, queries, models.
- Dependency Injection via settings module for DB connection and configuration.
- Single Responsibility: small, well-defined modules.
- Extensibility Points: adding new CLI commands, new modules (e.g., reports) by following existing package structure.

##### Detailed Capture of Architectural Elements
- Don’t over-abstract—include each module package as a separate service component.
- `uv` runner at the top invoking `app.py`.
- `init-db` command path for schema setup.
- Future-improvement extension points (report export module) as placeholders.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UV Runner
    uvRunner["UV Runner"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        app["app.py\n(CLI EntryPoint)"]:::cli
        tCli["taskcli CLI"]:::cli
        trCli["tracker CLI"]:::cli
        alCli["alarm CLI"]:::cli
        catCli["categories CLI"]:::cli
        utilCli["utils CLI"]:::cli
    end

    %% Service Layer
    subgraph "Service Layer"
        ts["TaskService"]:::service
        trs["TrackerService"]:::service
        als["AlarmService"]:::service
        alPoll["Alarm Polling Logic"]:::service
        cs["CategoryService"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        dbConn["Database Connector"]:::data
        initDb["Schema Init\n(init-db)"]:::data
        sharedQueries["Shared DB Queries"]:::data
        subgraph "Module Persistence"
            tasksModels["Task Models"]:::data
            tasksQueries["Task Queries"]:::data
            trackerModels["Tracker Models"]:::data
            categoryModels["Category Models"]:::data
            categoryQueries["Category Queries"]:::data
        end
        db["Database\n(tasks, categories,\n time_tracking, alarms)"]:::database
    end

    %% Utilities and Settings
    subgraph "Utilities & Settings"
        dateFuncs["Date Functions"]:::util
        displayFmt["Display Formatting"]:::util
        exportCsv["CSV Export"]:::util
        settings["Settings Loader"]:::util
    end

    %% External Notifier
    extNotify["External Notifier\n(wsl-notify-send)"]:::external

    %% Connections
    uvRunner --> app
    app --> tCli
    app --> trCli
    app --> alCli
    app --> catCli
    app --> utilCli

    tCli --> ts
    trCli --> trs
    alCli --> als
    catCli --> cs

    ts --> tasksQueries
    ts --> tasksModels
    trs --> trackerModels
    cs --> categoryModels
    cs --> categoryQueries

    ts --> dbConn
    trs --> dbConn
    als --> dbConn
    cs --> dbConn
    sharedQueries --> dbConn
    dbConn --> db

    initDb --> db

    als --> alPoll
    alPoll --> extNotify

    %% Cross-cutting utilities and settings
    ts --> dateFuncs
    trs --> dateFuncs
    als --> dateFuncs
    cs --> dateFuncs
    utilCli --> displayFmt
    utilCli --> exportCsv
    ts --> settings
    trs --> settings
    als --> settings
    cs --> settings

    %% Click Events
    click app "https://github.com/juancarlis/py-task-tracker/blob/main/src/app.py"
    click tCli "https://github.com/juancarlis/py-task-tracker/blob/main/src/tasks/cli.py"
    click trCli "https://github.com/juancarlis/py-task-tracker/blob/main/src/tracker/cli.py"
    click alCli "https://github.com/juancarlis/py-task-tracker/blob/main/src/alarm/cli.py"
    click catCli "https://github.com/juancarlis/py-task-tracker/blob/main/src/categories/cli.py"
    click utilCli "https://github.com/juancarlis/py-task-tracker/blob/main/src/utils/cli.py"
    click ts "https://github.com/juancarlis/py-task-tracker/blob/main/src/tasks/service.py"
    click trs "https://github.com/juancarlis/py-task-tracker/blob/main/src/tracker/service.py"
    click als "https://github.com/juancarlis/py-task-tracker/blob/main/src/alarm/service.py"
    click alPoll "https://github.com/juancarlis/py-task-tracker/blob/main/src/alarm/check_alarms.py"
    click cs "https://github.com/juancarlis/py-task-tracker/blob/main/src/categories/service.py"
    click dbConn "https://github.com/juancarlis/py-task-tracker/blob/main/src/database/database.py"
    click initDb "https://github.com/juancarlis/py-task-tracker/blob/main/src/database/init_db.py"
    click sharedQueries "https://github.com/juancarlis/py-task-tracker/blob/main/src/database/queries.py"
    click tasksModels "https://github.com/juancarlis/py-task-tracker/blob/main/src/tasks/models.py"
    click tasksQueries "https://github.com/juancarlis/py-task-tracker/blob/main/src/tasks/queries.py"
    click trackerModels "https://github.com/juancarlis/py-task-tracker/blob/main/src/tracker/models.py"
    click categoryModels "https://github.com/juancarlis/py-task-tracker/blob/main/src/categories/models.py"
    click categoryQueries "https://github.com/juancarlis/py-task-tracker/blob/main/src/categories/queries.py"
    click dateFuncs "https://github.com/juancarlis/py-task-tracker/blob/main/src/utils/date_funcs.py"
    click displayFmt "https://github.com/juancarlis/py-task-tracker/blob/main/src/utils/display.py"
    click exportCsv "https://github.com/juancarlis/py-task-tracker/blob/main/src/utils/export_csv.py"
    click settings "https://github.com/juancarlis/py-task-tracker/blob/main/src/settings/settings.py"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef service fill:#d4edda,stroke:#000,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#000,stroke-width:1px
    classDef database fill:#ffe5b4,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef util fill:#e2e3e5,stroke:#000,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
