Enterprise FastAPI Template

An enterprise-level FastAPI backend template built with MongoDB and Redis. Features comprehensive CRUD operations, caching, dependency injection, and a clean layered architecture with best practices.

Features

• 📝 Todo Management: Complete CRUD operations for todos with status tracking, priorities, and tags
• 💾 MongoDB Integration: Async MongoDB with proper indexing and data modeling
• ⚡ Redis Caching: Intelligent caching for improved performance
• 🏗️ Clean Architecture: Layered architecture with separation of concerns and clear boundaries
• 🔧 Dependency Injection: Enterprise-grade DI using dependency-injector with declarative containers and auto-wiring
• ⚙️ Configuration Management: Environment-based config with type-safe Pydantic settings
• 🧪 Comprehensive Testing: Unit tests and integration tests with high coverage
• 📚 API Documentation: Auto-generated OpenAPI/Swagger documentation
• 🐳 Docker Support: Local development infrastructure with docker-compose
• 🎯 Template Ready: Production-ready template with enterprise patterns (Factory, Repository, Service Layer)

Tech Stack

• FastAPI: Modern, fast web framework for building APIs with automatic OpenAPI documentation
• MongoDB: NoSQL database with Motor async driver for high-performance data operations
• Redis: In-memory caching and session storage for improved performance
• Pydantic: Data validation, serialization, and settings management with type safety
• dependency-injector: Enterprise-grade dependency injection framework with declarative containers and auto-wiring
• Docker: Containerization for consistent local development environment
• Pytest: Testing framework with async support for comprehensive test coverage
• Poetry: Modern dependency management and packaging tool
• Ruff: Fast Python linter and formatter for code quality
• MyPy: Static type checking for better code reliability and IDE support

Why This Template? 🤔

This template addresses common FastAPI pain points that plague enterprise development. If you've ever struggled with:

• Global variable nightmares that make testing impossible
• Router-Service-Repository patterns that don't scale beyond tutorials
• Missing enterprise structure compared to frameworks like NestJS
• Massive pyproject.toml files with scattered configurations
• Test files living in exile far from source code

Then this template is for you! We've solved these architectural challenges with:

✅ Proper dependency injection with dependency-injector's declarative containers
✅ Domain-driven module structure that scales with teams
✅ Enterprise patterns ready for production
✅ Clean configuration separation across dedicated files
✅ Co-located tests right next to source code

📖 Read the full analysis: FastAPI Pain Points: A Developer's Survival Guide

Development Environment Setup

Prerequisites

Before starting, ensure you have Docker Desktop installed and running:

• Docker Desktop: Download and install from docker.com
  • Required for local MongoDB and Redis infrastructure
  • Make sure Docker Desktop is running before proceeding

Setup Steps

0. Install Homebrew

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. Clone the repository

   git clone git@github.com:your-username/enterprise-fastapi-template.git
   cd enterprise-fastapi-template

2. Install tools using Homebrew

   # Install pyenv and pipx
   brew install pyenv pipx
   
   # Configure pyenv in shell
   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
   echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
   echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc
   source ~/.zshrc
   
   # Install Poetry using pipx
   pipx install poetry

3. Install Python version (pyenv will read from .python-version file)

   # Install the Python version specified in .python-version
   pyenv install

4. Install dependencies

   poetry install

5. Setup development environment

   poetry run poe setup

6. Set up environment variables

   cp .env.example .env.local
   # Edit .env.local with your configuration

7. Start local infrastructure (MongoDB & Redis)

   poetry run poe infra-up

8. Start the development server

   poetry run poe local

Links

Service	URL	Description
API Documentation	http://localhost:8000/docs	Interactive Swagger UI documentation
Alternative Docs	http://localhost:8000/redoc	ReDoc API documentation
Health Check	http://localhost:8000/health	Service health status endpoint

All Commands

Development Commands

Use Poe the Poet for all development tasks.

Command	Description
poetry run poe setup	Setup development environment (first-time)
poetry run poe infra-up	Start local infrastructure (MongoDB & Redis)
poetry run poe infra-down	Stop local infrastructure
poetry run poe infra-logs	View infrastructure logs
poetry run poe local	Local development mode (loads .env.local)
poetry run poe dev	Development mode (loads .env.dev)
poetry run poe staging	Staging mode (loads .env.staging)
poetry run poe prod	Production mode (loads .env.prod)
poetry run poe test	Run all tests (unit + integration)
poetry run poe test-unit	Run unit tests only
poetry run poe test-int	Run integration tests only
poetry run poe test-cov	Run tests with coverage report
poetry run poe lint	Run Ruff linting with auto-fix
poetry run poe format	Run Ruff code formatting
poetry run poe type-check	Run MyPy type checking
poetry run poe check	Run all checks (lint + format + type-check)
poetry run poe clean	Clean cache files and build artifacts

Poetry Commands

Command	Description
poetry add requests	Add a new production dependency
poetry add --group dev pytest	Add a development dependency
poetry install	Install all dependencies from pyproject.toml
poetry update	Update all dependencies to latest versions
poetry show --tree	Show dependency tree
poetry env info	Show virtual environment information

Python Version Management Commands

Command	Description
pyenv install	Install Python version from .python-version file
pyenv local 3.12.0	Set Python version for current project
pyenv global 3.12.0	Set Python version as system default

Note: This project includes a .python-version file that specifies Python 3.12.0. When you run pyenv install without arguments, it will automatically install the version specified in this file.

Code Quality Commands

Command	Description
poetry run poe check	Run all checks (lint + format + type-check)
poetry run poe lint	Ruff linting with auto-fix
poetry run poe format	Ruff code formatting
poetry run poe type-check	MyPy type checking

Pre-commit Commands

Command	Description
poetry run poe pre-commit-install	Install pre-commit hooks
poetry run poe pre-commit-run	Run all pre-commit hooks on all files
poetry run poe pre-commit-update	Update pre-commit hook versions
poetry run pre-commit uninstall	Uninstall pre-commit hooks

Commit Message Conventions

Conventional Commit Format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Examples:

• feat: add user authentication
• fix: resolve database connection issue
• docs: update README with new instructions
• refactor: simplify user validation logic