teamhide/fastapi-boilerplate: A Production-Oriented FastAPI Starting Point

What the boilerplate includes for a new FastAPI service

This repository targets developers starting a Python API that will use FastAPI and an asynchronous database layer. Its stated problem is broader than providing a minimal application factory. The repository contains an `app/` tree, `core/` modules, `celery_task/`, migrations, tests, a `Makefile`, Docker files and a `pyproject.toml`. That structure gives a service team a place for routers, shared infrastructure, background tasks and database evolution instead of assembling each concern from scratch.

The feature list includes an async SQLAlchemy session, a custom user class, permission dependencies, Celery, Docker hot reload, an event dispatcher and caching. The package metadata also identifies FastAPI, Uvicorn, Alembic, Redis, PyMySQL, aiomysql, dependency-injector, pydantic-settings, PyJWT and cryptography as project dependencies. This is a useful fit for a service that already expects asynchronous database access and background processing. It is less suitable for a small synchronous script, a data-only worker or an API whose operational requirements do not include these components.

The repository is not archived, and its last push was on 2026-05-08. It has no GitHub releases. The license is not identified in the project metadata, so redistribution and internal reuse should be checked directly with the repository owner rather than assumed from the code layout.

How the async database and authentication flow is organized

The database example centers on `Transactional` and a globally provided `session`. A write method adds a `User` inside a `@Transactional()` decorated function, while the README explicitly says that the class handles the commit. The repository therefore expects transaction boundaries to be expressed through the decorator rather than through explicit `commit()` calls in each service function.

Concurrent reads are treated differently. When queries run through `asyncio.gather()`, the documented pattern opens each operation with `session_factory()` and executes the query inside that context. The global session is recommended for ordinary database work such as `session.add()`, but the README distinguishes it from concurrent query sessions. That distinction matters because sharing one asynchronous session across concurrent operations can produce unclear transaction and connection behavior. The repository gives a concrete mechanism here, though it does not document a general connection-pool sizing policy.

Authentication is implemented through a custom user class. The example accesses `request.user.id` from a route handler. The documentation says the middleware decodes the header token and stores user information in `request.user`, and it requires a JWT supplied through an `Authorization: Bearer 1234` header. The customization points are `core/fastapi/schemas/current_user.py` and `core/fastapi/middlewares/authentication.py`. The sample `CurrentUser` model only declares an `id` field. The README does not explain token issuance, expiration policy, refresh behavior or key storage, so an adopter must inspect those files before treating the authentication path as production-ready.

A first local run with Docker, Poetry and Alembic

The README presents Docker as the main launch path and provides separate commands for dependency installation, migration and server startup. The commands below are copied from the repository documentation. The shell prompts shown in the README are omitted because they are not part of the command itself.

Start the Docker Compose services from the repository's Docker directory:

docker-compose -f docker/docker-compose.yml up

For a local Poetry environment, create or enter the shell and install dependencies:

poetry shell
poetry install

Apply the latest Alembic migration before starting the application:

alembic upgrade head

Then start the server with an environment selector and debug flag:

python3 main.py --env local|dev|prod --debug

The literal pipe in `local|dev|prod` reflects the README's usage notation, not a verified shell argument. The documentation does not specify the required database credentials, Redis settings or environment-file contents, so a first run cannot be reproduced from the README alone. The repository does provide test and coverage entry points in its `Makefile`, but those commands depend on a test environment and service configuration that are not fully described.

Permissions, caching and background processing boundaries

Permission checks are implemented as FastAPI dependencies. The built-in examples include `IsAdmin`, `IsAuthenticated` and `AllowAll`. A route can attach `PermissionDependency([IsAdmin])` through the `dependencies` argument, and custom permissions are expected to inherit `BasePermission` and implement `has_permission()`. The README also notes that Swagger's authorize function requires `PermissionDependency` in the dependencies list. This design keeps authorization attached to route registration, which is more explicit than scattering checks throughout handlers.

Caching is decorator-based. `@Cache.cached(prefix="get_user", ttl=60)` provides prefix-based invalidation, while `CacheTag` provides tag-based invalidation. The documentation says the cached return value is stored under a key derived from the function arguments. `BaseKeyMaker` is the extension point for custom keys, and `BaseBackend` defines the get, set and prefix deletion interface. The backend and key maker are initialized in `/app/server.py` through `Cache.init()`.

