TaskFlow API

Production-oriented CRUD API for personal projects and tasks.

Stack

• Python 3.13+ (local environment currently uses Python 3.14), Poetry
• FastAPI, Pydantic v2, SQLAlchemy 2.0 async, asyncpg
• PostgreSQL 16
• Alembic migrations, JWT access tokens, rotated refresh tokens
• pytest, httpx, Ruff

Project structure

app/
  core/                 # settings and security primitives
  db/                   # SQLAlchemy Base and async session
  features/
    auth/               # router, schemas, model, repository, service
    projects/           # router, schemas, model, repository, service
    tasks/              # router, schemas, model, repository, service
  dependencies.py       # FastAPI auth/database dependencies
  main.py               # application composition and lifespan
migrations/             # Alembic environment and revisions
tests/                  # API tests with an isolated SQLite database

Business logic is kept in feature services, database access in feature repositories, and routers only translate HTTP input/output. Feature modules depend on shared infrastructure through explicit boundaries.

Local setup

python3 -m venv .venv
./.venv/bin/pip install -e .
./.venv/bin/pip install aiosqlite pytest pytest-asyncio ruff
cp .env.example .env

Start the dedicated PostgreSQL database in OrbStack:

docker compose up -d postgres
./.venv/bin/alembic upgrade head

Run the API locally:

./.venv/bin/uvicorn app.main:app --reload

Swagger UI is available at http://127.0.0.1:8000/docs.

Verification

./.venv/bin/pytest -q
./.venv/bin/ruff check .
./.venv/bin/ruff format --check .

The test suite covers registration/login/refresh, invalid credentials, duplicate users, project/task CRUD, and isolation of one user's data from another user's data.

API surface

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• POST /api/v1/auth/refresh
• POST /api/v1/auth/logout
• GET /api/v1/auth/me
• CRUD /api/v1/projects
• CRUD /api/v1/projects/{project_id}/tasks
• GET /health