# marcizos/taskflow-pro architecture

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

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

## Overview

TaskFlow Pro is a dependency-aware Kanban planner. Users create and edit tasks, manage prerequisites, move cards across gated workflow columns, and inspect schedules and critical paths; the backend validates graph changes, propagates schedule shifts, derives readiness, and persists the board. A separate AI workflow proposes evidence-checked dependencies for human review. The graph preserves documented capabilities even where implementation excerpts are incomplete; dashed links mark optional integrations. Evidence is limited to the supplied excerpts, source index, and README.

Main entry points: [`frontend/src/App.tsx`](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/App.tsx) (Application shell), [`backend/app/services/board.py`](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/board.py) (Board operations), [`frontend/src/hooks.ts`](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/hooks.ts) (Query and mutations), [`backend/app/services/ai.py`](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/ai.py) (Suggestion validation and decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Application shell<br/>[App.tsx]"]
  node_boardview["Kanban board<br/>[BoardView.tsx]"]
  node_graphview["Dependency graph view<br/>[GraphView.tsx]"]
  node_taskui["Task editing<br/>[TaskDrawer.tsx]"]
  node_newtask["Task creation<br/>[NewTaskDialog.tsx]"]
  node_suggestui["Suggestion review"]
  node_hooks["Query and mutations<br/>[hooks.ts]"]
  node_toast["User notifications<br/>[Toasts.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_domain["Planning services"]
  node_board_service["Board operations<br/>[board.py]"]
  node_engine["Dependency and schedule engine<br/>[graph.py]"]
  node_seed["Demo board seeding<br/>[seed.py]"]
end

subgraph group_assist["AI suggestions"]
  node_ai_service["Suggestion validation and decisions<br/>[ai.py]"]
  node_llm{{"Hosted LLM providers"}}
  node_keyword["Offline keyword model<br/>[ai.py]"]
end

subgraph group_runtime["Runtime and storage"]
  node_api["HTTP API<br/>[api.py]"]
  node_models["Task and dependency records<br/>[models.py]"]
  node_database[("Persistent database")]
  node_db_runtime["Database sessions and locking<br/>[db.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_startup["Application startup<br/>[main.py]"]
end

node_user(("Planner"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_boardview
node_app -->|"renders"| node_graphview
node_app -->|"opens"| node_taskui
node_app -->|"opens"| node_newtask
node_app -->|"opens"| node_suggestui
node_app -->|"loads board"| node_hooks
node_boardview -->|"mutates through"| node_hooks
node_taskui -.->|"mutates through"| node_hooks
node_newtask -.->|"mutates through"| node_hooks
node_suggestui -->|"requests"| node_api_client
node_hooks -->|"requests"| node_api_client
node_hooks -->|"reports results"| node_toast
node_api_client -->|"sends HTTP requests"| node_api
node_api -->|"dispatches board actions"| node_board_service
node_api -->|"dispatches AI actions"| node_ai_service
node_board_service -->|"validates and schedules"| node_engine
node_board_service -.->|"loads and saves"| node_models
node_board_service -->|"locks writes"| node_db_runtime
node_db_runtime -->|"reads settings"| node_config
node_db_runtime -->|"reads and writes"| node_database
node_models -->|"uses ORM base"| node_db_runtime
node_startup -->|"registers routes"| node_api
node_startup -->|"initializes demo"| node_seed
node_startup -.->|"loads board"| node_board_service
node_api -->|"resets demo"| node_seed
node_ai_service -->|"dry-run validates"| node_engine
node_ai_service -.->|"accepts dependency"| node_board_service
node_ai_service -->|"requests proposals"| node_llm
node_ai_service -.->|"uses fallback"| node_keyword

click node_app "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/App.tsx"
click node_boardview "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/BoardView.tsx"
click node_graphview "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/GraphView.tsx"
click node_taskui "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/TaskDrawer.tsx"
click node_newtask "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/NewTaskDialog.tsx"
click node_suggestui "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/SuggestionsPanel.tsx"
click node_hooks "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/hooks.ts"
click node_toast "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/Toasts.tsx"
click node_api_client "https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/api.ts"
click node_api "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/api.py"
click node_board_service "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/board.py"
click node_engine "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/engine/graph.py"
click node_models "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/models.py"
click node_db_runtime "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/db.py"
click node_config "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/config.py"
click node_startup "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/main.py"
click node_seed "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/seed.py"
click node_ai_service "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/ai.py"
click node_keyword "https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/ai.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_app,node_boardview,node_graphview,node_taskui,node_newtask,node_suggestui,node_hooks,node_toast,node_api_client toneBlue
class node_board_service,node_engine,node_seed toneAmber
class node_ai_service,node_llm,node_keyword toneMint
class node_api,node_models,node_database,node_db_runtime,node_config,node_startup toneRose
class node_user toneIndigo
```

## Components

### Web application

- [Application shell](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Kanban board](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/BoardView.tsx): `frontend/src/components/BoardView.tsx`
- [Dependency graph view](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/GraphView.tsx): `frontend/src/components/GraphView.tsx`
- [Task editing](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/TaskDrawer.tsx): `frontend/src/components/TaskDrawer.tsx`
- [Task creation](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/NewTaskDialog.tsx): `frontend/src/components/NewTaskDialog.tsx`
- [Suggestion review](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/SuggestionsPanel.tsx): `frontend/src/components/SuggestionsPanel.tsx`
- [Query and mutations](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/hooks.ts): `frontend/src/hooks.ts`
- [User notifications](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/components/Toasts.tsx): `frontend/src/components/Toasts.tsx`
- [API client](https://github.com/marcizos/taskflow-pro/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Planning services

- [Board operations](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/board.py): `backend/app/services/board.py`
- [Dependency and schedule engine](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/engine/graph.py): `backend/app/engine/graph.py`
- [Demo board seeding](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/seed.py): `backend/app/seed.py`

### AI suggestions

- [Suggestion validation and decisions](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/ai.py): `backend/app/services/ai.py`
- **Hosted LLM providers**
- [Offline keyword model](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/services/ai.py): `backend/app/services/ai.py`

### Runtime and storage

- [HTTP API](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/api.py): `backend/app/api.py`
- [Task and dependency records](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/models.py): `backend/app/models.py`
- **Persistent database**
- [Database sessions and locking](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/db.py): `backend/app/db.py`
- [Runtime configuration](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/config.py): `backend/app/config.py`
- [Application startup](https://github.com/marcizos/taskflow-pro/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Planner**

## Connections

- Planner → Application shell: uses (evidence: `README.md`)
- Application shell → Kanban board: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Dependency graph view: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Task editing: opens (evidence: `frontend/src/App.tsx`)
- Application shell → Task creation: opens (evidence: `frontend/src/App.tsx`)
- Application shell → Suggestion review: opens (evidence: `frontend/src/App.tsx`)
- Application shell → Query and mutations: loads board (evidence: `frontend/src/App.tsx`)
- Kanban board → Query and mutations: mutates through (evidence: `frontend/src/components/BoardView.tsx`)
- Task editing → Query and mutations: mutates through (evidence: `frontend/src/components/TaskDrawer.tsx`)
- Task creation → Query and mutations: mutates through (evidence: `frontend/src/components/NewTaskDialog.tsx`)
- Suggestion review → API client: requests (evidence: `frontend/src/components/SuggestionsPanel.tsx`)
- Query and mutations → API client: requests (evidence: `frontend/src/hooks.ts`)
- Query and mutations → User notifications: reports results (evidence: `frontend/src/hooks.ts`)
- API client → HTTP API: sends HTTP requests (evidence: `README.md`)
- HTTP API → Board operations: dispatches board actions (evidence: `backend/app/api.py`)
- HTTP API → Suggestion validation and decisions: dispatches AI actions (evidence: `backend/app/api.py`)
- Board operations → Dependency and schedule engine: validates and schedules (evidence: `backend/app/services/board.py`)
- Board operations → Task and dependency records: loads and saves (evidence: `backend/app/services/board.py`)
- Board operations → Database sessions and locking: locks writes (evidence: `backend/app/services/board.py`)
- Database sessions and locking → Runtime configuration: reads settings (evidence: `backend/app/db.py`)
- Database sessions and locking → Persistent database: reads and writes (evidence: `backend/app/db.py`)
- Task and dependency records → Database sessions and locking: uses ORM base (evidence: `backend/app/models.py`)
- Application startup → HTTP API: registers routes (evidence: `backend/app/main.py`)
- Application startup → Demo board seeding: initializes demo (evidence: `backend/app/main.py`)
- Application startup → Board operations: loads board (evidence: `backend/app/main.py`)
- HTTP API → Demo board seeding: resets demo (evidence: `backend/app/api.py`)
- Suggestion validation and decisions → Dependency and schedule engine: dry-run validates (evidence: `backend/app/services/ai.py`)
- Suggestion validation and decisions → Board operations: accepts dependency (evidence: `backend/app/services/ai.py`)
- Suggestion validation and decisions → Hosted LLM providers: requests proposals (evidence: `backend/app/services/ai.py`)
- Suggestion validation and decisions → Offline keyword model: uses fallback (evidence: `README.md`)
