# alimgiray/tasks architecture

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

- Interactive diagram: https://gitdiagram.com/alimgiray/tasks
- Repository: https://github.com/alimgiray/tasks

## Overview

##### Project Type and Purpose
- This is a Go‐based, command‐line TUI (text‐user interface) application for tracking tasks.
- It uses CharmBracelet’s BubbleTea library for its UI (under src/views).
- It persists data via a local database and applies migrations at startup.

##### Out the Key Packages (Top‐Level Components)
1) cmd
– Entry point (main.go)
– Responsible for wiring together subsystems and launching the TUI.
2) src/database
– `database.go`: DB connection & query helpers
– `migration.go`: runs migrations on startup
– `project.go`/`task.go`: CRUD operations
3) src/migrations
– Organized migration files (0000_…, 0001_…, etc.)
– Migration runner that applies schema changes
4) src/models
– Domain objects: Project, Task
– Pure data structures (no I/O)
5) src/views
– BubbleTea models, views, cursors, and layout components (dashboard, project panes, headers, footers)
– Handles user input, rendering, and state transitions

##### Relationships & Data Flows
- Startup sequence:
cmd/main.go → initialize database connection (`src/database/database.go`) → run migrations (`src/database/migration.go` + `src/migrations`) → load initial data (`src/database/project.go`, `task.go`) → initialize BubbleTea TUI (`src/views`)
- Runtime interaction:
User keystroke → BubbleTea event loop (`views/cursor.go`, `views/dashboard.go`…) → maps to command (e.g., create task) → call into database layer → update model → views re‐render
- Persistence layer:
src/database ←→ underlying SQL store (e.g., SQLite file)

##### Architectural Patterns & Principles
- Clear separation of concerns:
– Presentation (views)
– Domain (models)
– Persistence (database + migrations)
– Orchestration/entry (cmd)
- MVC‐like flow inside TUI:
– Model = domain objects + view state
– View = BubbleTea rendering components
– Controller = BubbleTea update functions reading input & invoking DB
- Migration‐based schema evolution

