How juancarlis/py-task-tracker works
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.