Architectural overview for TaskFlow onboarding: high-level architecture, key modules, and data flow

Summary:

• Goal: Provide a concise, high-level view of TaskFlow's architecture to help onboarding and future development.

• Overall structure: A small Python monolith exposing both a CLI (Click) and a REST API (FastAPI) that share a common domain model and a SQLite persistence layer.

• Core domain model:

  • src/models.py defines:
    • Task, Project dataclasses
    • Priority and Status enums
    • Domain logic (e.g., Project.summary, Task.complete)
  • The domain model is used by both CLI and API layers, ensuring consistency of business rules.

• Data persistence:

  • src/db.py implements a SQLite-backed repository (Database) with two tables: projects and tasks.
  • Schema includes created_at timestamps, and completed_at for tasks.
  • Tags are stored as JSON in the tasks.tags column.
  • Default DB path is ~/.taskflow/tasks.db.

• API layer:

  • src/api.py exposes REST endpoints for managing projects and tasks using FastAPI.
  • Endpoints include: list/create projects, get project with a computed summary, list/create tasks, update task status.
  • Uses pydantic models for request/response (ProjectCreate, TaskCreate, TaskUpdate).
  • Converts domain objects into JSON-friendly responses (e.g., Priority/Status enums mapped to their values).

• CLI layer:

  • src/cli.py provides a Click-based CLI for managing projects and tasks (create/list, add, done) that interacts with the same Database class.
  • Commands mirror API functionality, offering a local, scriptable interface.

• Data lifecycle / flow:

  • Create project or task via CLI or API; Domain objects created and stored in SQLite via Database.
  • Reading data returns domain models converted to dicts for API responses; CLI prints human-friendly output.
  • Task status updates write to the tasks table; completed_at is populated when status becomes DONE.
  • Project.summary computes progress metrics for API responses based on the tasks associated with the project.

• Cross-cutting concerns:

  • Language: Python 3.11+; dependencies: click, fastapi, uvicorn, sqlite3, json.
  • Simple, file-based persistence suitable for demos; no migrations or external DB required.
  • Extensibility: The separation between models, DB, CLI, and API provides clear extension points (e.g., swap DB with a real database, or expose more API endpoints).

• Observations / potential improvements:

  • Add tests for CLI, API endpoints, and data layer.
  • Introduce a Repository/Service layer to decouple domain models from persistence even further.
  • Add configuration options for DB path, API host/port, and enable authentication/authorization if needed.