– [ ] Clear labels for all packages and runtime modules
– [ ] Annotation of key files or functions (e.g., main.go, migration runner)
– [ ] External library (BubbleTea) flagged

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Layer
    subgraph "Entry Layer"
        CLI["CLI Entrypoint\n(cmd/main.go)"]:::entry
    end

    %% Migration Subsystem
    subgraph "Migration Subsystem"
        MIG_RUNNER["Migration Runner\n(src/migrations/migration.go)"]:::migration
        MIG_FILES["Migration Files\n(0000, 0001, 0002, migrations.go)"]:::migration
    end

    %% Database Layer
    subgraph "Database Layer"
        DB_CONN["Database Connection\n(src/database/database.go)"]:::database
        DB_MIG["DB Migration\n(src/database/migration.go)"]:::database
        DB_PROJ["Project CRUD\n(src/database/project.go)"]:::database
        DB_TASK["Task CRUD\n(src/database/task.go)"]:::database
    end

    %% Domain Models
    subgraph "Domain Models"
        DM_PROJ["Project Model\n(src/models/project.go)"]:::domain
        DM_TASK["Task Model\n(src/models/task.go)"]:::domain
    end

    %% TUI Layer
    subgraph "TUI Layer"
        UI_CURSOR["Cursor Handler\n(src/views/cursor.go)"]:::ui
        UI_DASH["Dashboard\n(src/views/dashboard.go)"]:::ui
        UI_COL["Dashboard Column\n(src/views/dashboard_column.go)"]:::ui
        UI_HEAD["Dashboard Header\n(src/views/dashboard_header.go)"]:::ui
        UI_FOOT["Dashboard Footer\n(src/views/dashboard_footer.go)"]:::ui
        UI_STAT["Status Bar\n(src/views/dashboard_status.go)"]:::ui
        UI_PROJ_VIEW["Project View\n(src/views/project.go)"]:::ui
        UI_PROJ_HEAD["Project Header\n(src/views/project_header.go)"]:::ui
        UI_PROJ_FOOT["Project Footer\n(src/views/project_footer.go)"]:::ui
    end

    %% External & Persistence
    BubbleTea["BubbleTea Library"]:::external
    Store["Persistent Store\n(SQLite File)"]:::persist

    %% Startup Flow
    CLI -->|"init DB"| DB_CONN
    CLI -->|"run migrations"| MIG_RUNNER
    CLI -->|"start TUI"| UI_DASH

    MIG_RUNNER -->|"loads files"| MIG_FILES
    MIG_RUNNER -->|"apply via"| DB_MIG
    DB_MIG -->|"sets up"| DB_CONN

    DB_CONN -->|"open"| Store

    %% Runtime Flow
    BubbleTea -.->|"UI loop"| UI_DASH
    UI_DASH -->|"CRUD calls"| DB_PROJ
    UI_DASH -->|"CRUD calls"| DB_TASK
    DB_PROJ -->|"uses"| DM_PROJ
    DB_TASK -->|"uses"| DM_TASK
    UI_DASH -->|"renders"| DM_PROJ
    UI_DASH -->|"renders"| DM_TASK
    UI_CURSOR --> UI_DASH
    UI_COL --> UI_DASH
    UI_HEAD --> UI_DASH
    UI_FOOT --> UI_DASH
    UI_STAT --> UI_DASH
    UI_PROJ_VIEW --> UI_DASH
    UI_PROJ_HEAD --> UI_PROJ_VIEW
    UI_PROJ_FOOT --> UI_PROJ_VIEW

    %% Domain references
    UI_DASH -->|"domain use"| DM_PROJ
    UI_DASH -->|"domain use"| DM_TASK

    %% Click Events
    click CLI "https://github.com/alimgiray/tasks/blob/main/cmd/main.go"
    click DB_CONN "https://github.com/alimgiray/tasks/blob/main/src/database/database.go"
    click DB_MIG "https://github.com/alimgiray/tasks/blob/main/src/database/migration.go"
    click DB_PROJ "https://github.com/alimgiray/tasks/blob/main/src/database/project.go"
    click DB_TASK "https://github.com/alimgiray/tasks/blob/main/src/database/task.go"
    click MIG_RUNNER "https://github.com/alimgiray/tasks/blob/main/src/migrations/migration.go"
    click MIG_FILES "https://github.com/alimgiray/tasks/blob/main/src/migrations/0000_migration_create.go"
    click MIG_FILES "https://github.com/alimgiray/tasks/blob/main/src/migrations/0001_projects_create.go"
    click MIG_FILES "https://github.com/alimgiray/tasks/blob/main/src/migrations/0002_tasks_create.go"
    click MIG_FILES "https://github.com/alimgiray/tasks/blob/main/src/migrations/migrations.go"
    click DM_PROJ "https://github.com/alimgiray/tasks/blob/main/src/models/project.go"
    click DM_TASK "https://github.com/alimgiray/tasks/blob/main/src/models/task.go"
    click UI_CURSOR "https://github.com/alimgiray/tasks/blob/main/src/views/cursor.go"
    click UI_DASH "https://github.com/alimgiray/tasks/blob/main/src/views/dashboard.go"
    click UI_COL "https://github.com/alimgiray/tasks/blob/main/src/views/dashboard_column.go"
    click UI_HEAD "https://github.com/alimgiray/tasks/blob/main/src/views/dashboard_header.go"
    click UI_FOOT "https://github.com/alimgiray/tasks/blob/main/src/views/dashboard_footer.go"
    click UI_STAT "https://github.com/alimgiray/tasks/blob/main/src/views/dashboard_status.go"
    click UI_PROJ_VIEW "https://github.com/alimgiray/tasks/blob/main/src/views/project.go"
    click UI_PROJ_HEAD "https://github.com/alimgiray/tasks/blob/main/src/views/project_header.go"
    click UI_PROJ_FOOT "https://github.com/alimgiray/tasks/blob/main/src/views/project_footer.go"

    %% Styles
    classDef entry fill:#f9d19c,stroke:#f08d58,color:#333
    classDef migration fill:#e0f7fa,stroke:#26c6da,color:#006064
    classDef database fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef domain fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef external fill:#eeeeee,stroke:#757575,color:#424242,stroke-dasharray: 5 5
    classDef persist fill:#d7ccc8,stroke:#8d6e63,color:#3e2723,shape:cylinder
```
