# ameshsenanayaka/taskflow-ai architecture

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

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

## Overview

TaskFlow AI is a single-user task manager with a Next.js dashboard, Spring REST API, PostgreSQL persistence, and both a direct TaskAgent and a multi-agent assistant. The main workflow runs from a user action through frontend pages and API calls to backend services and task storage; assistant requests can instead be routed by the supervisor to task-management or read-only analysis agents. README documentation supplies several product-level links; source excerpts and the index support the backend service and tool relationships. Unsampled frontend wiring and agent internals are not inferred beyond those documented capabilities.

Main entry points: [`backend/src/main/java/com/taskflow/ai/agent/TaskFlowSupervisor.java`](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/TaskFlowSupervisor.java) (Supervisor), [`backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java`](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java) (Read-only tools), [`backend/src/main/java/com/taskflow/service/TaskService.java`](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/service/TaskService.java) (Task rules), [`frontend/lib/api/client.ts`](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/frontend/lib/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_pages["App pages"]
  node_task_ui["Task views"]
  node_assistant_ui["Assistant chat<br/>[assistant-chat.tsx]"]
  node_frontend_api["API client<br/>[client.ts]"]
end

subgraph group_api["REST and domain"]
  node_task_api["Task endpoints"]
  node_ai_api["AI endpoints"]
  node_task_service["Task rules<br/>[TaskService.java]"]
  node_dashboard["Dashboard stats"]
  node_preferences["User preferences"]
  node_task_model["Task model<br/>[Task.java]"]
end

subgraph group_assistant["AI assistant"]
  node_task_agent["TaskAgent<br/>[TaskAgent.java]"]
  node_supervisor["Supervisor"]
  node_multi_service["Multi-agent service"]
  node_task_tools["Task tools<br/>[TaskTools.java]"]
  node_query_tools["Read-only tools"]
  node_priority_agent["Priority agent<br/>[PriorityAgent.java]"]
  node_planning_agent["Planning agent<br/>[PlanningAgent.java]"]
  node_summary_agent["Summary agent<br/>[SummaryAgent.java]"]
end

subgraph group_storage["Persistence"]
  node_task_repo["Task repository"]
  node_preferences_repo["Preferences repository"]
  node_postgres[("PostgreSQL")]
end

node_user(("User"))
node_openai{{"OpenAI"}}

node_user -->|"uses"| node_pages
node_pages -->|"renders"| node_task_ui
node_pages -->|"opens"| node_assistant_ui
node_task_ui -->|"requests data"| node_frontend_api
node_assistant_ui -->|"sends chat"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_task_api
node_frontend_api -->|"HTTP requests"| node_ai_api
node_task_api -->|"delegates"| node_task_service
node_task_service -->|"reads and writes"| node_task_repo
node_task_service -->|"maps tasks"| node_task_model
node_task_repo -->|"persists"| node_postgres
node_dashboard -->|"counts tasks"| node_task_repo
node_dashboard -->|"gets today"| node_preferences
node_preferences -->|"loads and saves"| node_preferences_repo
node_preferences_repo -->|"persists"| node_postgres
node_ai_api -->|"invokes chat"| node_task_agent
node_ai_api -->|"delegates supervisor"| node_multi_service
node_multi_service -->|"runs"| node_supervisor
node_supervisor -->|"routes requests"| node_task_agent
node_supervisor -->|"routes requests"| node_priority_agent
node_supervisor -->|"routes requests"| node_planning_agent
node_supervisor -->|"routes requests"| node_summary_agent
node_task_agent -->|"calls tools"| node_task_tools
node_task_tools -->|"calls service"| node_task_service
node_priority_agent -->|"uses read tools"| node_query_tools
node_planning_agent -->|"uses read tools"| node_query_tools
node_summary_agent -->|"uses read tools"| node_query_tools
node_query_tools -->|"lists tasks"| node_task_service
node_query_tools -->|"gets statistics"| node_dashboard
node_query_tools -->|"gets context"| node_preferences
node_task_agent -->|"calls model"| node_openai
node_supervisor -->|"plans routing"| node_openai

click node_pages "https://github.com/ameshsenanayaka/taskflow-ai/tree/main/frontend/app"
click node_task_ui "https://github.com/ameshsenanayaka/taskflow-ai/tree/main/frontend/components/tasks"
click node_assistant_ui "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/frontend/components/assistant/assistant-chat.tsx"
click node_frontend_api "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/frontend/lib/api/client.ts"
click node_task_api "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/controller/TaskController.java"
click node_ai_api "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/controller/AiChatController.java"
click node_task_service "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/service/TaskService.java"
click node_dashboard "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/service/DashboardService.java"
click node_preferences "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/service/PreferencesService.java"
click node_task_model "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/entity/Task.java"
click node_task_repo "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/repository/TaskRepository.java"
click node_preferences_repo "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/repository/PreferencesRepository.java"
click node_task_agent "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/TaskAgent.java"
click node_supervisor "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/TaskFlowSupervisor.java"
click node_multi_service "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/service/MultiAgentService.java"
click node_task_tools "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/tool/TaskTools.java"
click node_query_tools "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java"
click node_priority_agent "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/PriorityAgent.java"
click node_planning_agent "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/PlanningAgent.java"
click node_summary_agent "https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/SummaryAgent.java"

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_pages,node_task_ui,node_assistant_ui,node_frontend_api,node_user toneBlue
class node_task_api,node_ai_api,node_task_service,node_dashboard,node_preferences,node_task_model toneAmber
class node_task_agent,node_supervisor,node_multi_service,node_task_tools,node_query_tools,node_priority_agent,node_planning_agent,node_summary_agent toneMint
class node_task_repo,node_preferences_repo,node_postgres toneRose
class node_openai toneIndigo
```

## Components

### Web application

- [App pages](https://github.com/ameshsenanayaka/taskflow-ai/tree/main/frontend/app): `frontend/app`
- [Task views](https://github.com/ameshsenanayaka/taskflow-ai/tree/main/frontend/components/tasks): `frontend/components/tasks`
- [Assistant chat](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/frontend/components/assistant/assistant-chat.tsx): `frontend/components/assistant/assistant-chat.tsx`
- [API client](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`

### REST and domain

- [Task endpoints](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/controller/TaskController.java): `backend/src/main/java/com/taskflow/controller/TaskController.java`
- [AI endpoints](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/controller/AiChatController.java): `backend/src/main/java/com/taskflow/controller/AiChatController.java`
- [Task rules](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/service/TaskService.java): `backend/src/main/java/com/taskflow/service/TaskService.java`
- [Dashboard stats](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/service/DashboardService.java): `backend/src/main/java/com/taskflow/service/DashboardService.java`
- [User preferences](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/service/PreferencesService.java): `backend/src/main/java/com/taskflow/service/PreferencesService.java`
- [Task model](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/entity/Task.java): `backend/src/main/java/com/taskflow/entity/Task.java`

### AI assistant

- [TaskAgent](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/TaskAgent.java): `backend/src/main/java/com/taskflow/ai/agent/TaskAgent.java`
- [Supervisor](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/TaskFlowSupervisor.java): `backend/src/main/java/com/taskflow/ai/agent/TaskFlowSupervisor.java`
- [Multi-agent service](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/service/MultiAgentService.java): `backend/src/main/java/com/taskflow/ai/service/MultiAgentService.java`
- [Task tools](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/tool/TaskTools.java): `backend/src/main/java/com/taskflow/ai/tool/TaskTools.java`
- [Read-only tools](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java): `backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java`
- [Priority agent](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/PriorityAgent.java): `backend/src/main/java/com/taskflow/ai/agent/PriorityAgent.java`
- [Planning agent](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/PlanningAgent.java): `backend/src/main/java/com/taskflow/ai/agent/PlanningAgent.java`
- [Summary agent](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/ai/agent/SummaryAgent.java): `backend/src/main/java/com/taskflow/ai/agent/SummaryAgent.java`

### Persistence

- [Task repository](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/repository/TaskRepository.java): `backend/src/main/java/com/taskflow/repository/TaskRepository.java`
- [Preferences repository](https://github.com/ameshsenanayaka/taskflow-ai/blob/main/backend/src/main/java/com/taskflow/repository/PreferencesRepository.java): `backend/src/main/java/com/taskflow/repository/PreferencesRepository.java`
- **PostgreSQL**

### Other components

- **User**
- **OpenAI**

## Connections

- User → App pages: uses (evidence: `README.md`)
- App pages → Task views: renders (evidence: `README.md`)
- App pages → Assistant chat: opens (evidence: `README.md`)
- Task views → API client: requests data (evidence: `README.md`)
- Assistant chat → API client: sends chat (evidence: `README.md`)
- API client → Task endpoints: HTTP requests (evidence: `README.md`)
- API client → AI endpoints: HTTP requests (evidence: `README.md`)
- Task endpoints → Task rules: delegates (evidence: `backend/src/main/java/com/taskflow/controller/TaskController.java`)
- Task rules → Task repository: reads and writes (evidence: `backend/src/main/java/com/taskflow/service/TaskService.java`)
- Task rules → Task model: maps tasks (evidence: `backend/src/main/java/com/taskflow/service/TaskService.java`)
- Task repository → PostgreSQL: persists (evidence: `README.md`)
- Dashboard stats → Task repository: counts tasks (evidence: `backend/src/main/java/com/taskflow/service/DashboardService.java`)
- Dashboard stats → User preferences: gets today (evidence: `backend/src/main/java/com/taskflow/service/DashboardService.java`)
- User preferences → Preferences repository: loads and saves (evidence: `backend/src/main/java/com/taskflow/service/PreferencesService.java`)
- Preferences repository → PostgreSQL: persists (evidence: `README.md`)
- AI endpoints → TaskAgent: invokes chat (evidence: `backend/src/main/java/com/taskflow/controller/AiChatController.java`)
- AI endpoints → Multi-agent service: delegates supervisor (evidence: `backend/src/main/java/com/taskflow/controller/AiChatController.java`)
- Multi-agent service → Supervisor: runs (evidence: `backend/src/main/java/com/taskflow/ai/service/MultiAgentService.java`)
- Supervisor → TaskAgent: routes requests (evidence: `README.md`)
- Supervisor → Priority agent: routes requests (evidence: `README.md`)
- Supervisor → Planning agent: routes requests (evidence: `README.md`)
- Supervisor → Summary agent: routes requests (evidence: `README.md`)
- TaskAgent → Task tools: calls tools (evidence: `README.md`)
- Task tools → Task rules: calls service (evidence: `README.md`)
- Priority agent → Read-only tools: uses read tools (evidence: `README.md`)
- Planning agent → Read-only tools: uses read tools (evidence: `README.md`)
- Summary agent → Read-only tools: uses read tools (evidence: `README.md`)
- Read-only tools → Task rules: lists tasks (evidence: `backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java`)
- Read-only tools → Dashboard stats: gets statistics (evidence: `backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java`)
- Read-only tools → User preferences: gets context (evidence: `backend/src/main/java/com/taskflow/ai/tool/TaskQueryTools.java`)
- TaskAgent → OpenAI: calls model (evidence: `README.md`)
- Supervisor → OpenAI: plans routing (evidence: `README.md`)
