Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
71 commits
Select commit Hold shift + click to select a range
dd735d0
carry the deploy templates into blueprint/ on the generator context, …
igorbenav Oct 26, 2026
eb24ef2
draw a secret key the project's own rules accept from a backend script
igorbenav Oct 27, 2026
77ce33e
audit the environment the way production would from a backend script
igorbenav Oct 27, 2026
4778e01
describe the blueprint, its dependencies, its presets and its verify …
igorbenav Oct 27, 2026
0fdec4e
declare the points features contribute to, and what core contributes
igorbenav Oct 28, 2026
339d7cc
declare the points features contribute to, and what core contributes
igorbenav Oct 28, 2026
90355be
check the catalog against the rules spec rev 1.7 tightens
igorbenav Oct 28, 2026
80839e9
draw the test's key inside the test, not into its id
igorbenav Oct 28, 2026
4a06265
run the blueprint's tests when pytest runs from the workspace root
igorbenav Oct 28, 2026
8bd2c1e
declare the nine features, what they need and what they own
igorbenav Oct 28, 2026
10327c3
declare what each feature contributes, in what order, and what it can…
igorbenav Oct 28, 2026
e181076
declare the twelve files the composition root is generated into
igorbenav Oct 28, 2026
c4dcb84
lay the generated wiring out the way the spec renders it
igorbenav Oct 28, 2026
b3a00dc
declare the deploy generator, the commands and the blueprint's own pr…
igorbenav Oct 28, 2026
951950b
declare the commands each feature brings with it
igorbenav Oct 28, 2026
1ae7f45
write the baseline migration from a script, and declare it as a command
igorbenav Oct 29, 2026
7e49c35
say in every generated file that fastro generated it
igorbenav Oct 29, 2026
48e8107
name the secret command what fastro names it, and keep the blueprint'…
igorbenav Oct 30, 2026
c7de105
keep the blueprint's own files out of the projects the drill builds
igorbenav Oct 31, 2026
2879f5a
declare faker and httpx for development, which is where they are impo…
igorbenav Oct 31, 2026
52abbcf
declare each feature's own dependencies, and the memcached option's
igorbenav Oct 31, 2026
e6aa1c2
declare each feature's own dependencies, and the memcached option's
igorbenav Oct 31, 2026
b607680
drop the dependency nothing used, and account for the ones nothing im…
igorbenav Oct 31, 2026
e838bf0
give every section of the environment example one owner
igorbenav Oct 31, 2026
2ffce91
say which feature keeps each section of the environment example
igorbenav Oct 31, 2026
7dad584
keep the blueprint's own files out of the source tarball
igorbenav Oct 31, 2026
e46bf26
give taskiq's reload extra to the taskiq feature, and drop the exampl…
igorbenav Oct 31, 2026
ccae106
give projects their own gitignore and agent instructions
igorbenav Oct 31, 2026
513647a
give projects a readme that matches what they carry
igorbenav Oct 31, 2026
0b25ea0
give projects a CI workflow and pre-commit hooks that check what they…
igorbenav Oct 31, 2026
b6ab6f9
ship the admin panel switched off in the environment example
igorbenav Oct 31, 2026
d7c218d
name the app blueprint verify imports, and the test environment its c…
igorbenav Nov 4, 2026
00661ee
pin fastro at the repository root, and run its sync check in pre-comm…
igorbenav Nov 16, 2026
4bfe979
run the sync check when a commit moves the fastro pin, since another …
igorbenav Nov 16, 2026
d811716
say in the contributing guide that syncing installs fastro, that a co…
igorbenav Nov 16, 2026
93a3e16
test the facts the contributing guide states about fastro, not its wo…
igorbenav Nov 16, 2026
bfe285f
name the sync check hook in the development guide's hook table, and t…
igorbenav Nov 16, 2026
6739d4d
say in the readme that the quickstart sync installs fastro, and hold …
igorbenav Nov 17, 2026
5bce23c
name every hook and the unit test hook's command and directory in the…
igorbenav Nov 17, 2026
33a0e73
say in each row of the development guide's hook table whether ci runs…
igorbenav Nov 17, 2026
cb28fe0
correct the development guide's claim that the unit tests need no con…
igorbenav Nov 17, 2026
c270f3c
check that the unit test hook passes without docker by running it aga…
igorbenav Nov 17, 2026
a66c494
read the pre-commit config and the workflows in the catalog tests wit…
igorbenav Nov 17, 2026
44679a6
remove the left-out path filters from the docs tests, which only run …
igorbenav Nov 17, 2026
d5b74fb
cap fastapi below 0.140.7, the first release the app can't import, an…
igorbenav Nov 17, 2026
37633ac
register the tracing recipe's installer under fastro.toml's app contr…
igorbenav Nov 17, 2026
b03038b
say in the observability guide how a generated project adds the traci…
igorbenav Nov 17, 2026
b8817f1
hold the overlay test's loader in a variable and call get_source on i…
igorbenav Nov 17, 2026
04b505f
type-check blueprint/tests in ci and test that ci type-checks every b…
igorbenav Nov 17, 2026
3d01bb2
name the blueprint fastapi-boilerplate in blueprint.toml and fastro.t…
igorbenav Nov 17, 2026
4d1a889
name the FastAPI-boilerplate blueprint in full in the overlay's AGENT…
igorbenav Nov 17, 2026
e440fc9
call the blueprint FastAPI-boilerplate wherever the bare tool name st…
igorbenav Nov 17, 2026
56b5aa6
read the blueprint's name and version in the deploy template test's c…
igorbenav Nov 17, 2026
6e8b501
pass a refused secret key to the core-checks production validator tes…
igorbenav Nov 17, 2026
3b88ea2
switch the readme and docs from the old cli commands to fastro make d…
igorbenav Nov 17, 2026
df17128
replace the cli docs section with one fastro page, redirect the old c…
igorbenav Nov 17, 2026
4ed8917
move the fastro pin from ddda03f to a07bbc1
igorbenav Nov 18, 2026
7d43d23
remove the old cli package and make backend the workspace's one membe…
igorbenav Nov 18, 2026
5885aa3
give the mailpit tests a 120 second timeout and wait for mailpit to a…
igorbenav Nov 18, 2026
29bc4d7
run fastro blueprint verify in ci over every set it builds, one job e…
igorbenav Nov 18, 2026
6f72553
delete the removal drill and its test, drop it from ci, ruff, bluepri…
igorbenav Nov 18, 2026
1c72c0c
point the composable features steps, its ci table and the new module …
igorbenav Nov 18, 2026
ccb2a74
read settings from the environment and the env file when each class i…
igorbenav Nov 18, 2026
b6e910a
keep the settings build tests type-clean in every selection by passin…
igorbenav Nov 18, 2026
decd2f9
sign auth_client, auth_client_2 and superuser_auth_client in for real…
igorbenav Nov 18, 2026
ec01a8f
pin fastro at the commit that replaces the legacy deploy command with…
igorbenav Nov 19, 2026
1258c86
relock fastro at 640caae now that it's pushed, so the locked sync in …
igorbenav Nov 19, 2026
d188bc7
let accounts contribute the scope fingerprint through the generated s…
igorbenav Nov 19, 2026
c0f0b55
narrow the fastro command to a click group so mypy checks its subcomm…
igorbenav Nov 20, 2026
09bab0c
give a new account the tier DEFAULT_TIER_NAME names on the signup rou…
igorbenav Nov 20, 2026
856a6b8
name the settings classes the docs point to as the code has them, DEF…
igorbenav Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
docs/ export-ignore
zensical.toml export-ignore
.github/ISSUE_TEMPLATE/ export-ignore
10 changes: 8 additions & 2 deletions .github/workflows/linting.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,13 @@ jobs:
- name: Ruff check
# --no-sync skips uv run's implicit sync: the step above already installed
# every member and extra, and skipping it keeps each step from re-resolving.
run: uv run --no-sync ruff check backend/src backend/tests backend/scripts backend/migrations cli/src cli/tests tools
run: uv run --no-sync ruff check backend/src backend/tests backend/scripts backend/migrations blueprint/tests

