# dvc2/task_tracker architecture

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

- Interactive diagram: https://gitdiagram.com/dvc2/task_tracker
- Repository: https://github.com/dvc2/task_tracker

## Overview

##### Project type and purpose
- TaskTracker is a terminal-based CLI application (Node.js) for task management.
- It has a modular architecture, with command handlers, core/domain services, integration adapters, and file-based persistence.
- Key use cases: create/list/update tasks, track file&git context, generate AI context, produce reports/statistics.

##### File structure
Top-level directories:
- bin/            → CLI entrypoints (shell wrappers, “tt”, “tasktracker”)
- lib/commands/   → One JS file per CLI command (“add.js”, “list.js”, etc.)
- lib/core/       → Domain logic / services (TaskManager, ConfigManager, ArchiveManager…)
- lib/integration/→ Adapters for AI, auto-tracking, external tools
- lib/reporting/  → Charting, stats, journal generators
- lib/utils/      → Shared utilities (CLI parsing, security, output formatting)
- .tasktracker/   → Local JSON data store (config, archives, stats, reports)
- tests/          → Unit/integration/performance/security tests
- docs/           → Documentation, including architecture notes

Config/build/deployment files:
- package.json / install.js → NPM package config & installer
- .github/workflows → CI for tests
- .gitignore, VERSION, LICENSE, CHANGELOG

##### README for additional insights
- Confirms modular design, AI integration, git integration, plugin support, statistics & reporting.

