Task Management API

A production-structured REST API for managing personal tasks, built with FastAPI, SQLAlchemy 2.0, and JWT authentication. Each user can register, log in, and manage a private list of tasks — full CRUD with per-user ownership, input validation, and consistent error handling.

This repository is a portfolio project intended to demonstrate backend engineering fundamentals: clean layered architecture, REST API design, database modelling, stateless authentication, automated tests, and containerization with Docker.

---

Table of Contents

• Features
• Tech Stack
• Architecture
• Project Structure
• Database Schema
• Getting Started
  • Run Locally
  • Run with Docker
• Configuration
• API Documentation
• Example Usage (cURL)
• Running Tests
• Design Decisions

---

Features

• User registration with email + password, validated and uniqueness-checked
• User login issuing a signed JWT access token
• JWT-protected endpoints via the OAuth2 bearer scheme
• Task CRUD — create, list (paginated), read, partial-update, delete
• Per-user ownership — users can only ever see or modify their own tasks
• Input validation with Pydantic v2 (typed, constrained fields)
• Consistent error handling with appropriate HTTP status codes
• Interactive API docs auto-generated at /docs and /redoc
• Automated test suite (pytest) covering auth, CRUD, and ownership isolation
• Dockerized with a non-root image, health check, and Compose file

---

Tech Stack

Concern	Choice
Language	Python 3.12
Web framework	FastAPI
ORM	SQLAlchemy 2.0 (typed Mapped columns)
Validation	Pydantic v2 + pydantic-settings
Database	SQLite (swappable for PostgreSQL)
Auth	JWT (PyJWT) + bcrypt password hashing
Server	Uvicorn (ASGI)
Tests	pytest + httpx TestClient
Lint / format	Ruff
CI	GitHub Actions (lint, tests, Docker build)
Packaging / deploy	Docker + Docker Compose

---

Architecture

The application follows a layered (clean) architecture. Each layer has a single responsibility and depends only on the layers beneath it, which keeps business logic testable and the HTTP surface thin.

flowchart TD
Client([HTTP Client])
subgraph App["FastAPI Application"]
direction TB
API["API layer<br/><code>api/routes/*</code> · <code>api/deps.py</code><br/><i>routing · auth gate · status codes</i>"]
Schemas["Schema layer<br/><code>schemas/*</code><br/><i>request / response contracts (Pydantic)</i>"]
CRUD["CRUD layer<br/><code>crud/*</code><br/><i>owner-scoped queries</i>"]
Models["Model layer<br/><code>models/*</code><br/><i>SQLAlchemy ORM tables</i>"]
Core["Core<br/><code>core/config · database · security</code><br/><i>settings · engine · hashing + JWT</i>"]
end
DB[(SQLite / PostgreSQL)]
Client -->|JSON over HTTP| API
API --> Schemas
API --> CRUD
CRUD --> Models
Models --> Core
Core --> DB

Loading

Request lifecycle — POST /api/v1/tasks:

sequenceDiagram
autonumber
participant C as Client
participant R as Route handler
participant D as get_current_user (deps)
participant V as Pydantic (TaskCreate)
participant CR as CRUD layer
participant DB as Database
C->>R: POST /tasks + Bearer token + JSON body
R->>D: resolve current user
alt token missing / invalid
D-->>C: 401 Unauthorized
end
D-->>R: authenticated User
R->>V: validate request body
alt body invalid
V-->>C: 422 Unprocessable Entity
end
V-->>R: validated payload
R->>CR: create_task(owner_id, payload)
CR->>DB: INSERT (scoped to owner_id)
DB-->>CR: row
CR-->>R: Task
R-->>C: 201 Created (TaskRead)

Loading

This separation means the database can be swapped (SQLite → PostgreSQL) by changing one environment variable, and the query logic can be unit-tested without spinning up HTTP.

---

Project Structure

