Backend Architecture Deep-Dive

Task Management REST API

Modern RESTful backend featuring JWT authentication (Argon2), strict IDOR defense, dynamic filtering/pagination, and isolated Pytest test suite.

PythonFastAPIPostgreSQLSQLAlchemy 2.0AlembicPydantic v2JWT (Argon2)Pytest

Project Overview

A production-ready, human-quality Task Management REST API engineered with Python 3.14, FastAPI, PostgreSQL, SQLAlchemy 2.0, and Alembic. Designed following clean architecture principles, featuring strict request validation via Pydantic v2, memory-hard Argon2 password hashing with stateless JWT authentication, query-level IDOR authorization defense, envelope pagination, and 100% test isolation across 32 automated Pytest test cases.

Key Features & Technical Implementations

Stateless JWT Authentication & Argon2 password hashing

Strict IDOR defense enforcing user ownership at the SQL query level

SQLAlchemy 2.0 Mapped Models & Alembic schema migrations

Dynamic filtering (status, priority) & deterministic nulls-last sorting

Envelope pagination returning items, total, limit, and offset

Dual-Database test isolation with 32 automated Pytest test cases

Backend System Architecture Diagram

Interactive Blueprint

Layer 01

Client / HTTP Consumer

Frontend App / cURL / Swagger UI

HTTP/HTTPS

Layer 02

ASGI Server & Router

FastAPI Central Router & Endpoints

Uvicorn & FastAPI

Layer 03

Dependency Injection

JWT Auth (Argon2) & DB Session Lifecycle

get_current_user & get_db

Layer 04

Validation & Schemas

Pydantic v2 Strict Serialization

Pydantic v2

Layer 05

ORM & Migration Layer

SQLAlchemy 2.0 Mapped Entities & Alembic

SQLAlchemy & Alembic

Layer 06

Database Layer

Relational Persistence & Indexing

PostgreSQL (task_db)

Execution & Data Lifecycle Flow

1. Client sends HTTP request with JSON payload or Authorization Bearer token to FastAPI endpoints.

2. FastAPI router executes dependency injection for get_db session management and get_current_user authentication.

3. Security layer verifies JWT signature and Argon2 password hashes, rejecting invalid or expired credentials.

4. Pydantic v2 schemas strictly validate input payloads and deserialize request parameters.

5. SQLAlchemy 2.0 executes type-safe queries with query-level IDOR user ownership isolation against PostgreSQL.

6. Endpoint returns structured JSON response with envelope pagination or standard HTTP status codes (201 Created, 204 No Content, 404 Not Found).

API Documentation & cURL Playground

OpenAPI Spec

Endpoints (4)

POST/api/v1/auth/login

Authenticate user credentials and return signed JWT access token.

cURL Request

curl -X POST "http://127.0.0.1:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=alex@example.com&password=SecurePassword123."

Response (200 OK - JSON)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

System Outputs & Live Terminal Gallery

Visual Evidence

pytest --verbose

100% PASSED

✓ tests/test_auth.py::test_login_success PASSED

✓ tests/test_tasks.py::test_create_task PASSED

✓ tests/test_tasks.py::test_task_idor_isolation PASSED

✓ tests/test_queries.py::test_filter_and_sort_tasks PASSED

----------------------------------------

32 passed in 1.48s

Swagger UI Docs SchemaOpenAPI 3.0.2

Auto-generated Interactive OpenAPI Documentation

Strict Pydantic JSON Schema Export

CORS Configured with Rate Limiting

Challenges Faced & Engineering Solutions

01.Eliminating Insecure Direct Object Reference (IDOR) vulnerabilities by enforcing ownership verification directly within SQLAlchemy query filters (Task.user_id == current_user.id) rather than in application memory.

02.Implementing dynamic query filtering and multi-column sorting while ensuring deterministic order for nullable deadlines using SQLAlchemy .nulls_last().

03.Configuring dual-database test isolation with Pytest session fixtures and FastAPI dependency overrides to prevent test runs from mutating active development data.

Key Engineering Takeaways

01.Mastery of modern SQLAlchemy 2.0 syntax (Mapped, mapped_column), relationship cascades, and Alembic migration version control.

02.Hardening backend security using memory-hard Argon2 password hashing (pwdlib) and cryptographic JWT token encoding (PyJWT).

03.Architecting clean layered FastAPI structure separating schemas, models, dependency injection (deps.py), and versioned API routers.