# syswitzz/task-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/syswitzz/task-tracker
- Repository: https://github.com/syswitzz/task-tracker

## Overview

#### Purpose and Runtime
This repository is an asynchronous REST API for user-scoped task tracking. It runs on Python 3.12 with FastAPI under Uvicorn, uses async SQLAlchemy with SQLite/`aiosqlite`, and exposes OpenAPI documentation through FastAPI. The application entry point is `main.py`; development startup is `uvicorn main:app --reload`.

#### Application Composition
`main.py` creates the FastAPI application, initializes database state at startup, and mounts the domain routers. The HTTP surface is separated by resource:
- User registration, login/token issuance, current-user access, and user mutation: `router/users.py`
- Authenticated task CRUD and completion-state actions: `router/tasks.py`
- Router package boundary: `router/__init__.py`

#### Authentication and Authorization
`auth.py` is the security boundary for OAuth2 password-flow authentication and JWT handling. Clients obtain an access token through the user routes, then send it as a Bearer token to protected endpoints. Route dependencies resolve the authenticated user and enforce user-specific access, preventing tasks from being accessed across owners. JWT signing settings originate from `config.py`.

#### Persistence Layer
`database.py` owns the async SQLAlchemy engine/session lifecycle and startup database initialization. SQLite is the default persistent store (`tasks.db` per the README), accessed asynchronously through `aiosqlite`. HTTP handlers should reach persistence through the injected async database session rather than create independent connections.

#### Domain Model
`models.py` defines the SQLAlchemy persistence entities and their relationships: users own tasks, and task records include completion state. This ownership relationship is the primary authorization and query boundary for task operations. Database schema definitions are distinct from request/response validation contracts in `schemas.py`.

#### API Contract and Request Flow
`schemas.py` contains Pydantic schemas used at the API boundary for registration, credentials/token responses, task creation, partial task updates, and serialized responses. The normal flow is: request → resource router (`router/users.py` or `router/tasks.py`) → authentication dependency when required (`auth.py`) → async session (`database.py`) → ORM entities (`models.py`) → schema-shaped response (`schemas.py`).

#### Configuration and Dependencies
`config.py` centralizes environment-backed security configuration, including `SECRET_KEY`, JWT algorithm, and token expiry. Dependency versions and runtime requirements are defined by `pyproject.toml` and locked in `uv.lock`. The architecture is intentionally local-first: no external identity provider, message broker, cache, or hosted database is indicated.

