ForgeAPI

Opinionated FastAPI starter kit for production-ready APIs.

ForgeAPI provides a clean foundation for building API backends with FastAPI. It favors a modular monolith, clean architecture boundaries, predictable tooling, and framework-style developer ergonomics inspired by Laravel and AdonisJS.

What ForgeAPI Is

ForgeAPI is a starter kit for production-oriented API projects. The current foundation includes application structure, configuration, database wiring, migrations, Docker services, testing, linting, type checking, a CLI entrypoint, users, and authentication.

Background jobs, mail, events, cache abstractions, and advanced authorization are planned roadmap items. They are intentionally not implemented yet.

Why It Exists

FastAPI is flexible, but teams often need repeatable conventions before an application grows. ForgeAPI provides those conventions upfront:

• Feature modules instead of a flat routes folder.
• Pydantic Settings for typed configuration.
• SQLAlchemy 2.x and Alembic for database work.
• Docker Compose for local PostgreSQL and Redis.
• Makefile commands for common workflows.
• Typer CLI scaffolding for future framework-style commands.

Features

Foundation included:

• FastAPI application factory and lifespan hook.

• GET /health and GET /ready endpoints.

• Modular app/modules layout.

• Typed environment configuration with Pydantic Settings.

• Async SQLAlchemy engine and session dependency.

• Alembic migration scaffold.

• Structured JSON logging with structlog.

• Standard API error response format.

• Request ID, request logging, CORS, and security headers middleware.

• Users module with model, migration, repository, service, schemas, API routes, and tests.

• Authentication with registration, login, JWT access tokens, persisted refresh tokens, logout, and current-user dependencies.

• Docker Compose services for PostgreSQL and Redis.

• Pytest integration test setup.

• Ruff linting and formatting.

• mypy type checking.

• Typer CLI entrypoint.

• Foundation: app structure, configuration, health/readiness checks, standard errors, request logging, database setup, migrations, Docker, tests, and CLI. Included.

• Cache abstraction: Redis and in-memory backends with a clean get, set, remember API. Included.

• Mail abstraction: Console and SMTP backends for transactional emails. Included.

• Background jobs: Local in-process dispatcher with job registry. Included.

• Users module: model, migration, repository, service, schemas, API routes, and tests. Included.

• Authentication: registration, login, JWT access tokens, persisted refresh tokens, logout, current-user dependencies, and protected user routes. Included.

• Authorization: roles, permissions, policies, and admin-only user management. Planned.

• Developer tooling: seeders, generators, and events. Planned.

• Production hardening: deployment examples, metrics/tracing, and operational runbooks. Planned.

Tech Stack

• Python 3.12+
• FastAPI
• Pydantic v2 and Pydantic Settings
• SQLAlchemy 2.x with async sessions
• Alembic
• PostgreSQL
• Redis
• Pytest
• Ruff
• mypy
• Typer
• Docker Compose
• uv

Quick Start

Install dependencies:

uv sync --extra dev

Create a local environment file:

cp .env.example .env

Start PostgreSQL and Redis:

make docker-up

Run migrations:

make migrate

Start the API:

make dev

Open:

• API health check: http://127.0.0.1:8000/health
• Readiness check: http://127.0.0.1:8000/ready
• OpenAPI docs: http://127.0.0.1:8000/docs

Project Structure

app/
  main.py
  core/
    config.py
    database.py
    logging.py
  modules/
    health/
      router.py
      schemas.py
      service.py
    auth/
      dependencies.py
      models.py
      repository.py
      router.py
      schemas.py
      service.py
    users/
      models.py
      repository.py
      router.py
      schemas.py
      service.py
  cli/
    main.py
alembic/
docs/
tests/
docker-compose.yml
Dockerfile
pyproject.toml
Makefile

Available Commands

make dev        # Run the API with reload
make test       # Run the test suite
make lint       # Run Ruff checks
make format     # Format Python files with Ruff
make typecheck  # Run mypy
make migrate    # Apply Alembic migrations
make revision message="create users"  # Generate a migration
make cli        # Show ForgeAPI CLI help
make docker-up  # Start PostgreSQL and Redis
make docker-down

CLI Commands

Forge provides a command-line tool forgeapi to speed up common tasks. A shorter alias forge is also available for convenience.

# Show environment info
uv run forgeapi info

# List all routes
uv run forge routes

# Generate a new module scaffold
uv run forge make module billing

# Create a database migration
uv run forge make migration "create billing tables"

# Run database seeders
uv run forge db seed

Documentation

• Introduction
• Getting Started
• Architecture
• Configuration
• Database
• Cache
• Mail
• Background Jobs
• Errors
• Observability
• Authentication
• Security
• Users
• Testing
• CLI
• Deployment
• Decision Records

Roadmap

• Foundation: app structure, configuration, health/readiness checks, standard errors, request logging, database setup, migrations, Docker, tests, and CLI. Included.
• Cache abstraction: Redis and in-memory backends. Included.
• Mail abstraction: Console and SMTP backends for transactional emails. Included.
• Background jobs: Local in-process dispatcher with job registry. Included.
• Users module: model, migration, repository, service, schemas, API routes, and tests. Included.
• Authentication: registration, login, JWT access tokens, persisted refresh tokens, logout, current-user dependencies, and protected user routes. Included.
• Authorization: roles, permissions, policies, and admin-only user management. Planned.
• Developer tooling: seeders, generators, and events. Planned.
• Production hardening: deployment examples, metrics/tracing, and operational runbooks. Planned.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, follow the existing architecture, and keep changes focused.

Before opening a pull request, run:

make test
make lint
make typecheck

License

ForgeAPI is distributed under the MIT License. See LICENSE.