FastAPI Project Template

A modern, production-ready FastAPI template with built-in features for rapid development and deployment.

Features & Tech Stack

Core Framework

• FastAPI - Modern, fast web framework for building APIs with automatic OpenAPI documentation
• FastAPI Pundra - Productivity companion for FastAPI (global exception handling, OpenAPI schema discovery, auto_bind_router for API modules)
• Auto Route Discovery - Routers under app.api are discovered and mounted automatically

Database & ORM

• PostgreSQL - Default target database (connection built from settings; psycopg2-binary driver)
• SQLAlchemy - SQL toolkit and ORM
• Alembic - Database migration management and version control

Configuration & Validation

• Pydantic - Request/response models and validation
• Pydantic Settings - Typed configuration from environment variables (app/config/settings.py)
• Schema Layer - Organized schemas under app.schemas with OpenAPI discovery
• Custom Serializers - Flexible data transformation under app/serializers

Task Management

• TaskIQ - Async task queue for background jobs
• taskiq-redis - Redis broker for TaskIQ
• Task Scheduling - Sample scheduled tasks and scheduler scripts under scripts/

Security & Authentication

• JWT Authentication - Bearer tokens via fastapi-pundra JWT utilities
• Authorization Middleware - Validates JWT on protected routes; public routes are configured in EXCLUDE_PATHS (app/config/authorization.py)
• Path Rules - Prefix, segment-wildcard, and exact path matching for public routes (app/lib/auth_path_utils.py)

HTTP & Integrations

• HTTPX - Async-friendly HTTP client; shared helpers in app/lib/httpx_client.py

Development & Tools

• UV - Python package manager and lockfile (uv.lock)
• Pytest - Tests with pytest-asyncio, pytest-cov, factories (factory-boy / faker), and app/tests/conftest.py
• Ruff - Linter/formatter (ruff.toml; also run via pre-commit)
• Pre-commit - Git hooks (install with uv run pre-commit-install or use uv run lint to run hooks on all files)
• Docker - Sample app Dockerfile and supervisor config under docker/

Additional Features

• Email - fastapi-mail, Jinja2 templates, and premailer/inline CSS under app/templates/mails/
• SQL File Management - Raw SQL files under app/sql_files/
• Structured Logging - Loguru-based logging (app/utils/logger.py)

Prerequisites

• Python 3.12 or higher
• UV package manager (recommended)
• PostgreSQL (or adjust db_* settings in .env to match your database)

Quick Start

1. Setup Project

Clone the repository and install dependencies:

# Install dependencies
uv sync

# Install with development dependencies (recommended for development)
uv sync --extra dev

Note: The --extra dev flag installs testing tools, Ruff, pre-commit, and related dev dependencies.

2. Environment Configuration

Create your environment configuration:

# Copy the example environment file
cp .env.example .env

# Edit .env: database host/user/password/name, SSL mode, project port, test DB URL, etc.
# Settings are loaded in app/config/settings.py (Pydantic Settings).

3. Database Setup

This project uses Alembic for database schema management and migrations.

Initialize and upgrade your database:

# Run database migrations
uv run db-upgrade

# Create a new database revision (message in quotes)
uv run db-revision "Initial database setup"

4. Run the Application

Start the development server:

# Development: auto-reload (port from settings, default 8000)
uv run start-server-dev

# Production-style: no reload
uv run start-server

The API will be available at (host/port depend on your settings; defaults shown):

• API: http://localhost:8000
• Interactive Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

5. Optional: Git hooks & tests

# Install pre-commit hooks (once per clone)
uv run pre-commit-install

# Run the full lint pipeline (pre-commit on all files)
uv run lint

# Tests with coverage (project script enforces coverage thresholds)
bash scripts/test.sh

# Or run pytest directly (see pyproject.toml for default pytest options)
uv run pytest

Project CLI entry points

Defined in pyproject.toml under [project.scripts]:

Command	Purpose
uv run start-server	Run the app with Uvicorn (no reload)
uv run start-server-dev	Run with reload
uv run db-upgrade	alembic upgrade head
uv run db-revision "message"	alembic revision --autogenerate
uv run lint	Run pre-commit on all files
uv run pre-commit-install	pre-commit install

Directory structure

├── _docs/                          # Extra documentation (see below)
├── alembic/                        # Alembic env and migration versions
├── app/
│   ├── api/                        # HTTP routes (auto-bound from app.api)
│   │   ├── v1/
│   │   │   ├── task_schedule_sample.py
│   │   │   └── user.py
│   │   ├── health.py
│   │   ├── root_index.py
│   │   └── router.py
│   ├── config/                     # Settings, CORS, authorization lists
│   │   ├── authorization.py       # EXCLUDE_PATHS (JWT not required)
│   │   ├── cors.py
│   │   └── settings.py            # Pydantic Settings / env
│   ├── lib/
│   │   ├── auth_path_utils.py     # Public-path matching for middleware
│   │   ├── database.py            # Engine, session, Base
│   │   ├── dot_env_loader.py
│   │   ├── httpx_client.py
│   │   └── tskq/                  # TaskIQ broker, scheduler helpers, invoker
│   ├── middleware/
│   │   └── authorization_middleware.py
│   ├── models/
│   │   └── users.py
│   ├── schemas/
│   │   └── user_schema.py
│   ├── serializers/
│   │   └── user_serializer.py
│   ├── services/
│   │   ├── scheduler_service.py
│   │   └── user_service.py
│   ├── sql_files/users/           # Example raw SQL
│   ├── tasks/                     # TaskIQ task modules
│   ├── templates/                 # Jinja (e.g. mail HTML)
│   ├── tests/                     # pytest: unit/, integration/, factories/, fixtures/
│   ├── utils/
│   │   ├── base.py
│   │   └── logger.py              # Loguru setup
│   ├── cli.py                     # db-upgrade, db-revision, lint, pre-commit-install
│   ├── main.py                    # FastAPI app factory
│   └── taskiq.py                  # TaskIQ app/broker wiring
├── docker/
│   ├── config/supervisor/
│   └── dockerfiles/
├── scripts/                       # test.sh, lint.sh, format.sh, taskiq-*.sh, deploy.sh, etc.
├── .coveragerc
├── .pre-commit-config.yaml
├── alembic.ini
├── pyproject.toml
├── ruff.toml
├── uv.lock
└── README.md

Note

This project requires Python 3.12 or higher.

Postman collection documentation

• Postman collection documentation

Docs

• Linting and formatting
• Testing
• Authorization & public paths
• HTTPX client
• Task scheduler
• Mailing
• Containerization