fastapi-task-api/
├── app/
│ ├── main.py # App factory: routers, CORS, lifespan, error handlers
│ ├── core/
│ │ ├── config.py # Env-driven settings (pydantic-settings)
│ │ ├── database.py # Engine, session factory, Base, get_db dependency
│ │ └── security.py # Password hashing + JWT encode/decode
│ ├── models/
│ │ ├── user.py # User ORM model
│ │ └── task.py # Task ORM model
│ ├── schemas/
│ │ ├── user.py # UserCreate / UserRead
│ │ ├── task.py # TaskCreate / TaskUpdate / TaskRead
│ │ └── token.py # Token / TokenPayload
│ ├── crud/
│ │ ├── user.py # User queries + authentication
│ │ └── task.py # Owner-scoped task queries
│ └── api/
│ ├── deps.py # Shared dependencies (DB session, current user)
│ └── routes/
│ ├── auth.py # /auth/register, /auth/login, /auth/me
│ └── tasks.py # /tasks CRUD
├── tests/
│ ├── conftest.py # In-memory DB + auth fixtures
│ ├── test_auth.py
│ └── test_tasks.py
├── .github/workflows/ci.yml # Lint + tests + Docker build on push/PR
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── pyproject.toml # Ruff + pytest configuration
├── .env.example
├── .dockerignore
├── .gitignore
├── LICENSE
└── README.md

---

Database Schema

Two tables with a one-to-many relationship: a User owns many Tasks.

