# guyvanced/taskmanager-api architecture

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

- Interactive diagram: https://gitdiagram.com/guyvanced/taskmanager-api
- Repository: https://github.com/guyvanced/taskmanager-api

## Overview

This is a **single-service REST API** (“Task Manager API”) built with **FastAPI**. It exposes CRUD endpoints for `Task` resources and persists them in a **SQLite** database using **SQLAlchemy**. **Pydantic** schemas handle request/response validation/serialization. There is no separate frontend; the “client” is typically Swagger UI / curl / Postman / any HTTP consumer.

- **HTTP API layer (FastAPI + routers)**
- **Schema/validation layer (Pydantic)**
- **Business/data access layer (CRUD module)**
- **Persistence layer (SQLAlchemy ORM + SQLite DB file)**
- **App bootstrap + dependency wiring (main.py, database session lifecycle)**

##### File structure analysis (map directories to architectural layers)
From the tree:

- `app/main.py`
Likely creates the FastAPI `app`, includes routers, sets up lifecycle events, etc. This is the **composition root**.

- `app/routers/task.py`
FastAPI **routing/controller** layer: defines endpoints `/tasks/` and `/tasks/{id}` and translates HTTP → internal calls.

- `app/schemas/task.py`
**Pydantic DTOs**: request bodies for create/update and response models. Also contains validation rules (e.g., `Field(min_length=3)`).

- `app/models/task.py`
**SQLAlchemy model(s)**: ORM mapping defining the `tasks` table (id/title/description/completed).

- `app/crud/task.py`
**Data access / repository-like functions**: create/read/update/delete operations using SQLAlchemy session and models.

- `app/core/database.py`
**DB/session setup**: engine creation, SessionLocal, Base, dependency provider for DB session (FastAPI `Depends` pattern), possibly migrations-less initialization.

- `requirements.txt`

Net: this is a classic **layered monolith**: Router → Schema validation → CRUD → ORM → SQLite.

##### README insights (what to explicitly annotate)
The README provides:
- Concrete endpoints and flows: POST/GET/PUT/DELETE on `/tasks`
- Validation behavior: title length enforced via Pydantic
- Runtime: Uvicorn serving FastAPI, Swagger UI via `/docs` (README has a slightly odd path, but conceptually it’s FastAPI docs)

- Validation note (Pydantic min length)
- “Swagger UI / OpenAPI” as an interface to the same FastAPI app

##### Client(s)
- Browser (Swagger UI)
- API Consumer (curl/Postman/other service)

##### ASGI Server
- `uvicorn` (hosts the app, handles concurrency, passes requests to FastAPI)

##### FastAPI Application (app/main.py)
- Router registration / dependency wiring
- OpenAPI/Swagger generation

##### Task Router (app/routers/task.py)
- Endpoint handlers: POST/GET/PUT/DELETE

##### Pydantic Schemas (app/schemas/task.py)
- Request validation + serialization
- Title min length rule

##### CRUD / Data Access (app/crud/task.py)
- Functions: create_task, get_tasks, get_task_by_id, update_task, delete_task

##### SQLAlchemy ORM Models (app/models/task.py)
- `Task` mapped class

##### Database Core / Session Management (app/core/database.py)
- Engine
- SessionLocal
- Dependency: `get_db()` providing a session per request (likely)

##### SQLite Database
- Local DB file on disk (the persistent store)

- Client → Uvicorn: **HTTP request**
- Uvicorn → FastAPI app: **ASGI call**
- FastAPI app → Task Router: **route dispatch**
- Task Router → Pydantic Schemas: **parse/validate request body**
- Task Router → DB Session dependency (`get_db`): **Depends injection**
- Task Router → CRUD functions: **call (business/data ops)**
- CRUD → SQLAlchemy Models: **construct/query ORM entities**
- CRUD → SQLAlchemy Session/Engine: **ORM query/commit**
- SQLAlchemy → SQLite: **SQL reads/writes**

Error paths:
- Pydantic Schemas → Router: **422 validation error** (e.g., title too short)
- CRUD/DB layer → Router: **404 not found** for missing task id (as described in README)

##### c) Architectural patterns / principles present
- **Layered architecture**: Router (presentation) → CRUD (data access) → ORM → DB
- **Dependency Injection**: FastAPI `Depends(get_db)` session per request
- **DTOs and Validation**: Pydantic models separate from ORM models
- **Single service / single database**: no microservices, no queues, no caches

