FastAPI Project Template

Reusable starting point for a FastAPI service with async SQLAlchemy, Alembic, Bearer token auth, Sentry, and pytest.

Project layout

app/
  main.py                 # AppFastAPI, AppState, lifespan
  apps/
    internal/             # healthcheck endpoint (reference app module)
  core/
    auth.py               # Bearer API token verification
    db/                   # Base model, DatabaseManager, repository/service bases
    exceptions.py         # AppValueError, AppValidationError, model errors
    exception_handlers.py
    middlewares/          # access logging, error catcher
    routing/              # AppMiddlewareBase
    settings.py           # Settings, PostgresSettings, SentrySettings
    setups.py             # setup_db
    integrations/         # logging, Sentry
  utils/
migrations/               # Alembic env (add versions as you introduce models)
tests/
  apps/internal/          # healthcheck tests
  core/db/                # ExampleModel + repository/service template tests
  fixtures/               # app, db, settings fixtures
scripts/
  rename_project.py       # rename package / class prefix for a new service

Prepare development environment

# uv creates .venv with Python 3.12 and installs dependencies
uv sync
cp .env.template .env

PostgreSQL 18+ is required (Base.id uses func.uuidv7()).

Run local server

docker compose up -d db
uvicorn app.main:AppFastAPI --host 0.0.0.0 --port 8081 --reload

Run with Docker Compose

docker compose up --build

API listens on http://localhost:8081. Healthcheck: GET /v1/healthcheck with header Authorization: Bearer <API_TOKEN>.

Database migrations

Generate a migration:

alembic revision --autogenerate -m "create Some Table" --rev-id=<migration number>

Apply migrations:

alembic upgrade head

Import new models in migrations/env.py (or anywhere that registers them on Base.metadata) before autogenerate.

Tests

pytest -vv --cov

tests/core/db/ contains a technical ExampleModel plus concrete repository/service tests that exercise SQLAlchemyRepository / SQLAlchemyService base classes. Template classes live in tests/core/db/repositories/template.py and tests/core/db/services/template.py — subclass them for your own models.

Pre-commit hooks

pre-commit install
pre-commit run --all-files

Rename the template for your service

Use the helper script (dry-run first):

python scripts/rename_project.py --package myservice --prefix MyService --dry-run
python scripts/rename_project.py --package myservice --prefix MyService

What it updates:

• renames the app/ package directory
• rewrites from app. / import app. import paths (without touching app.state or Dockerfile WORKDIR /app)
• updates anchors in pyproject.toml, .coveragerc, Dockerfile, compose files, README
• optionally renames AppFastAPI, AppState, AppMiddlewareBase, AppValueError, AppValidationError, and app_*_exception_handler when --prefix is set

Manual checklist after rename:

1. Set APP_NAME / POSTGRES_DB in .env and .env.template
2. Run uv sync and pytest -vv --cov
3. Update GitLab / Harbor project variables if needed

Add a new app module

1. Create app/apps/<name>/ with models/, repositories/, services/, schemas/, views/.
2. Subclass SQLAlchemyRepository and SQLAlchemyService from app.core.db.
3. Register the router in app/core/routers.py under /v1 (token auth is applied globally there).
4. Import models so Alembic sees them (e.g. from package __init__.py or migrations/env.py).
5. Add factories under tests/... and subclass SQLAlchemyRepositoryTestTemplate / SQLAlchemyServiceTestTemplate.
6. Generate and apply an Alembic migration.