erDiagram
USERS ||--o{ TASKS : owns
USERS {
int id PK
string email UK "unique, indexed"
string hashed_password "bcrypt hash"
datetime created_at
}
TASKS {
int id PK
string title
text description "nullable"
bool completed "default false"
int owner_id FK "indexed, ON DELETE CASCADE"
datetime created_at
datetime updated_at "auto-updates"
}

Loading

users

Column	Type	Constraints
id	INTEGER	Primary key
email	VARCHAR(320)	Unique, indexed, not null
hashed_password	VARCHAR(255)	Not null (bcrypt hash)
created_at	DATETIME	Not null, defaults to now (UTC)

tasks

Column	Type	Constraints
id	INTEGER	Primary key
title	VARCHAR(255)	Not null
description	TEXT	Nullable
completed	BOOLEAN	Not null, default false
owner_id	INTEGER	Foreign key → users.id, indexed, not null
created_at	DATETIME	Not null, defaults to now (UTC)
updated_at	DATETIME	Not null, auto-updates on modify

Relationship & integrity

users (1) ──────< (many) tasks
owner_id FK ON DELETE CASCADE

• tasks.owner_id references users.id with ON DELETE CASCADE, so deleting a user removes their tasks and never leaves orphaned rows.
• email is unique and indexed to enforce one account per address and to keep login lookups fast.
• owner_id is indexed because every task query filters on it.

Schema is created automatically on startup via Base.metadata.create_all. A production deployment would replace this with Alembic migrations for versioned, reversible schema changes.

---

Getting Started

Prerequisites

• Python 3.12+ (for local runs), or
• Docker + Docker Compose (for containerized runs)

Run Locally

# 1. Clone and enter the projectcd fastapi-task-api
# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate# 3. Install dependencies
pip install -r requirements.txt
# 4. Create your environment file and set a real SECRET_KEY
cp .env.example .env
# Generate a strong secret:# openssl rand -hex 32# then paste it into .env as SECRET_KEY# 5. Start the development server (auto-reload)
uvicorn app.main:app --reload

The API is now running at http://localhost:8000. Open http://localhost:8000/docs for interactive Swagger documentation.

Run with Docker

# Build and start in the background
docker compose up --build -d
# Tail logs
docker compose logs -f
# Stop
docker compose down

The service listens on http://localhost:8000 and persists its SQLite database in a named Docker volume (api-data).

Note: Set a strong SECRET_KEY in docker-compose.yml (or via a .env file) before any non-local use.

---

Configuration

All configuration is supplied through environment variables (loaded from .env in development). See .env.example.

Variable	Default	Description
PROJECT_NAME	Task Management API	Shown in the OpenAPI docs
API_V1_PREFIX	/api/v1	Base path for all versioned routes
ENVIRONMENT	development	Free-form environment label
SECRET_KEY	(required)	Key used to sign JWTs — keep secret
ACCESS_TOKEN_EXPIRE_MINUTES	60	Access-token lifetime in minutes
ALGORITHM	HS256	JWT signing algorithm
BACKEND_CORS_ORIGINS	http://localhost:3000,http://localhost:8000	Comma-separated allow-list of browser origins
DATABASE_URL	sqlite:///./tasks.db	SQLAlchemy connection string

To use PostgreSQL instead of SQLite, set e.g. DATABASE_URL="postgresql+psycopg://user:pass@host:5432/tasks" — no code changes required.

---

API Documentation

Base URL: http://localhost:8000/api/v1 Interactive docs: GET /docs (Swagger UI) · GET /redoc (ReDoc)

Method	Path	Auth	Description	Success
GET	/health	—	Liveness/readiness probe	200
POST	/auth/register	—	Register a new user	201
POST	/auth/login	—	Obtain a JWT access token	200
GET	/auth/me	✅	Get the current user	200
POST	/tasks	✅	Create a task	201
GET	/tasks	✅	List your tasks (paginated)	200
GET	/tasks/{id}	✅	Get one of your tasks	200
PATCH	/tasks/{id}	✅	Partially update a task	200
DELETE	/tasks/{id}	✅	Delete a task	204

Authentication: call /auth/login with form fields username (your email) and password. The response contains an access_token; send it on protected requests as Authorization: Bearer <token>.

Error responses

Status	When
401	Missing/invalid/expired token, or bad credentials
404	Task not found (or owned by another user)
409	Email already registered
422	Request body fails validation

---

Example Usage (cURL)

BASE=http://localhost:8000/api/v1
# 1. Register
curl -s -X POST $BASE/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com","password":"password123"}'# 2. Log in and capture the token
TOKEN=$(curl -s -X POST $BASE/auth/login \ -d "username=jane@example.com&password=password123" \| python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")# 3. Create a task
curl -s -X POST $BASE/tasks \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Ship portfolio","description":"Polish the README"}'# 4. List tasks
curl -s $BASE/tasks -H "Authorization: Bearer $TOKEN"# 5. Update a task (mark complete)
curl -s -X PATCH $BASE/tasks/1 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"completed":true}'# 6. Delete a task
curl -s -X DELETE $BASE/tasks/1 -H "Authorization: Bearer $TOKEN"

---

Running Tests

pip install -r requirements.txt
# Lint & format check (same as CI)
ruff check .
ruff format --check .# Test suite
SECRET_KEY=test-secret pytest

The suite runs against an isolated in-memory SQLite database (no setup needed) and covers:

• Registration: success, duplicate email, invalid email, weak password
• Login: success and wrong-password rejection
• Task CRUD: create, list, read, update, delete
• Ownership isolation: one user cannot read or delete another user's task
• Auth enforcement: protected routes reject unauthenticated requests

Continuous Integration: every push and pull request to main runs the linter, the full test suite (Python 3.12), and a Docker image build via GitHub Actions.

---

Design Decisions

• Layered architecture keeps HTTP, validation, and persistence concerns separate, so each can be reasoned about and tested in isolation.
• Owner-scoped queries enforce authorization at the data layer rather than trusting the route — a task lookup cannot return another user's row.
• 404 instead of 403 for tasks owned by others avoids leaking the existence of resources a user isn't allowed to see.
• Stateless JWT auth means no server-side session store; tokens are signed and self-validating, which scales horizontally without shared state.
• Bcrypt password hashing — plaintext passwords are never stored.
• Pydantic response models act as an allow-list on output, so internal fields like hashed_password can never accidentally be serialized.
• Environment-driven config (twelve-factor) keeps secrets out of code and makes the same image deployable across environments.
• Explicit CORS allow-list rather than a wildcard, so the API never echoes arbitrary origins on credentialed requests.
• Linting + CI as a quality gate — Ruff and the test suite run on every push, so regressions are caught before merge.

---

Possible Next Steps

Ideas that would extend this into a larger system: Alembic migrations, refresh tokens + token revocation, role-based access control, rate limiting, structured logging/observability, and a CI pipeline running the test suite on every push.