How syswitzz/task-tracker works
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 Async Database · users.py User Routes · tasks.py Task Routes · main.py FastAPI Application
Components 12
Runtime
- FastAPI Application · Creates the app, initializes storage, and mounts routers.
main.py - Runtime Dependencies · Python runtime and dependency versions.
pyproject.toml
API Surface
- User Routes · Registration, login, current-user, and user mutation endpoints.
router/users.py - Task Routes · Authenticated task CRUD and completion actions.
router/tasks.py - Router Package
router/__init__.py - API Schemas · Request validation and response serialization contracts.
schemas.py
Security
- Auth & JWT · OAuth2 password flow, token handling, and current-user authorization.
auth.py - Security Config · JWT secret, algorithm, and expiry settings.
config.py
Persistence
- Async Database · Owns the async engine, injected sessions, and startup initialization.
database.py - ORM Models · Users own tasks; ownership scopes task access.
models.py - SQLite Store · Local tasks.db accessed through aiosqlite.
Other components
- API Client · Uses REST endpoints and Bearer tokens.
Connections 15
- 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