# imsudipcreator/task-pilot architecture

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

- Interactive diagram: https://gitdiagram.com/imsudipcreator/task-pilot
- Repository: https://github.com/imsudipcreator/task-pilot

## Overview

1. **Overall shape**
   This is a Python command bot with two major interaction paths: regular command handlers for bot features, and an AI-assisted path that can invoke tools. The repo is organized around chat-command entrypoints, SQLite-backed persistence, and a small utility layer for time/reminder logic.

2. **Entry point and routing**
   `main.py` is the process entrypoint. It likely initializes the bot runtime, wires up handlers, opens the database layer, and starts the event loop that receives incoming user messages/commands.

3. **Command handling boundary**
   The `handlers/` package is the main request-routing layer. It separates user-facing commands into dedicated modules:
   - `start.py` and `help.py` for onboarding and usage
   - `todo.py` for task management
   - `remind.py` for reminder commands
   - `qr.py` for QR-related functionality
   - `ai.py` for AI/chat interactions
   - `unknown.py` for fallback handling of unrecognized input  
   This is the main boundary between inbound messages and internal business logic.

4. **AI subsystem**
   The `ai/` package is a second major subsystem. `ai/agent.py` likely contains the conversational agent orchestration, while `ai/checkpointer.py` handles persistence of agent state across turns. This indicates the bot is not stateless: conversation context and tool-usage state are stored and restored.

5. **AI tool layer**
   `ai/tools/` contains callable capabilities exposed to the agent:
   - `todo.py`
   - `remind.py`
   - `time.py`
   - `web_search.py`
   - `wiki.py`  
   These tools form the agent’s “action layer,” letting it fetch information, reason about time, and manipulate user tasks/reminders instead of only generating text.

6. **Persistent data stores**
   The `data/` directory contains three SQLite databases:
   - `bot.db` for core bot/application data
   - `agent_memory.db` for AI memory or conversation-related persistence
   - `checkpoints.db` for agent checkpoint/state recovery  
   The separation suggests different persistence concerns are intentionally isolated.

7. **Shared database access**
   `database.py` is the common database abstraction or connection manager used by handlers and tools. It likely centralizes schema access, CRUD operations, and connections to the SQLite files under `data/`.

8. **Reminder and time utilities**
   `utils/parse_time.py` and `utils/reminder.py` are shared support code for interpreting human-friendly times like `10m` and `1h`, and for turning them into scheduled reminder behavior. This sits between the reminder command handler and persistence/scheduling logic.

9. **Cross-cutting concerns**
   `decorators.py` likely provides reusable wrappers for handler behavior such as validation, error handling, auth, or logging. This is a shared layer used to keep handler modules thin and consistent.

10. **Repository/runtime tooling**
    The project is managed as a Python application (`pyproject.toml`, `requirements.txt`, `uv.lock`, `.python-version`). That suggests a local Python runtime with dependency lockfile-driven installs, rather than a container-first or framework-heavy setup.

11. **Primary data flow**
    A typical flow is: user message → `main.py` dispatch → specific handler in `handlers/` → database/helper utilities. For AI-driven requests, the flow becomes: user message → `handlers/ai.py` → `ai/agent.py` → tool call in `ai/tools/*` → persistence via `database.py` and `ai/checkpointer.py` → response back to the user.

12. **External integration boundary**
    The only obvious external-facing integrations are the AI/web-information tools (`web_search.py`, `wiki.py`) and whatever chat platform the bot runs on. Everything else is internal application logic or local persistence.

13. **What to show in an architecture diagram**
    The clearest diagram would place the bot runtime at the top, split into:
    - command handlers
    - AI agent/tool subsystem
    - shared utilities/database layer
    - SQLite persistence  
    and show the AI path separately from the direct command path, with reminders/todos as shared capabilities used by both.