##### d) Relevant technologies as first-class labels
- FastAPI (routers, dependency injection, OpenAPI)
- Pydantic (schemas/validation)
- SQLAlchemy (ORM + session)
- SQLite (storage)
- Uvicorn (ASGI server)

##### “Don’t overthink it”: separate into many components (specific to this repo)
- In `Task Router`, show the 5 handlers: Create / List / GetById / Update / Delete
- In `CRUD task`, show the 5 corresponding functions
- In `database.py`, show:
- Engine creation
- Session factory
- Base metadata
- `get_db()` generator

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External Clients
    %% =========================
    subgraph "Clients (External)"
        SwaggerUI["Browser: Swagger UI (/docs)"]:::external
        APIClient["HTTP Client: curl / Postman / other service"]:::external
    end

    %% =========================
    %% Runtime Hosting
    %% =========================
    subgraph "Runtime"
        Uvicorn["Uvicorn (ASGI Server)"]:::runtime
        FastAPIApp["FastAPI Application (Composition Root)"]:::runtime
        OpenAPI["OpenAPI Schema + Docs Generation"]:::runtime
    end

    %% =========================
    %% API Layer
    %% =========================
    subgraph "HTTP API Layer (FastAPI Routers)"
        TaskRouter["Task Router: /tasks, /tasks/{id}"]:::api

        subgraph "Endpoint Handlers"
            EPCreate["POST /tasks (Create)"]:::handler
            EPList["GET /tasks (List)"]:::handler
            EPGet["GET /tasks/{id} (GetById)"]:::handler
            EPUpdate["PUT /tasks/{id} (Update)"]:::handler
            EPDelete["DELETE /tasks/{id} (Delete)"]:::handler
        end
    end

    %% =========================
    %% Validation / DTOs
    %% =========================
    subgraph "Schema + Validation Layer (Pydantic)"
        Schemas["Pydantic Schemas (TaskCreate/TaskUpdate/TaskOut)"]:::schema
        ValidationNote["Validation: title min_length >= 3"]:::note
        Err422["HTTP 422: Validation Error"]:::error
    end

    %% =========================
    %% Business / Data Access
    %% =========================
    subgraph "Business / Data Access Layer"
        CRUD["CRUD Module (Task)"]:::code

        subgraph "CRUD Functions"
            CCreate["create_task()"]:::func
            CList["get_tasks()"]:::func
            CGet["get_task_by_id()"]:::func
            CUpdate["update_task()"]:::func
            CDelete["delete_task()"]:::func
        end

        Err404["HTTP 404: Task Not Found"]:::error
    end

    %% =========================
    %% Persistence
    %% =========================
    subgraph "Persistence Layer"
        DBcore["Database Core / Session Management"]:::code

        subgraph "database.py Internals"
            Engine["SQLAlchemy Engine"]:::code
            SessionLocal["SessionLocal (Session Factory)"]:::code
            Base["Base (Declarative Metadata)"]:::code
            GetDB["get_db() (per-request session)"]:::di
        end

        Model["SQLAlchemy ORM Model: Task (tasks table)"]:::code
        SQLite[("SQLite Database (DB file on disk)")]:::db
    end

    %% =========================
    %% Dependencies / Build
    %% =========================
    subgraph "Project Dependencies"
        Reqs["requirements.txt (FastAPI, SQLAlchemy, Pydantic, Uvicorn, ...)"]:::deps
    end

    %% =========================
    %% Main Flow: Requests
    %% =========================
    SwaggerUI -->|"HTTP JSON"| Uvicorn
    APIClient -->|"HTTP JSON"| Uvicorn

    Uvicorn -->|"ASGI call"| FastAPIApp
    FastAPIApp -->|"route dispatch"| TaskRouter
    FastAPIApp -->|"generates"| OpenAPI
    OpenAPI -->|"served to"| SwaggerUI

    %% Router to endpoints
    TaskRouter -->|"handler"| EPCreate
    TaskRouter -->|"handler"| EPList
    TaskRouter -->|"handler"| EPGet
    TaskRouter -->|"handler"| EPUpdate
    TaskRouter -->|"handler"| EPDelete

    %% Validation
    EPCreate -->|"parse/validate body"| Schemas
    EPUpdate -->|"parse/validate body"| Schemas
    Schemas -->|"enforces"| ValidationNote
    Schemas -.->|"on_invalid:422"| Err422
    Err422 -->|"JSON error response"| TaskRouter

    %% Dependency Injection for DB Session
    EPCreate -.->|"Depends(get_db)"| GetDB
    EPList -.->|"Depends(get_db)"| GetDB
    EPGet -.->|"Depends(get_db)"| GetDB
    EPUpdate -.->|"Depends(get_db)"| GetDB
    EPDelete -.->|"Depends(get_db)"| GetDB

    GetDB -->|"opens/closes session"| SessionLocal
    DBcore -->|"configures"| Engine
    DBcore -->|"exposes"| SessionLocal
    DBcore -->|"defines"| Base

    %% Endpoint -> CRUD
    EPCreate -->|"calls"| CCreate
    EPList -->|"calls"| CList
    EPGet -->|"calls"| CGet
    EPUpdate -->|"calls"| CUpdate
    EPDelete -->|"calls"| CDelete

    %% CRUD -> ORM + Session
    CRUD -->|"contains"| CCreate
    CRUD -->|"contains"| CList
    CRUD -->|"contains"| CGet
    CRUD -->|"contains"| CUpdate
    CRUD -->|"contains"| CDelete

    CCreate -->|"uses session"| SessionLocal
    CList -->|"uses session"| SessionLocal
    CGet -->|"uses session"| SessionLocal
    CUpdate -->|"uses session"| SessionLocal
    CDelete -->|"uses session"| SessionLocal

    CCreate -->|"constructs/persists"| Model
    CList -->|"queries"| Model
    CGet -->|"queries"| Model
    CUpdate -->|"updates"| Model
    CDelete -->|"deletes"| Model

    SessionLocal -->|"ORM query/commit"| Engine
    Engine -->|"SQL read/write"| SQLite

    %% Errors + Responses
    CGet -.->|"if_missing:404"| Err404
    CUpdate -.->|"if_missing:404"| Err404
    CDelete -.->|"if_missing:404"| Err404
    Err404 -->|"JSON error response"| TaskRouter

    EPCreate -->|"returns JSON"| TaskRouter
    EPList -->|"returns JSON"| TaskRouter
    EPGet -->|"returns JSON"| TaskRouter
    EPUpdate -->|"returns JSON"| TaskRouter
    EPDelete -->|"returns status"| TaskRouter
    TaskRouter -->|"HTTP response"| FastAPIApp
    FastAPIApp -->|"ASGI response"| Uvicorn
    Uvicorn -->|"HTTP response"| SwaggerUI
    Uvicorn -->|"HTTP response"| APIClient

    %% =========================
    %% Click events (component mapping)
    %% =========================
    click FastAPIApp "https://github.com/guyvanced/taskmanager-api/blob/main/app/main.py"
    click TaskRouter "https://github.com/guyvanced/taskmanager-api/blob/main/app/routers/task.py"
    click Schemas "https://github.com/guyvanced/taskmanager-api/blob/main/app/schemas/task.py"
    click CRUD "https://github.com/guyvanced/taskmanager-api/blob/main/app/crud/task.py"
    click Model "https://github.com/guyvanced/taskmanager-api/blob/main/app/models/task.py"
    click DBcore "https://github.com/guyvanced/taskmanager-api/blob/main/app/core/database.py"
    click Reqs "https://github.com/guyvanced/taskmanager-api/blob/main/requirements.txt"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#E8F1FF,stroke:#2563EB,stroke-width:1.5px,color:#0B1B3A
    classDef runtime fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1.5px,color:#0B1B3A
    classDef api fill:#BFDBFE,stroke:#1D4ED8,stroke-width:1.5px,color:#0B1B3A
    classDef handler fill:#93C5FD,stroke:#1D4ED8,stroke-width:1.2px,color:#0B1B3A
    classDef schema fill:#E9D5FF,stroke:#7C3AED,stroke-width:1.5px,color:#2B0B3A
    classDef code fill:#DDD6FE,stroke:#6D28D9,stroke-width:1.5px,color:#1F1147
    classDef func fill:#C4B5FD,stroke:#6D28D9,stroke-width:1.2px,color:#1F1147
    classDef di fill:#F5D0FE,stroke:#A21CAF,stroke-width:1.5px,color:#3B0A2A,stroke-dasharray: 4 3
    classDef db fill:#FEF3C7,stroke:#B45309,stroke-width:2px,color:#3A2200
    classDef note fill:#F3E8FF,stroke:#7C3AED,stroke-width:1px,color:#2B0B3A,stroke-dasharray: 3 3
    classDef error fill:#FEE2E2,stroke:#DC2626,stroke-width:1.5px,color:#3A0B0B
    classDef deps fill:#E5E7EB,stroke:#374151,stroke-width:1.2px,color:#111827
```