a. Components:
1. Presentation Layer
– CLI entrypoints (bin/tt, bin/tasktracker, shell-completion scripts)
– Command-line parser
2. Application Layer
– Command Registry & Dispatch (lib/commands/index.js)
– Individual Command Handlers (add, list, update, ai-context, stats…)
3. Domain/Core Layer
– TaskManager, ConfigManager, ArchiveManager, DependencyTracker, FileCache, PerfMonitor, ListManager, QuickTask, TaskContext, TaskCommit
4. Integration Layer
– AI Integration Adapter (ai-context-cache, auto-tracker.sh)
– Git Integration (via core file-cache & dependency tracker)
5. Reporting Layer
– BurndownChart, StatsTracker, TaskJournal
6. Persistence Layer
– Local File Store (.tasktracker/*.json)
7. External Services
– AI API (OpenAI/Claude), Git CLI, Possibly plugins (custom modules)

b. Relationships & interactions:
- User types “tt <command>” → shell script → Node process
- CLI Parser reads args → dispatches to correct Command Handler
- Command Handler invokes Core services (e.g., TaskManager)
- Core services read/write JSON files via ConfigManager/FileCache
- Integration adapters called when needed (AI context uses AI API, Git integration uses exec/git commands)
- Reporting modules consume core data to generate charts or reports
- Output streamed back to terminal

c. Architectural patterns & design principles:
- Layered architecture (Presentation → Application → Domain → Persistence)
- Command pattern for CLI commands
- Adapter pattern for AI/Git integrations
- Single-responsibility modules (each core class handles one concern)
- File-based persistence (lightweight, no external DB)
- Modular/plugin extensibility

d. Key technologies & frameworks:
- Node.js (lib/)
- NPM CLI packaging
- Shell scripts for wrappers and completion
- JSON file store under .tasktracker/
- External AI APIs (via integration modules)
- Git CLI

##### Detail
- .tasktracker folder as a bundle of JSON files
- Call out AI-integration and auto-tracker as separate adapter modules
- Shell-completion scripts as optional entrypoints

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLIEntrypoints["CLI Entrypoints"]:::frontend
        ShellWrappers["Shell Wrappers (completion, aliases)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        CLIParser["Command Parser"]:::frontend
        CommandRegistry["Command Registry & Dispatch"]:::frontend
        CommandHandlers["Command Handlers (add, list, update, stats...)"]:::frontend
    end

    %% Domain/Core Layer
    subgraph "Domain/Core Layer"
        TaskManager["TaskManager"]:::core
        ConfigManager["ConfigManager"]:::core
        ArchiveManager["ArchiveManager"]:::core
        DependencyTracker["DependencyTracker"]:::core
        FileCache["FileCache"]:::core
        PerfMonitor["PerfMonitor"]:::core
        ListManager["ListManager"]:::core
        QuickTask["QuickTask"]:::core
        TaskContext["TaskContext"]:::core
        TaskCommit["TaskCommit"]:::core
    end

    %% Integration Layer
    subgraph "Integration Layer"
        AIAdapter["AI Integration Adapter"]:::integration
        AutoTracker["Auto-Tracking Adapter"]:::integration
    end

    %% Reporting Layer
    subgraph "Reporting Layer"
        BurndownChart["BurndownChart"]:::reporting
        StatsTracker["StatsTracker"]:::reporting
        TaskJournal["TaskJournal"]:::reporting
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        JSONStore[".tasktracker (JSON Store)"]:::data
    end

    %% External Services
    subgraph "External Services"
        AIAPI["AI API (OpenAI/Claude)"]:::external
        GitCLI["Git CLI"]:::external
    end

    %% Data Flow
    CLIEntrypoints --> ShellWrappers
    ShellWrappers --> CLIParser
    CLIParser --> CommandRegistry
    CommandRegistry --> CommandHandlers
    CommandHandlers --> TaskManager
    CommandHandlers --> ConfigManager
    CommandHandlers --> ArchiveManager
    CommandHandlers --> DependencyTracker
    CommandHandlers --> FileCache
    CommandHandlers --> PerfMonitor
    CommandHandlers --> ListManager
    CommandHandlers --> QuickTask
    CommandHandlers --> TaskContext
    CommandHandlers --> TaskCommit

    TaskManager --> JSONStore
    ConfigManager --> JSONStore
    ArchiveManager --> JSONStore
    FileCache --> JSONStore
    PerfMonitor --> JSONStore

    TaskManager --> AIAdapter
    DependencyTracker --> GitCLI
    AIAdapter --> AIAPI
    AutoTracker --> GitCLI

    TaskManager --> BurndownChart
    TaskManager --> StatsTracker
    TaskManager --> TaskJournal
    BurndownChart --> CLIEntrypoints
    StatsTracker --> CLIEntrypoints
    TaskJournal --> CLIEntrypoints

    %% Click Events
    click CLIEntrypoints "https://github.com/dvc2/task_tracker/tree/main/bin/"
    click ShellWrappers "https://github.com/dvc2/task_tracker/tree/main/bin/tt"
    click CLIParser "https://github.com/dvc2/task_tracker/blob/main/lib/core/cli-parser.js"
    click CommandRegistry "https://github.com/dvc2/task_tracker/blob/main/lib/commands/index.js"
    click CommandHandlers "https://github.com/dvc2/task_tracker/tree/main/lib/commands/"
    click TaskManager "https://github.com/dvc2/task_tracker/blob/main/lib/core/task-manager.js"
    click ConfigManager "https://github.com/dvc2/task_tracker/blob/main/lib/core/config-manager.js"
    click ArchiveManager "https://github.com/dvc2/task_tracker/blob/main/lib/core/archive-manager.js"
    click DependencyTracker "https://github.com/dvc2/task_tracker/blob/main/lib/core/dependency-tracker.js"
    click FileCache "https://github.com/dvc2/task_tracker/blob/main/lib/core/file-cache.js"
    click PerfMonitor "https://github.com/dvc2/task_tracker/blob/main/lib/core/perf-monitor.js"
    click ListManager "https://github.com/dvc2/task_tracker/blob/main/lib/core/list-manager.js"
    click QuickTask "https://github.com/dvc2/task_tracker/blob/main/lib/core/quick-task.js"
    click TaskContext "https://github.com/dvc2/task_tracker/blob/main/lib/core/task-context.js"
    click TaskCommit "https://github.com/dvc2/task_tracker/blob/main/lib/core/task-commit.js"
    click AIAdapter "https://github.com/dvc2/task_tracker/blob/main/lib/integration/ai-context-cache.js"
    click AutoTracker "https://github.com/dvc2/task_tracker/blob/main/lib/integration/auto-tracker.sh"
    click BurndownChart "https://github.com/dvc2/task_tracker/blob/main/lib/reporting/burndown-chart.js"
    click StatsTracker "https://github.com/dvc2/task_tracker/blob/main/lib/reporting/stats-tracker.js"
    click TaskJournal "https://github.com/dvc2/task_tracker/blob/main/lib/reporting/task-journal.js"
    click JSONStore "https://github.com/dvc2/task_tracker/tree/main/.tasktracker/"

    %% Styles
    classDef frontend fill:#E8F1FA,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef core fill:#F0F4F8,stroke:#1D4E89,color:#1D4E89,stroke-width:1px;
    classDef integration fill:#FFF4E5,stroke:#D9822B,color:#D9822B,stroke-width:1px,stroke-dasharray: 5 5;
    classDef reporting fill:#E6F4EA,stroke:#22863A,color:#22863A,stroke-width:1px;
    classDef data fill:#E6FFFA,stroke:#15847A,color:#0C4A3A,stroke-width:1px,shape:cylinder;
    classDef external fill:#FFF5F5,stroke:#D73A49,color:#D73A49,stroke-width:1px,shape:cloud;
```