- name: Ruff format
run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations cli/src cli/tests tools
run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations blueprint/tests

- name: Wiring in sync
run: uv run --no-sync fastro sync --check

- name: Blueprint lint
run: uv run --no-sync fastro blueprint lint
16 changes: 8 additions & 8 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ jobs:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only

- name: Pytest (cli)
run: cd cli && uv run --no-sync pytest
- name: Pytest (blueprint)
run: uv run --no-sync pytest blueprint/tests

removal-drills:
verify:
runs-on: ubuntu-latest
strategy:
fail-fast: false
Expand All @@ -48,6 +48,9 @@ jobs:
- accounts-api-keys
- accounts-rbac-tiers
- accounts-cache-taskiq
- minimal
- standard
- full
- everything
steps:
- uses: actions/checkout@v4
Expand All @@ -64,8 +67,5 @@ jobs:
- name: Sync workspace
run: uv sync --all-packages --all-extras --locked --python 3.11

- name: Removal drill
run: uv run --no-sync python tools/removal_drill.py ${{ matrix.preset }}
env:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only
- name: Verify
run: uv run --no-sync fastro blueprint verify ${{ matrix.preset }}
10 changes: 2 additions & 8 deletions .github/workflows/type-checking.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,8 @@ jobs:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only

- name: Mypy (cli)
run: cd cli && uv run --no-sync mypy -p cli
env:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only