Celery appears as both a project directory and a dependency, but the README does not provide a task definition, broker configuration, worker startup command or failure policy. Likewise, the event dispatcher documentation points to the separate `fastapi-event` project rather than explaining local configuration. These features are useful building blocks, but the boilerplate does not make the surrounding operational design complete. You would need to verify broker, cache backend and event behavior in the corresponding configuration files before relying on them.

Migrations, testing and dependency management

Database changes are managed with Alembic. The repository includes `alembic.ini` and a `migrations/` directory, and the documented startup flow applies revisions with `alembic upgrade head`. This is a conventional migration boundary, which is preferable to changing an existing schema implicitly during application startup. The README does not document a downgrade command, migration review process or deployment strategy for running migrations against multiple environments.

The `Makefile` exposes a focused test target and a coverage target. The test target runs `ENV=test pytest tests -s`, while coverage runs `coverage run -m pytest` and then generates an HTML report. `pytest.ini`, `tests/` and the coverage configuration are present, so tests are part of the intended project structure. The available documentation does not state which external services must be running for the tests or whether the suite uses isolated databases.

Dependency versions are pinned in `pyproject.toml`, including `python = "3.11.7"`, FastAPI `^0.109.1`, SQLAlchemy `^2.0.25`, Alembic `^1.13.1`, Celery `^5.3.6` and Redis `^5.0.1`. `poetry.lock` is included, which gives the project a lockfile for repeatable Poetry installs. The project is still a version `0.2.0` package with no GitHub release history, so version labels should not be interpreted as a public release or support commitment.

Where this boilerplate is the wrong tool

The clearest wrong-tool case is a small API that needs only FastAPI routes and a synchronous database. Importing the full set of async SQLAlchemy, Celery, Redis, event and permission patterns would add concepts without a documented requirement. Another mismatch is a team that expects a complete production deployment. The repository provides Docker Compose hot reload and a Gunicorn dependency, but the README does not describe health checks, structured logging configuration, metrics, secret injection, database migration deployment, graceful shutdown or rollback.

The database example also carries a real constraint: concurrent reads require `session_factory` context managers rather than the globally used session. Code that ignores this distinction can create incorrect assumptions about session isolation and concurrent query execution. The custom `CurrentUser` sample contains only `id`, so an application needing roles, tenant IDs or other claims must change both the schema and middleware according to the README.

A real alternative is a bare FastAPI project with Uvicorn and SQLAlchemy managed directly by the application team. That approach has fewer repository conventions, but it requires building migrations, transaction handling, authentication, caching and background-task wiring separately. This boilerplate is more productive when those concerns are already desired; it is a poorer fit when the project needs a minimal or unusually different architecture.

Maintenance, licensing and upgrade implications

The repository is not archived, and the last push was on 2026-05-08. That fact establishes recent repository activity at that point, but the repository has no GitHub releases and the README does not define a release policy, supported-version policy or migration guide for upgrades. There is therefore no documented compatibility promise for upgrading FastAPI, SQLAlchemy, Celery or the surrounding dependencies.

The project metadata does not identify a license. That is a material adoption constraint for any organization planning to modify and redistribute the template. Reviewers should inspect the repository's license file or contact its owner before distributing the code as part of a product. The license question is separate from technical suitability: an unrestricted dependency list does not make the boilerplate's own code licensed under a known permissive agreement.

The upgrade path has two concrete pieces. First, `poetry.lock` and `pyproject.toml` define the dependency baseline. Second, Alembic migrations define the database path. Neither mechanism documents how to test a framework upgrade across application code, authentication changes or deployment infrastructure, so dependency updates require project-specific validation rather than a blind lockfile refresh.

Editorial conclusion

Adopt this repository when your next service needs the specific FastAPI, async SQLAlchemy, Celery, Redis and permission scaffolding shown in the repository. Do not treat it as a finished production service, because the README does not define deployment hardening, secret management, observability or rollback procedures. Verify the Python 3.11.7 environment, database configuration, authentication behavior and Docker dependencies before building application logic on top of it.

Frequently asked questions

Official sources

1. Issues
2. README
3. teamhide/fastapi-boilerplate on GitHub