# mohith535/taskflow architecture

> Architecture diagram of the GitHub repository mohith535/taskflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohith535/taskflow
- Repository: https://github.com/mohith535/taskflow

## Overview

TaskFlow is an offline, CLI-first task execution system, with a web dashboard and a Textual terminal UI. The principal workflow is capture or manage tasks, persist them, then choose a prioritized action for today and optionally enter a timed focus session with distraction blocking. Task records also support enrichment, deadlines, recovery and progress history. The README documents reminder, momentum, overdue-candidate and recovery capabilities; these are represented at the command layer because their finer implementation paths were not sampled. Edges reflect shown imports/calls or README descriptions; uncertain unsampled subsystem links are omitted.

Main entry points: [`task_manager/commands.py`](https://github.com/mohith535/taskflow/blob/main/task_manager/commands.py) (Task workflows), [`task_manager/system_detector.py`](https://github.com/mohith535/taskflow/blob/main/task_manager/system_detector.py) (Platform selection), [`task_manager/storage.py`](https://github.com/mohith535/taskflow/blob/main/task_manager/storage.py) (Local task storage), [`task_manager/server.py`](https://github.com/mohith535/taskflow/blob/main/task_manager/server.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_tui["Terminal UI<br/>[cascade.py]"]
  node_palette["Momentum palette<br/>[palette.py]"]
end

subgraph group_workflow["Task execution"]
  node_commands["Task workflows<br/>[commands.py]"]
  node_sync["Task sync<br/>[sync.py]"]
  node_recovery["Recovery and overdue<br/>[commands.py]"]
end

subgraph group_state["Task state"]
  node_task_model["Task model<br/>[models.py]"]
  node_storage[("Local task storage<br/>[storage.py]")]
end

subgraph group_focus["Focus defense"]
  node_detector["Platform selection<br/>[system_detector.py]"]
  node_blocker_base["Blocker framework<br/>[base.py]"]
  node_gentle["Gentle reminders<br/>[gentle.py]"]
  node_windows["Windows blocking<br/>[windows.py]"]
  node_proxy["Local filter proxy<br/>[proxy_filter.py]"]
  node_blocklist["Distraction lists<br/>[blocklist.py]"]
  node_macos["macOS blocker<br/>[macos.py]"]
  node_linux["Linux blocker<br/>[linux.py]"]
end

subgraph group_web["Web dashboard"]
  node_http["HTTP API<br/>[server.py]"]
  node_dashboard["Web dashboard<br/>[dashboard.js]"]
  node_web_view["Dashboard template<br/>[web_ui.py]"]
end

node_user(("User"))

node_user -->|"issues commands"| node_cli
node_cli -->|"dispatches"| node_commands
node_cli -->|"loads config"| node_storage
node_cli -->|"checks platform"| node_detector
node_user -->|"opens UI"| node_tui
node_tui -->|"loads tasks"| node_storage
node_tui -->|"styles tasks"| node_palette
node_user -->|"uses dashboard"| node_http
node_http -->|"serves template"| node_web_view
node_dashboard -.->|"sends requests"| node_http
node_http -->|"dispatches actions"| node_commands
node_http -->|"reads tasks"| node_storage
node_commands -->|"persists tasks"| node_storage
node_storage -->|"deserializes"| node_task_model
node_commands -->|"uses task records"| node_task_model
node_commands -.->|"offers sync"| node_sync
node_commands -->|"selects blocker"| node_detector
node_detector -->|"selects fallback"| node_gentle
node_detector -->|"selects platform blocker"| node_windows
node_detector -->|"selects platform blocker"| node_macos
node_detector -->|"selects platform blocker"| node_linux
node_gentle -->|"extends"| node_blocker_base
node_windows -->|"extends"| node_blocker_base
node_windows -->|"starts proxy"| node_proxy
node_proxy -->|"uses data directory"| node_storage
node_commands -->|"loads blocklist"| node_blocklist
node_commands -->|"handles recovery"| node_recovery
node_commands -->|"surfaces candidates"| node_recovery

click node_cli "https://github.com/mohith535/taskflow/blob/main/taskflow/cli.py"
click node_tui "https://github.com/mohith535/taskflow/blob/main/taskflow/ui/cascade.py"
click node_http "https://github.com/mohith535/taskflow/blob/main/task_manager/server.py"
click node_dashboard "https://github.com/mohith535/taskflow/blob/main/task_manager/static/dashboard.js"
click node_web_view "https://github.com/mohith535/taskflow/blob/main/task_manager/web_ui.py"
click node_task_model "https://github.com/mohith535/taskflow/blob/main/task_manager/models.py"
click node_storage "https://github.com/mohith535/taskflow/blob/main/task_manager/storage.py"
click node_commands "https://github.com/mohith535/taskflow/blob/main/task_manager/commands.py"
click node_sync "https://github.com/mohith535/taskflow/blob/main/task_manager/sync.py"
click node_detector "https://github.com/mohith535/taskflow/blob/main/task_manager/system_detector.py"
click node_blocker_base "https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/base.py"
click node_gentle "https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/gentle.py"
click node_windows "https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/windows.py"
click node_proxy "https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/proxy_filter.py"
click node_blocklist "https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/blocklist.py"
click node_macos "https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/macos.py"
click node_linux "https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/linux.py"
click node_palette "https://github.com/mohith535/taskflow/blob/main/taskflow/ui/palette.py"
click node_recovery "https://github.com/mohith535/taskflow/blob/main/task_manager/commands.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_tui,node_palette,node_user toneBlue
class node_commands,node_sync,node_recovery toneAmber
class node_task_model,node_storage toneMint
class node_detector,node_blocker_base,node_gentle,node_windows,node_proxy,node_blocklist,node_macos,node_linux toneRose
class node_http,node_dashboard,node_web_view toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/mohith535/taskflow/blob/main/taskflow/cli.py): `taskflow/cli.py`
- [Terminal UI](https://github.com/mohith535/taskflow/blob/main/taskflow/ui/cascade.py): `taskflow/ui/cascade.py`
- [Momentum palette](https://github.com/mohith535/taskflow/blob/main/taskflow/ui/palette.py): `taskflow/ui/palette.py`

### Task execution

- [Task workflows](https://github.com/mohith535/taskflow/blob/main/task_manager/commands.py): `task_manager/commands.py`
- [Task sync](https://github.com/mohith535/taskflow/blob/main/task_manager/sync.py): `task_manager/sync.py`
- [Recovery and overdue](https://github.com/mohith535/taskflow/blob/main/task_manager/commands.py): `task_manager/commands.py`

### Task state

- [Task model](https://github.com/mohith535/taskflow/blob/main/task_manager/models.py): `task_manager/models.py`
- [Local task storage](https://github.com/mohith535/taskflow/blob/main/task_manager/storage.py): `task_manager/storage.py`

### Focus defense

- [Platform selection](https://github.com/mohith535/taskflow/blob/main/task_manager/system_detector.py): `task_manager/system_detector.py`
- [Blocker framework](https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/base.py): `task_manager/blockers/base.py`
- [Gentle reminders](https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/gentle.py): `task_manager/blockers/gentle.py`
- [Windows blocking](https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/windows.py): `task_manager/blockers/windows.py`
- [Local filter proxy](https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/proxy_filter.py): `task_manager/blockers/proxy_filter.py`
- [Distraction lists](https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/blocklist.py): `task_manager/blockers/blocklist.py`
- [macOS blocker](https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/macos.py): `task_manager/blockers/macos.py`
- [Linux blocker](https://github.com/mohith535/taskflow/blob/main/task_manager/blockers/linux.py): `task_manager/blockers/linux.py`

### Web dashboard

- [HTTP API](https://github.com/mohith535/taskflow/blob/main/task_manager/server.py): `task_manager/server.py`
- [Web dashboard](https://github.com/mohith535/taskflow/blob/main/task_manager/static/dashboard.js): `task_manager/static/dashboard.js`
- [Dashboard template](https://github.com/mohith535/taskflow/blob/main/task_manager/web_ui.py): `task_manager/web_ui.py`

### Other components

- **User**

## Connections

- User → CLI commands: issues commands (evidence: `README.md`)
- CLI commands → Task workflows: dispatches (evidence: `taskflow/cli.py`)
- CLI commands → Local task storage: loads config (evidence: `taskflow/cli.py`)
- CLI commands → Platform selection: checks platform (evidence: `taskflow/cli.py`)
- User → Terminal UI: opens UI (evidence: `README.md`)
- Terminal UI → Local task storage: loads tasks (evidence: `taskflow/ui/cascade.py`)
- Terminal UI → Momentum palette: styles tasks (evidence: `taskflow/ui/cascade.py`)
- User → HTTP API: uses dashboard (evidence: `README.md`)
- HTTP API → Dashboard template: serves template (evidence: `task_manager/server.py`)
- Web dashboard → HTTP API: sends requests
- HTTP API → Task workflows: dispatches actions (evidence: `task_manager/server.py`)
- HTTP API → Local task storage: reads tasks (evidence: `task_manager/server.py`)
- Task workflows → Local task storage: persists tasks (evidence: `task_manager/commands.py`)
- Local task storage → Task model: deserializes (evidence: `task_manager/storage.py`)
- Task workflows → Task model: uses task records (evidence: `task_manager/commands.py`)
- Task workflows → Task sync: offers sync (evidence: `task_manager/commands.py`)
- Task workflows → Platform selection: selects blocker (evidence: `task_manager/commands.py`)
- Platform selection → Gentle reminders: selects fallback (evidence: `task_manager/system_detector.py`)
- Platform selection → Windows blocking: selects platform blocker (evidence: `task_manager/system_detector.py`)
- Platform selection → macOS blocker: selects platform blocker (evidence: `task_manager/system_detector.py`)
- Platform selection → Linux blocker: selects platform blocker (evidence: `task_manager/system_detector.py`)
- Gentle reminders → Blocker framework: extends (evidence: `task_manager/blockers/gentle.py`)
- Windows blocking → Blocker framework: extends (evidence: `task_manager/blockers/windows.py`)
- Windows blocking → Local filter proxy: starts proxy (evidence: `task_manager/blockers/windows.py`)
- Local filter proxy → Local task storage: uses data directory (evidence: `task_manager/blockers/proxy_filter.py`)
- Task workflows → Distraction lists: loads blocklist (evidence: `task_manager/commands.py`)
- Task workflows → Recovery and overdue: handles recovery (evidence: `README.md`)
- Task workflows → Recovery and overdue: surfaces candidates (evidence: `README.md`)
