# codechen-1/task-management-system architecture

> Architecture diagram of the GitHub repository codechen-1/task-management-system, 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/codechen-1/task-management-system
- Repository: https://github.com/codechen-1/task-management-system

## Overview

This is a FastAPI/SQLite task-management application with browser and CLI clients. The main workflow is user registration/login, authenticated task capture and planning (Inbox, planned dates, top-three focus, checklists), organization/search, and calendar review; categories and preferences provide adjacent capabilities. The server mounts the static UI and registers API routers, while task routes own persistence and filtering. Some UI, settings, calendar, and CLI behavior is represented from the README and source index where implementation excerpts were not provided.

Main entry points: [`app/main.py`](https://github.com/codechen-1/task-management-system/blob/main/app/main.py) (FastAPI app), [`app/database.py`](https://github.com/codechen-1/task-management-system/blob/main/app/database.py) (SQLAlchemy session), [`app/routes/tasks.py`](https://github.com/codechen-1/task-management-system/blob/main/app/routes/tasks.py) (Tasks and planner), [`app/routes/categories.py`](https://github.com/codechen-1/task-management-system/blob/main/app/routes/categories.py) (Categories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_browser["Web interface<br/>[app.js]"]
  node_cli["CLI menus<br/>[menus.py]"]
  node_cli_handlers["CLI handlers<br/>[handlers.py]"]
end

subgraph group_api["API workflows"]
  node_server["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_tasks["Tasks and planner<br/>[tasks.py]"]
  node_categories["Categories<br/>[categories.py]"]
  node_calendar["Calendar views<br/>[calendar.py]"]
  node_settings["User settings<br/>[settings.py]"]
end

subgraph group_domain["Domain and validation"]
  node_task_schema["Task validation<br/>[task.py]"]
  node_category_schema["Category validation<br/>[category.py]"]
  node_date_utils["Date handling<br/>[dates.py]"]
end

subgraph group_persistence["Persistence and security"]
  node_security["JWT and passwords<br/>[security.py]"]
  node_db[("SQLAlchemy session<br/>[database.py]")]
  node_user_model["User records<br/>[user.py]"]
  node_task_model["Task records<br/>[task.py]"]
  node_category_model["Category records<br/>[category.py]"]
  node_settings_model["Settings records<br/>[settings.py]"]
  node_migrations["Planner upgrade<br/>[migrations.py]"]
end

node_person(("User"))

node_person -->|"uses"| node_browser
node_person -->|"uses"| node_cli
node_browser -.->|"calls API"| node_server
node_cli -->|"dispatches"| node_cli_handlers
node_cli_handlers -->|"sends requests"| node_server
node_server -->|"registers router"| node_auth
node_server -->|"registers router"| node_tasks
node_server -->|"registers router"| node_categories
node_server -->|"registers router"| node_calendar
node_server -->|"registers router"| node_settings
node_server -->|"creates tables"| node_db
node_server -->|"runs upgrade"| node_migrations
node_auth -->|"checks credentials"| node_security
node_auth -->|"reads/writes"| node_user_model
node_auth -->|"creates defaults"| node_category_model
node_tasks -->|"validates input"| node_task_schema
node_tasks -->|"authenticates"| node_security
node_tasks -->|"queries and commits"| node_db
node_tasks -->|"reads/writes"| node_task_model
node_tasks -->|"checks ownership"| node_category_model
node_categories -->|"uses task helpers"| node_tasks
node_categories -->|"validates input"| node_category_schema
node_categories -->|"queries and commits"| node_db
node_categories -->|"reads/writes"| node_category_model
node_calendar -->|"queries"| node_db
node_calendar -->|"reads tasks"| node_task_model
node_calendar -->|"normalizes dates"| node_date_utils
node_settings -->|"queries and commits"| node_db
node_settings -->|"reads/writes"| node_settings_model
node_task_schema -->|"normalizes deadlines"| node_date_utils
node_task_schema -->|"embeds category"| node_category_schema
node_db -->|"provides base"| node_user_model
node_db -->|"provides base"| node_task_model
node_db -->|"provides base"| node_category_model
node_security -->|"loads session"| node_db
node_security -->|"loads identity"| node_user_model

click node_browser "https://github.com/codechen-1/task-management-system/blob/main/static/js/app.js"
click node_cli "https://github.com/codechen-1/task-management-system/blob/main/cli/menus.py"
click node_cli_handlers "https://github.com/codechen-1/task-management-system/blob/main/cli/handlers.py"
click node_server "https://github.com/codechen-1/task-management-system/blob/main/app/main.py"
click node_auth "https://github.com/codechen-1/task-management-system/blob/main/app/routes/auth.py"
click node_tasks "https://github.com/codechen-1/task-management-system/blob/main/app/routes/tasks.py"
click node_categories "https://github.com/codechen-1/task-management-system/blob/main/app/routes/categories.py"
click node_calendar "https://github.com/codechen-1/task-management-system/blob/main/app/routes/calendar.py"
click node_settings "https://github.com/codechen-1/task-management-system/blob/main/app/routes/settings.py"
click node_task_schema "https://github.com/codechen-1/task-management-system/blob/main/app/schemas/task.py"
click node_category_schema "https://github.com/codechen-1/task-management-system/blob/main/app/schemas/category.py"
click node_date_utils "https://github.com/codechen-1/task-management-system/blob/main/app/utils/dates.py"
click node_security "https://github.com/codechen-1/task-management-system/blob/main/app/utils/security.py"
click node_db "https://github.com/codechen-1/task-management-system/blob/main/app/database.py"
click node_user_model "https://github.com/codechen-1/task-management-system/blob/main/app/models/user.py"
click node_task_model "https://github.com/codechen-1/task-management-system/blob/main/app/models/task.py"
click node_category_model "https://github.com/codechen-1/task-management-system/blob/main/app/models/category.py"
click node_settings_model "https://github.com/codechen-1/task-management-system/blob/main/app/models/settings.py"
click node_migrations "https://github.com/codechen-1/task-management-system/blob/main/app/migrations.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_browser,node_cli,node_cli_handlers,node_person toneBlue
class node_server,node_auth,node_tasks,node_categories,node_calendar,node_settings toneAmber
class node_task_schema,node_category_schema,node_date_utils toneMint
class node_security,node_db,node_user_model,node_task_model,node_category_model,node_settings_model,node_migrations toneRose
```

## Components

### User clients

- [Web interface](https://github.com/codechen-1/task-management-system/blob/main/static/js/app.js): `static/js/app.js`
- [CLI menus](https://github.com/codechen-1/task-management-system/blob/main/cli/menus.py): `cli/menus.py`
- [CLI handlers](https://github.com/codechen-1/task-management-system/blob/main/cli/handlers.py): `cli/handlers.py`

### API workflows

- [FastAPI app](https://github.com/codechen-1/task-management-system/blob/main/app/main.py): `app/main.py`
- [Authentication](https://github.com/codechen-1/task-management-system/blob/main/app/routes/auth.py): `app/routes/auth.py`
- [Tasks and planner](https://github.com/codechen-1/task-management-system/blob/main/app/routes/tasks.py): `app/routes/tasks.py`
- [Categories](https://github.com/codechen-1/task-management-system/blob/main/app/routes/categories.py): `app/routes/categories.py`
- [Calendar views](https://github.com/codechen-1/task-management-system/blob/main/app/routes/calendar.py): `app/routes/calendar.py`
- [User settings](https://github.com/codechen-1/task-management-system/blob/main/app/routes/settings.py): `app/routes/settings.py`

### Domain and validation

- [Task validation](https://github.com/codechen-1/task-management-system/blob/main/app/schemas/task.py): `app/schemas/task.py`
- [Category validation](https://github.com/codechen-1/task-management-system/blob/main/app/schemas/category.py): `app/schemas/category.py`
- [Date handling](https://github.com/codechen-1/task-management-system/blob/main/app/utils/dates.py): `app/utils/dates.py`

### Persistence and security

- [JWT and passwords](https://github.com/codechen-1/task-management-system/blob/main/app/utils/security.py): `app/utils/security.py`
- [SQLAlchemy session](https://github.com/codechen-1/task-management-system/blob/main/app/database.py): `app/database.py`
- [User records](https://github.com/codechen-1/task-management-system/blob/main/app/models/user.py): `app/models/user.py`
- [Task records](https://github.com/codechen-1/task-management-system/blob/main/app/models/task.py): `app/models/task.py`
- [Category records](https://github.com/codechen-1/task-management-system/blob/main/app/models/category.py): `app/models/category.py`
- [Settings records](https://github.com/codechen-1/task-management-system/blob/main/app/models/settings.py): `app/models/settings.py`
- [Planner upgrade](https://github.com/codechen-1/task-management-system/blob/main/app/migrations.py): `app/migrations.py`

### Other components

- **User**

## Connections

- User → Web interface: uses (evidence: `README.md`)
- User → CLI menus: uses (evidence: `README.md`)
- Web interface → FastAPI app: calls API (evidence: `README.md`)
- CLI menus → CLI handlers: dispatches (evidence: `cli/menus.py`)
- CLI handlers → FastAPI app: sends requests (evidence: `cli/handlers.py`)
- FastAPI app → Authentication: registers router (evidence: `app/main.py`)
- FastAPI app → Tasks and planner: registers router (evidence: `app/main.py`)
- FastAPI app → Categories: registers router (evidence: `app/main.py`)
- FastAPI app → Calendar views: registers router (evidence: `app/main.py`)
- FastAPI app → User settings: registers router (evidence: `app/main.py`)
- FastAPI app → SQLAlchemy session: creates tables (evidence: `app/main.py`)
- FastAPI app → Planner upgrade: runs upgrade (evidence: `app/main.py`)
- Authentication → JWT and passwords: checks credentials (evidence: `app/routes/auth.py`)
- Authentication → User records: reads/writes (evidence: `app/routes/auth.py`)
- Authentication → Category records: creates defaults (evidence: `app/routes/auth.py`)
- Tasks and planner → Task validation: validates input (evidence: `app/routes/tasks.py`)
- Tasks and planner → JWT and passwords: authenticates (evidence: `app/routes/tasks.py`)
- Tasks and planner → SQLAlchemy session: queries and commits (evidence: `app/routes/tasks.py`)
- Tasks and planner → Task records: reads/writes (evidence: `app/routes/tasks.py`)
- Tasks and planner → Category records: checks ownership (evidence: `app/routes/tasks.py`)
- Categories → Tasks and planner: uses task helpers (evidence: `app/routes/categories.py`)
- Categories → Category validation: validates input (evidence: `app/routes/categories.py`)
- Categories → SQLAlchemy session: queries and commits (evidence: `app/routes/categories.py`)
- Categories → Category records: reads/writes (evidence: `app/routes/categories.py`)
- Calendar views → SQLAlchemy session: queries (evidence: `app/routes/calendar.py`)
- Calendar views → Task records: reads tasks (evidence: `app/routes/calendar.py`)
- Calendar views → Date handling: normalizes dates (evidence: `app/routes/calendar.py`)
- User settings → SQLAlchemy session: queries and commits (evidence: `app/routes/settings.py`)
- User settings → Settings records: reads/writes (evidence: `app/routes/settings.py`)
- Task validation → Date handling: normalizes deadlines (evidence: `app/schemas/task.py`)
- Task validation → Category validation: embeds category (evidence: `app/schemas/task.py`)
- SQLAlchemy session → User records: provides base (evidence: `app/models/user.py`)
- SQLAlchemy session → Task records: provides base (evidence: `app/models/task.py`)
- SQLAlchemy session → Category records: provides base (evidence: `app/models/category.py`)
- JWT and passwords → SQLAlchemy session: loads session (evidence: `app/utils/security.py`)
- JWT and passwords → User records: loads identity (evidence: `app/utils/security.py`)
