README.md

Benav Labs FastAPI boilerplate

Batteries-included FastAPI starter — vertical-slice modules, swappable infrastructure, plugin-ready CLI.

📚 Docs · 🧠 DeepWiki · 💬 Discord

Features

• ⚡️ Fully async FastAPI + SQLAlchemy 2.0
• 🧱 Pydantic v2 models & validation
• 🔐 Server-side sessions + CSRF; OAuth (Google wired, GitHub scaffolded); API keys
• 👮 Rate limiter with per-tier, per-path rules
• 🧰 FastCRUD for efficient CRUD & pagination
• 🧑‍💼 SQLAdmin-based admin panel (optional, env-toggled)
• 🚦 Taskiq workers (Redis or RabbitMQ broker)
• 🧊 Redis or Memcached caching (@cache decorator + provider API)
• 🛠 Plugin-ready bp CLI — generate compose files, audit env, mount third-party command/feature plugins
• 🐳 Docker Compose for local / prod / nginx-fronted (generated by the CLI)

Why and When to use it

Perfect if you want:

• A pragmatic starter with auth, CRUD, jobs, caching and rate-limits
• Sensible defaults with the freedom to opt-out of modules
• A foundation that grows — vertical-slice modules + a plugin-aware CLI for code generators
• Docs over boilerplate in this README — depth lives on the docs site

Not a fit if you need a monorepo microservices scaffold — see the docs for pointers.

What you get:

• App: FastAPI app factory, env-aware docs exposure
• Auth: server-side sessions, CSRF, OAuth, API keys
• DB: Postgres + SQLAlchemy 2.0, Alembic migrations with prod-confirm gate
• CRUD: FastCRUD generics
• Caching: decorator + provider API (Redis or Memcached)
• Queues: Taskiq workers (Redis or RabbitMQ)
• Rate limits: per-tier + per-path rules
• Admin: SQLAdmin views (optional, env-toggled)
• CLI: bp tool for compose scaffolding, env audits, and plugin extensions

Building an AI SaaS? Skip even more setup with FastroAI — our production-ready template with AI integration, payments, and frontend included.

Repo Layout

This is a uv workspace with two members. One venv at the root covers both.

fastapi-boilerplate/
├── pyproject.toml          # workspace root (uv workspace metadata)
├── backend/                # the deployable application
│   ├── src/                # interfaces/, infrastructure/, modules/
│   ├── pyproject.toml
│   └── Dockerfile          # multi-stage: dev / migrate / prod
└── cli/                    # `bp` — developer/operator tool (never ships in prod)
    └── src/cli/

Quickstart

git clone https://github.com/<you>/FastAPI-boilerplate
cd FastAPI-boilerplate
uv sync --all-packages --all-extras           # one venv at the root, both members installed

Generate a compose file for the deployment shape you want:

uv run bp deploy generate local               # hot-reload dev stack
# or: uv run bp deploy generate prod          # production single-host
# or: uv run bp deploy generate nginx         # production behind nginx

Configure your env (the CLI helps with secrets and validation):

cp backend/.env.example backend/.env
uv run bp env gen-secret                      # print a fresh SECRET_KEY
uv run bp env validate                        # audit .env against the production validator

Bring it up:

docker compose up --build
# → http://127.0.0.1:8000  (Swagger at /docs)

Without Docker (Postgres + Redis required locally):

cd backend
uv run alembic upgrade head
uv run python -m scripts.setup_initial_data   # creates the first admin user + default tier
uv run fastapi dev src/interfaces/main.py     # API
uv run taskiq worker infrastructure.taskiq.worker:default_broker  # in a second terminal

Full setup, env-var reference, and per-environment deployment guides live in the docs.

Common tasks

# generate a fresh production-ready compose file
uv run bp deploy generate prod --workers 8

# audit your .env against the production security validator
uv run bp env validate

# run Alembic migrations
cd backend && uv run alembic revision --autogenerate -m "<msg>" && uv run alembic upgrade head

# run tests
cd backend && uv run pytest

# install bp as a global tool (optional)
uv tool install --editable ./cli

More examples (superuser creation, tiers, rate limits, admin usage, plugin authoring) in the docs.

Contributing

Read contributing.

References

This project was inspired by a few projects, it's based on them with things changed to the way I like (and pydantic, sqlalchemy updated)

• Full Stack FastAPI and PostgreSQL by @tiangolo himself
• FastAPI Microservices by @kludex which heavily inspired this boilerplate
• Async Web API with FastAPI + SQLAlchemy 2.0 for sqlalchemy 2.0 ORM examples
• FastaAPI Rocket Boilerplate for docker compose

License

MIT

Contact

Benav Labs – benav.io, discord server

---