Main entry points: [`ai/agent.py`](https://github.com/imsudipcreator/task-pilot/blob/main/ai/agent.py) (Agent), [`main.py`](https://github.com/imsudipcreator/task-pilot/blob/main/main.py) (Main), [`database.py`](https://github.com/imsudipcreator/task-pilot/blob/main/database.py) (Database), [`handlers/remind.py`](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/remind.py) (Remind)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
  node_handlers_ai["AI Handler<br/>command route<br/>[ai.py]"]
  node_handlers_start["Start<br/>command route<br/>[start.py]"]
  node_handlers_help["Help<br/>command route<br/>[help.py]"]
  node_handlers_todo["Todo<br/>command route<br/>[todo.py]"]
  node_handlers_remind["Remind<br/>command route<br/>[remind.py]"]
  node_handlers_qr["QR<br/>command route<br/>[qr.py]"]
  node_handlers_unknown["Fallback<br/>command route<br/>[unknown.py]"]
end

subgraph group_ai["AI Subsystem"]
  node_agent{{"Agent<br/>ai orchestrator<br/>[agent.py]"}}
  node_checkpointer[("Checkpointing<br/>ai state<br/>[checkpointer.py]")]
  node_tool_todo["Todo Tool<br/>ai tool<br/>[todo.py]"]
  node_tool_remind["Remind Tool<br/>ai tool<br/>[remind.py]"]
  node_tool_time["Time Tool<br/>ai tool<br/>[time.py]"]
  node_tool_web["Web Search<br/>ai tool<br/>[web_search.py]"]
  node_tool_wiki["Wiki Tool<br/>ai tool<br/>[wiki.py]"]
end

subgraph group_storage["Persistence"]
  node_database[("Database<br/>sqlite access<br/>[database.py]")]
  node_bot_db[("Bot DB<br/>sqlite file<br/>[bot.db]")]
  node_memory_db[("Agent Memory<br/>sqlite file<br/>[agent_memory.db]")]
  node_checkpoints_db[("Checkpoints DB<br/>sqlite file<br/>[checkpoints.db]")]
end

subgraph group_shared["Shared Logic"]
  node_parse_time["Parse Time<br/>[parse_time.py]"]
  node_reminder_utils["Reminder Utils<br/>[reminder.py]"]
  node_decorators["Decorators<br/>cross-cutting<br/>[decorators.py]"]
end

node_main -->|"routes"| node_handlers_start
node_main -->|"routes"| node_handlers_help
node_main -->|"routes"| node_handlers_todo
node_main -->|"routes"| node_handlers_remind
node_main -->|"routes"| node_handlers_qr
node_main -->|"routes"| node_handlers_ai
node_main -->|"fallback"| node_handlers_unknown
node_handlers_todo -->|"CRUD"| node_database
node_handlers_remind -->|"parses"| node_parse_time
node_handlers_remind -->|"schedules"| node_reminder_utils
node_handlers_remind -->|"stores"| node_database
node_handlers_ai -->|"invokes"| node_agent
node_handlers_ai -->|"reads/writes"| node_database
node_agent -->|"tool use"| node_tool_todo
node_agent -->|"tool use"| node_tool_remind
node_agent -->|"tool use"| node_tool_time
node_agent -->|"tool use"| node_tool_web
node_agent -->|"tool use"| node_tool_wiki
node_agent -->|"persists state"| node_checkpointer
node_checkpointer -->|"backed by"| node_memory_db
node_checkpointer -->|"backed by"| node_checkpoints_db
node_database -->|"backed by"| node_bot_db
node_tool_todo -->|"uses"| node_database
node_tool_remind -->|"uses"| node_database
node_tool_remind -->|"depends on"| node_tool_time
node_tool_web -->|"returns context"| node_agent
node_tool_wiki -->|"returns context"| node_agent
node_handlers_start -.->|"wrapped by"| node_decorators
node_handlers_help -.->|"wrapped by"| node_decorators
node_handlers_todo -.->|"wrapped by"| node_decorators
node_handlers_remind -.->|"wrapped by"| node_decorators

click node_main "https://github.com/imsudipcreator/task-pilot/blob/main/main.py"
click node_handlers_ai "https://github.com/imsudipcreator/task-pilot/blob/main/handlers/ai.py"
click node_handlers_start "https://github.com/imsudipcreator/task-pilot/blob/main/handlers/start.py"
click node_handlers_help "https://github.com/imsudipcreator/task-pilot/blob/main/handlers/help.py"
click node_handlers_todo "https://github.com/imsudipcreator/task-pilot/blob/main/handlers/todo.py"
click node_handlers_remind "https://github.com/imsudipcreator/task-pilot/blob/main/handlers/remind.py"
click node_handlers_qr "https://github.com/imsudipcreator/task-pilot/blob/main/handlers/qr.py"
click node_handlers_unknown "https://github.com/imsudipcreator/task-pilot/blob/main/handlers/unknown.py"
click node_agent "https://github.com/imsudipcreator/task-pilot/blob/main/ai/agent.py"
click node_checkpointer "https://github.com/imsudipcreator/task-pilot/blob/main/ai/checkpointer.py"
click node_tool_todo "https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/todo.py"
click node_tool_remind "https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/remind.py"
click node_tool_time "https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/time.py"
click node_tool_web "https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/web_search.py"
click node_tool_wiki "https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/wiki.py"
click node_database "https://github.com/imsudipcreator/task-pilot/blob/main/database.py"
click node_bot_db "https://github.com/imsudipcreator/task-pilot/blob/main/data/bot.db"
click node_memory_db "https://github.com/imsudipcreator/task-pilot/blob/main/data/agent_memory.db"
click node_checkpoints_db "https://github.com/imsudipcreator/task-pilot/blob/main/data/checkpoints.db"
click node_parse_time "https://github.com/imsudipcreator/task-pilot/blob/main/utils/parse_time.py"
click node_reminder_utils "https://github.com/imsudipcreator/task-pilot/blob/main/utils/reminder.py"
click node_decorators "https://github.com/imsudipcreator/task-pilot/blob/main/decorators.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_main,node_handlers_ai,node_handlers_start,node_handlers_help,node_handlers_todo,node_handlers_remind,node_handlers_qr,node_handlers_unknown toneBlue
class node_agent,node_checkpointer,node_tool_todo,node_tool_remind,node_tool_time,node_tool_web,node_tool_wiki toneAmber
class node_database,node_bot_db,node_memory_db,node_checkpoints_db toneMint
class node_parse_time,node_reminder_utils,node_decorators toneRose
```

## Components

### Bot Runtime

Process entrypoint and message routing

- [Main](https://github.com/imsudipcreator/task-pilot/blob/main/main.py): entrypoint · Bootstraps the bot runtime and dispatch loop · `main.py`
- [AI Handler](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/ai.py): command route · Routes AI/chat requests into the agent subsystem · `handlers/ai.py`
- [Start](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/start.py): command route · Onboarding and first-run command handling · `handlers/start.py`
- [Help](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/help.py): command route · Usage and assistance commands · `handlers/help.py`
- [Todo](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/todo.py): command route · Task management commands · `handlers/todo.py`
- [Remind](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/remind.py): command route · Reminder command handling · `handlers/remind.py`
- [QR](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/qr.py): command route · QR-related commands · `handlers/qr.py`
- [Fallback](https://github.com/imsudipcreator/task-pilot/blob/main/handlers/unknown.py): command route · Handles unrecognized input · `handlers/unknown.py`

### AI Subsystem

Agent orchestration and tool execution

- [Agent](https://github.com/imsudipcreator/task-pilot/blob/main/ai/agent.py): ai orchestrator · Coordinates conversational reasoning and tool use · `ai/agent.py`
- [Checkpointing](https://github.com/imsudipcreator/task-pilot/blob/main/ai/checkpointer.py): ai state · Persists and restores agent state across turns · `ai/checkpointer.py`
- [Todo Tool](https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/todo.py): ai tool · AI tool for managing tasks · `ai/tools/todo.py`
- [Remind Tool](https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/remind.py): ai tool · AI tool for creating reminders · `ai/tools/remind.py`
- [Time Tool](https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/time.py): ai tool · AI tool for time reasoning and scheduling · `ai/tools/time.py`
- [Web Search](https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/web_search.py): ai tool · External search capability for the agent · `ai/tools/web_search.py`
- [Wiki Tool](https://github.com/imsudipcreator/task-pilot/blob/main/ai/tools/wiki.py): ai tool · External knowledge lookup for the agent · `ai/tools/wiki.py`

### Persistence

Shared database access and SQLite files

- [Database](https://github.com/imsudipcreator/task-pilot/blob/main/database.py): sqlite access · Shared database layer used by handlers and tools · `database.py`
- [Bot DB](https://github.com/imsudipcreator/task-pilot/blob/main/data/bot.db): sqlite file · Core application data store · `data/bot.db`
- [Agent Memory](https://github.com/imsudipcreator/task-pilot/blob/main/data/agent_memory.db): sqlite file · Conversation or memory persistence for AI features · `data/agent_memory.db`
- [Checkpoints DB](https://github.com/imsudipcreator/task-pilot/blob/main/data/checkpoints.db): sqlite file · Checkpoint store for agent recovery · `data/checkpoints.db`

### Shared Logic

Reusable utilities for reminders and time parsing

- [Parse Time](https://github.com/imsudipcreator/task-pilot/blob/main/utils/parse_time.py): utility · Parses human-friendly time expressions · `utils/parse_time.py`
- [Reminder Utils](https://github.com/imsudipcreator/task-pilot/blob/main/utils/reminder.py): utility · Shared reminder scheduling and formatting helpers · `utils/reminder.py`
- [Decorators](https://github.com/imsudipcreator/task-pilot/blob/main/decorators.py): cross-cutting · Reusable handler wrappers and shared behavior · `decorators.py`

## Connections

- Main → Start: routes · Registers the onboarding handler
- Main → Help: routes · Registers usage/help handling
- Main → Todo: routes · Registers task commands
- Main → Remind: routes · Registers reminder commands
- Main → QR: routes · Registers QR commands
- Main → AI Handler: routes · Registers AI/chat handling
- Main → Fallback: fallback · Wires unknown-input handling
- Todo → Database: CRUD · Uses shared persistence for tasks
- Remind → Parse Time: parses · Interprets user time inputs
- Remind → Reminder Utils: schedules · Uses reminder helper logic
- Remind → Database: stores · Persists reminder data
- AI Handler → Agent: invokes · Hands chat requests to the agent
- AI Handler → Database: reads/writes · May access shared bot data
- Agent → Todo Tool: tool use · Can manage tasks through tools
- Agent → Remind Tool: tool use · Can create reminders through tools
- Agent → Time Tool: tool use · Uses time reasoning capabilities
- Agent → Web Search: tool use · Can search the web
- Agent → Wiki Tool: tool use · Can query wiki-like knowledge
- Agent → Checkpointing: persists state · Stores and restores conversational state
- Checkpointing → Agent Memory: backed by · Uses AI memory storage
- Checkpointing → Checkpoints DB: backed by · Uses checkpoint storage
- Database → Bot DB: backed by · Core application SQLite store
- Todo Tool → Database: uses · Reads and updates task data
- Remind Tool → Database: uses · Reads and updates reminder data
- Remind Tool → Time Tool: depends on · Uses time interpretation for reminders
- Web Search → Agent: returns context · Feeds external information back to the agent
- Wiki Tool → Agent: returns context · Feeds reference information back to the agent
- Start → Decorators: wrapped by · Shares common handler behavior
- Help → Decorators: wrapped by · Shares common handler behavior
- Todo → Decorators: wrapped by · Shares common handler behavior
- Remind → Decorators: wrapped by · Shares common handler behavior