- name: Mypy (tools)
run: uv run --no-sync mypy tools
- name: Mypy (blueprint tests)
run: uv run --no-sync mypy blueprint/tests
env:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only
9 changes: 4 additions & 5 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,12 @@ repos:
files: ^backend/(src|scripts|migrations|tests)/
types: [python]

- id: mypy_cli
name: Mypy (cli)
- id: fastro_sync_check
name: Wiring in sync (fastro)
language: system
entry: bash -c 'cd cli && uv run --no-sync mypy -p cli'
entry: uv run --no-sync fastro sync --check
pass_filenames: false
files: ^cli/src/
types: [python]
files: ^(blueprint\.toml|fastro\.toml|pyproject\.toml|uv\.lock|backend/src/wiring/.*|backend/scripts/seeders\.py|backend/tests/wiring\.py)$

- id: unit_test
name: Unit test
Expand Down
10 changes: 8 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,13 @@ cd FastAPI-boilerplate
uv sync --all-packages --all-extras
```

`--all-packages` installs both workspace members, and `--all-extras` brings in the
dev tools: a plain `uv sync` leaves you without ruff, mypy or pytest.
`--all-packages` installs the backend, the workspace's one member, and `--all-extras`
brings in the dev tools: a plain `uv sync` leaves you without ruff, mypy or pytest.

The sync also installs fastro, the CLI that generates projects from this blueprint
and checks it. The root `pyproject.toml` pins fastro to one commit in its `dev`
group. `uv.lock` is at lock revision 5, which uv 0.13.8 wrote, so use uv 0.13.8 or
newer.

### Activating the Virtual Environment

Expand Down Expand Up @@ -85,6 +90,7 @@ It helps in identifying simple issues before submission to code review. By runni
1. **Committing Your Changes**:
After making your changes, use `git commit -am 'Add some fooBar'` to commit them. Pre-commit will run automatically on your files when you commit, ensuring that they meet the required standards.
Note: If pre-commit identifies issues, it may block your commit. Fix these issues and commit again. This ensures that all contributions are of high quality.
A commit that touches `blueprint.toml`, `fastro.toml`, a wiring file fastro generates, the root `pyproject.toml`, or `uv.lock` also runs `uv run --no-sync fastro sync --check`, which fails when the wiring in the commit differs from what fastro generates. Run `uv run --no-sync fastro sync` to regenerate the wiring, then commit the result.
1. **Pushing Changes and Creating Pull Request**:
Push your changes to the branch using `git push origin feature/fooBar`.
Visit your fork on GitHub and create a new Pull Request to the main repository.
Expand Down
61 changes: 28 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
<h1 align="center">Fastro · The Benav Labs FastAPI Boilerplate</h1>
<h1 align="center">FastAPI-boilerplate by Benav Labs</h1>
<p align="center" markdown=1>
<i><b>Batteries-included FastAPI starter</b> - vertical-slice modules, swappable infrastructure, plugin-ready CLI.</i>
<i><b>Batteries-included FastAPI starter</b> - vertical-slice modules, swappable infrastructure, compose files written by fastro.</i>
</p>

<p align="center">
<a href="https://benavlabs.github.io/FastAPI-boilerplate">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/fastro-cover-dark.png">
<img src="docs/assets/fastro-cover-light.png" alt="Fastro - open-source FastAPI boilerplate with auth, CRUD, jobs, caching and rate-limits" width="100%">
<img src="docs/assets/fastro-cover-light.png" alt="FastAPI-boilerplate - open source, with auth, CRUD, jobs, caching and rate-limits" width="100%">
</picture>
</a>
</p>
Expand Down Expand Up @@ -47,8 +47,8 @@
* **SQLAdmin**-based admin panel (optional, env-toggled)
* [Taskiq](https://taskiq-python.github.io/) 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)
* **fastro** - generates the compose files and audits the env
* Docker Compose for local / prod / nginx-fronted (generated by fastro)
* Runs on any Postgres - the bundled container, or serverless via [Neon](https://neon.com) ([guide](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/database/neon/))

## Why and When to use it
Expand All @@ -57,7 +57,7 @@

* 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
* **A foundation that grows** - vertical-slice modules, one folder per domain
* **Docs over boilerplate** in this README - depth lives on the [docs site](https://benavlabs.github.io/FastAPI-boilerplate/)

> **Not a fit** if you need a monorepo microservices scaffold - [see the docs](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/project-structure/) for pointers.
Expand All @@ -72,20 +72,20 @@
* **Queues**: [Taskiq workers](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/background-tasks/) (Redis or RabbitMQ)
* **Rate limits**: [per-tier + per-path rules](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/rate-limiting/)
* **Admin**: [SQLAdmin views](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/admin-panel/) (optional, env-toggled)
* **CLI**: [`bp` tool](https://benavlabs.github.io/FastAPI-boilerplate/cli/) for compose scaffolding, env audits, and plugin extensions
* **fastro**: compose scaffolding and env audits

## Fastro vs FastroAI
## FastAPI-boilerplate vs FastroAI

This boilerplate - **Fastro** - is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well.
**FastAPI-boilerplate** is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well.

| | **Fastro** (this repo · free) | **FastroAI** (paid) |
| | **FastAPI-boilerplate** (this repo · free) | **FastroAI** (paid) |
|---|:---:|:---:|
| FastAPI + SQLAlchemy 2.0, Pydantic v2 | ✓ | ✓ |
| Auth - sessions, OAuth, API keys | ✓ | ✓ **+ JWT** |
| FastCRUD · SQLAdmin · Alembic | ✓ | ✓ |
| Caching · rate limiting · Taskiq jobs | ✓ | ✓ |
| Docker (local / prod / nginx) | ✓ | ✓ |
| `bp` CLI - scaffolding, env audit, plugins | ✓ | |
| fastro - compose scaffolding, env audit | ✓ | |
| **Payments** - Stripe: subscriptions, credits, discounts, webhooks | | ✓ |
| **Entitlements** - feature gating by plan/tier | | ✓ |
| **Transactional email** & notifications | | ✓ |
Expand All @@ -98,51 +98,49 @@ This boilerplate - **Fastro** - is the free, open-source **foundation**: everyth
<a href="https://fastro.ai">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/fastroai-card-dark.png">
<img src="docs/assets/fastroai-card-light.png" alt="FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of Fastro" width="100%">
<img src="docs/assets/fastroai-card-light.png" alt="FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of FastAPI-boilerplate" width="100%">
</picture>
</a>
</p>

**Stick with Fastro** if you want a clean, hackable FastAPI backend to build on.
**Stick with FastAPI-boilerplate** if you want a clean, hackable FastAPI backend to build on.
**[Get FastroAI →](https://fastro.ai)** if you're shipping a SaaS - AI or not - and want billing, entitlements, email, auth, and a frontend ready out of the box.

## Repo Layout

This is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with two members. One venv at the root covers both.
This is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with one member, `backend/`. One venv at the root holds it and fastro.

```text
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/
└── backend/ # the deployable application
├── src/ # interfaces/, infrastructure/, modules/
├── pyproject.toml
└── Dockerfile # multi-stage: dev / migrate / prod
```

## Quickstart

```bash
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
uv sync --all-packages --all-extras # one venv at the root: the backend, plus fastro
```

Generate a compose file for the deployment shape you want:

```bash
uv run --no-sync bp deploy generate local # hot-reload dev stack
# or: uv run --no-sync bp deploy generate prod # production single-host
# or: uv run --no-sync bp deploy generate nginx # production behind nginx
uv run --no-sync fastro make deploy local # hot-reload dev stack
# or: uv run --no-sync fastro make deploy prod # production single-host
# or: uv run --no-sync fastro make deploy nginx # production behind nginx
```

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

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

Bring it up:
Expand All @@ -168,22 +166,19 @@ uv run --no-sync taskiq worker src.infrastructure.taskiq.worker:default_broker

```bash
# generate a fresh production-ready compose file
uv run --no-sync bp deploy generate prod --workers 8
uv run --no-sync fastro make deploy prod --workers 8

# audit your .env against the production security validator
uv run --no-sync bp env validate
uv run --no-sync fastro env validate

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

# run tests
cd backend && uv run --no-sync 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](https://benavlabs.github.io/FastAPI-boilerplate/).
More examples (superuser creation, tiers, rate limits, admin usage) in the [docs](https://benavlabs.github.io/FastAPI-boilerplate/).

## Sponsors

Expand Down
Loading
Loading