Main entry points: [`database.py`](https://github.com/syswitzz/task-tracker/blob/main/database.py) (Async Database), [`router/users.py`](https://github.com/syswitzz/task-tracker/blob/main/router/users.py) (User Routes), [`router/tasks.py`](https://github.com/syswitzz/task-tracker/blob/main/router/tasks.py) (Task Routes), [`main.py`](https://github.com/syswitzz/task-tracker/blob/main/main.py) (FastAPI Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["FastAPI Application<br/>application entry<br/>[main.py]"]
  node_dependencies["Runtime Dependencies<br/>package manifest<br/>[pyproject.toml]"]
end

subgraph group_api["API Surface"]
  node_users_router["User Routes<br/>FastAPI router<br/>[users.py]"]
  node_tasks_router["Task Routes<br/>FastAPI router<br/>[tasks.py]"]
  node_router_package["Router Package<br/>package boundary<br/>[__init__.py]"]
  node_schemas["API Schemas<br/>Pydantic contracts<br/>[schemas.py]"]
end

subgraph group_security["Security"]
  node_auth{{"Auth &amp; JWT<br/>security boundary<br/>[auth.py]"}}
  node_config["Security Config<br/>environment config<br/>[config.py]"]
end

subgraph group_data["Persistence"]
  node_database[("Async Database<br/>SQLAlchemy session lifecycle<br/>[database.py]")]
  node_models["ORM Models<br/>SQLAlchemy entities<br/>[models.py]"]
  node_sqlite[("SQLite Store<br/>persistent database")]
end

node_client(("API Client"))

node_client -->|"REST requests"| node_main
node_main -->|"startup initialization"| node_database
node_main -->|"mounts"| node_router_package
node_router_package -->|"exports"| node_users_router
node_router_package -->|"exports"| node_tasks_router
node_users_router -->|"validates and serializes"| node_schemas
node_tasks_router -->|"validates and serializes"| node_schemas
node_users_router -->|"issues and resolves tokens"| node_auth
node_tasks_router -->|"requires current user"| node_auth
node_auth -->|"reads JWT settings"| node_config
node_users_router -->|"injected async session"| node_database
node_tasks_router -->|"injected async session"| node_database
node_database -->|"persists entities"| node_models
node_database -->|"async aiosqlite access"| node_sqlite
node_dependencies -.->|"provides runtime"| node_main

click node_main "https://github.com/syswitzz/task-tracker/blob/main/main.py"
click node_users_router "https://github.com/syswitzz/task-tracker/blob/main/router/users.py"
click node_tasks_router "https://github.com/syswitzz/task-tracker/blob/main/router/tasks.py"
click node_router_package "https://github.com/syswitzz/task-tracker/blob/main/router/__init__.py"
click node_schemas "https://github.com/syswitzz/task-tracker/blob/main/schemas.py"
click node_auth "https://github.com/syswitzz/task-tracker/blob/main/auth.py"
click node_config "https://github.com/syswitzz/task-tracker/blob/main/config.py"
click node_database "https://github.com/syswitzz/task-tracker/blob/main/database.py"
click node_models "https://github.com/syswitzz/task-tracker/blob/main/models.py"
click node_dependencies "https://github.com/syswitzz/task-tracker/blob/main/pyproject.toml"

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_dependencies toneBlue
class node_users_router,node_tasks_router,node_router_package,node_schemas toneAmber
class node_auth,node_config toneMint
class node_database,node_models,node_sqlite toneRose
class node_client toneNeutral
```

## Components

### Runtime

- [FastAPI Application](https://github.com/syswitzz/task-tracker/blob/main/main.py): application entry · Creates the app, initializes storage, and mounts routers. · `main.py`
- [Runtime Dependencies](https://github.com/syswitzz/task-tracker/blob/main/pyproject.toml): package manifest · Python runtime and dependency versions. · `pyproject.toml`

### API Surface

- [User Routes](https://github.com/syswitzz/task-tracker/blob/main/router/users.py): FastAPI router · Registration, login, current-user, and user mutation endpoints. · `router/users.py`
- [Task Routes](https://github.com/syswitzz/task-tracker/blob/main/router/tasks.py): FastAPI router · Authenticated task CRUD and completion actions. · `router/tasks.py`
- [Router Package](https://github.com/syswitzz/task-tracker/blob/main/router/__init__.py): package boundary · `router/__init__.py`
- [API Schemas](https://github.com/syswitzz/task-tracker/blob/main/schemas.py): Pydantic contracts · Request validation and response serialization contracts. · `schemas.py`

### Security

- [Auth & JWT](https://github.com/syswitzz/task-tracker/blob/main/auth.py): security boundary · OAuth2 password flow, token handling, and current-user authorization. · `auth.py`
- [Security Config](https://github.com/syswitzz/task-tracker/blob/main/config.py): environment config · JWT secret, algorithm, and expiry settings. · `config.py`

### Persistence

- [Async Database](https://github.com/syswitzz/task-tracker/blob/main/database.py): SQLAlchemy session lifecycle · Owns the async engine, injected sessions, and startup initialization. · `database.py`
- [ORM Models](https://github.com/syswitzz/task-tracker/blob/main/models.py): SQLAlchemy entities · Users own tasks; ownership scopes task access. · `models.py`
- **SQLite Store**: persistent database · Local tasks.db accessed through aiosqlite.

### Other components

- **API Client**: client · Uses REST endpoints and Bearer tokens.

## Connections

- API Client → FastAPI Application: REST requests
- FastAPI Application → Async Database: startup initialization
- FastAPI Application → Router Package: mounts
- Router Package → User Routes: exports
- Router Package → Task Routes: exports
- User Routes → API Schemas: validates and serializes
- Task Routes → API Schemas: validates and serializes
- User Routes → Auth & JWT: issues and resolves tokens
- Task Routes → Auth & JWT: requires current user
- Auth & JWT → Security Config: reads JWT settings
- User Routes → Async Database: injected async session
- Task Routes → Async Database: injected async session
- Async Database → ORM Models: persists entities
- Async Database → SQLite Store: async aiosqlite access
- Runtime Dependencies → FastAPI Application: provides runtime
