Building a Production-Ready FastAPI Boilerplate with Clean Architecture

I Built a Production-Ready FastAPI Boilerplate (So You Don't Have To)

Starting a new FastAPI project? You know the drill: configure linting, set up auth, write Docker files, configure tests... Hours wasted before writing a single feature.

So I built a boilerplate that does all of this for you.

🎯 What's Inside?

Architecture

• ✅ Clean Architecture (routes → services → repositories → models)
• ✅ Repository Pattern
• ✅ Dependency Injection
• ✅ Type hints everywhere

Authentication

• ✅ Complete JWT implementation
• ✅ Refresh tokens (stored in database)
• ✅ Password hashing (bcrypt)

Developer Experience

• ✅ All tools pre-configured: Black, Ruff, MyPy, Bandit
• ✅ Pre-commit hooks
• ✅ Makefile with useful commands
• ✅ 1500+ lines of documentation

Testing & DevOps

• ✅ Pytest with fixtures
• ✅ Docker & Docker Compose
• ✅ GitHub Actions CI/CD
• ✅ PostgreSQL + SQLite support

🏗️ Architecture

API Layer (FastAPI)
    ↓
Schemas (Pydantic DTOs)
    ↓
Services (Business Logic)
    ↓
Repositories (Data Access)
    ↓
Models (SQLAlchemy)

Why this structure?

• Each layer has one responsibility
• Easy to test (mock any layer)
• Easy to swap implementations
• Scales well

📝 Quick Example: User Registration

# 1. API receives request
@router.post("/register", response_model=UserResponse)
async def register(user_data: UserCreateDTO, service: UserService = Depends()):
    return service.create_user(user_data)

# 2. Service applies business logic
class UserService:
    def create_user(self, user_data: UserCreateDTO) -> User:
        if self.repo.get_by_email(user_data.email):
            raise ValueError("Email exists")
        return self.repo.create(user_data)

# 3. Repository talks to database
class UserRepository: 
    def create(self, user_data: UserCreateDTO) -> User:
        user = User(email=user_data.email, 
                   hashed_password=hash_password(user_data.password))
        self.db.add(user)
        self.db.commit()
        return user

Clean, testable, maintainable. ✨

🚀 Getting Started

# 1. Use as template (click button on GitHub)
# 2. Clone your repo
git clone your-new-repo

# 3. Setup
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 4. Configure
cp .env.example .env

# 5. Run
make dev

Visit http://localhost:8000/docs - you have a working API with auth!

🛠️ Developer Tools

Everything is configured. Just use it:

make format   # Black + isort
make lint     # Ruff + MyPy
make test     # Pytest with coverage
make security # Bandit + Safety
make docker-up # Start everything

🔐 Security Built-In

• JWT tokens (short-lived access + refresh)
• Password hashing (bcrypt)
• Security scanning (Bandit, Safety)
• Pre-commit hooks prevent issues
• CORS configured

📚 Documentation

Not just a README. Actual guides:

• Usage Guide (300+ lines) - How to develop, test, deploy
• Architecture Doc - Why decisions were made
• Contributing Guide - How to contribute

🎁 What You Get

Skip all the boring setup:

• ❌ No more "how do I structure this?"
• ❌ No more configuring linting tools
• ❌ No more setting up auth from scratch
• ❌ No more writing Docker files
• ❌ No more CI/CD configuration

✅ Just start building features.

🤔 Why Another Boilerplate?

Most boilerplates:

• Flat structure (everything in one place)
• Minimal docs
• Basic auth (if any)
• No tests
• No dev tools

This one:

• Clean architecture
• Comprehensive docs
• Complete auth system
• Full test suite
• All dev tools configured

📦 Try It

GitHub: Alwil17/fastapi-boilerplate

Click "Use this template" → Start building in minutes.

---

⭐ If you find it useful, give it a star on GitHub!

Questions? Drop them below! 👇

---

Tech Stack: FastAPI • SQLAlchemy • PostgreSQL • Docker • JWT • Pytest • GitHub Actions

Python #FastAPI #CleanArchitecture #Boilerplate