A Complete Guide to FastAPI Project Structures

“FastAPI is one of the fastest-growing Python frameworks, loved for its simplicity, performance, and flexibility. But because FastAPI is unopinionated, there is no single “official” FastAPI project structures.

This is beneficial—it gives you freedom.

But it’s also challenging—how do you know which structure is right?

So, it’s important for backend developers to understand project structure, which is the architecture of the application. We will cover DDD and Clean Architecture, and how we can create a project design based on Clean Architecture. For starters like me, it is very confusing, as many tutorials don’t teach which project structure is recommended and when to use it.

In this guide, we’ll learn:

1. Example folder layouts for each”Let’s dive in.
2. The most commonly used FastAPI project structures
4. How horizontal (layered) architecture works
5. How vertical (feature-based) architecture works
6. When to choose one over the other

Mine FastAPI project structures

Im learning FastAPI, I’m following Clean Architecture principles as much as possible and below is mine project structure.

Mine project structure follows a horizontal (layered) organization, which is a common approach for implementing the principles of Clean Architecture and i know its need lots of improvement.

app/
├── config.py
├── routes/
├── repository/
├── schemas/
├── services/
└── db/
    ├── models/
    ├── database.py
    ├── db.db
    └── init_db.py

🚀 Improvements suggestion from chatgpt

As searching through chatgpt, got following suggestion of improvement of the project structure.

1. Separate core config from app logic: Common pattern for FastAPI, Flask, Django

app/core/config.py

2. Organize routes using “versions”: Easier for API evolution.

app/api/v1/users.py
app/api/v1/auth.py
app/api/router.py

3. db/structure refinement

Rename database.py → session.py. Keep Base in a dedicated base.py to avoid import cycles.

app/db/session.py      # engine, SessionLocal, get_db()
app/db/base.py         # Base and import models

Place db.db inside /data/ or root, not inside source code.

project/data/db.db

5. init_db.py only for dev

Creating tables using create_all() is okay only for development. In production, use Alembic migrations.

---

⭐ Why Project Structure Matters

Choosing the right structure affects:

• Scalability
• Maintainability
• Onboarding new developers
• Testing
• Code clarity
• Separation of concerns

A good structure ensures that as your application grows, it does not become a tangled mess.

---

1. 🧱 Horizontal / Layered Architecture (Most Common)

This structure organizes your project by technical layers, not by domain or feature, here is full details of horizontal architecture.

Example:

project/
│
├── .env
├── main.py
├── alembic/                # (Optional but recommended for DB migrations)
├── app/
│   ├── core/               # Core configuration and initialization
│   │   ├── config.py       # Pydantic Settings, app config
│   │   ├── security.py     # Auth utilities (JWT/OAuth2)
│   │   └── logging.py      # Centralized logging config
│   │
│   ├── api/
│   │   ├── deps.py         # Common dependencies for routes
│   │   ├── v1/
│   │   │   ├── __init__.py
│   │   │   ├── users.py     # One file per domain route
│   │   │   ├── auth.py
│   │   │   └── items.py
│   │   └── router.py        # APIRouter aggregator
│   │
│   ├── db/
│   │   ├── base.py      # Base = declarative_base(), import all models here
│   │   ├── session.py       # engine, SessionLocal, get_db dependency
│   │   ├── init_db.py       # create_all (only for dev, not for prod)
│   │   └── models/
│   │       ├── user.py
│   │       ├── item.py
│   │       └── __init__.py
│   │
│   ├── repositories/
│   │   ├── user_repo.py
│   │   ├── item_repo.py
│   │   └── __init__.py
│   │
│   ├── services/
│   │   ├── user_service.py
│   │   ├── auth_service.py
│   │   └── __init__.py
│   │
│   ├── schemas/
│   │   ├── user.py
│   │   ├── item.py
│   │   └── __init__.py
│   │
│   ├── utils/
│   │   ├── helpers.py
│   │   └── email_utils.py
│   │
│   └── __init__.py
│
└── requirements.txt / pyproject.toml

This is the architecture used by many production FastAPI applications.

⭐ Why teams use it

• Clear separation of concerns
• Easy to test individual layers
• Works well for small and medium apps
• Familiar to developers from Django/Flask/Java backgrounds

⭐ Pros

✔ Clean, predictable structure
✔ Easy to read and navigate
✔ Modules are decoupled
✔ Good for CRUD-heavy apps
✔ Ideal for monolithic services

⭐ Cons

✘ As your app grows, files become scattered
✘ Business logic can spread across multiple folders
✘ Adding new features often means editing many folders

⭐ When to choose Horizontal / Layered

Choose this architecture if:

• Your app is small to medium-sized
• You want maximum clarity and organization
• You have few developers on the team
• You value technical separation (e.g., controllers/services/repositories)
• You’re building an internal API, CRM, admin tool, or SaaS backend

This is the most common structure for FastAPI.

---

2. 📦 Vertical / Feature-Based Architecture (Very Common for Large Apps)

Instead of organizing by layers, you organize by feature/domain.

Example:

app/
├── users/
│   ├── models.py
│   ├── schemas.py
│   ├── routes.py
│   ├── repository.py
│   ├── service.py
│   └── __init__.py
│
├── auth/
│   ├── routes.py
│   ├── service.py
│   ├── schemas.py
│   └── models.py
│
└── core/
    ├── config.py
    ├── database.py
    └── security.py

Each feature contains everything it needs. This approach is widely used in microservices, domain-driven design, and large enterprise systems.

⭐ Why teams use it

• All files for a feature are kept together
• Easy for multiple developers to work independently
• Fewer cross-module imports
• Features are modular and isolated

⭐ Pros

✔ Perfect for large-scale applications
✔ Each feature is self-contained
✔ Easier refactoring
✔ Easier to convert features into microservices later
✔ Very clean boundaries

⭐ Cons

✘ Harder to maintain shared logic if not planned well
✘ Beginners may find it unfamiliar
✘ Can duplicate code across features
✘ Requires discipline to avoid cross-dependencies

⭐ When to choose Vertical / Feature-Based

Choose this architecture if:

• Your application will grow large
• You have many developers working in parallel
• You want isolated modules
• You’re following Domain Driven Design (DDD)
• You may split the app into microservices later

This is the best architecture for enterprise-level FastAPI apps.

---

3. Minimal / Flat Structure (Good for learning)

For very small or prototype apps:

app/
├── main.py
├── routes.py
├── models.py
├── schemas.py
└── database.py

Great for:

• Tutorials
• Demos
• MVPs

Not recommended for production.

---

4. Hybrid Architecture (Popular in Real Teams)

Some teams combine both:

• Shared layers for common logic
• Feature folders for large modules

Example:

app/
├── core/
├── db/
├── common/
│   ├── utils.py
│   └── dependencies.py
│
├── features/
│   ├── users/
│   ├── items/
│   └── auth/

This is often the most practical structure for very large projects.

---

🧭 Which Architecture Should You Choose?

Here’s a quick cheat sheet:

App Size	Team Size	Best Choice
Tiny / prototype	1	Minimal
Small	1–3	Layered (horizontal)
Medium	3–10	Layered or Hybrid
Large	10+	Vertical (feature-based) or Hybrid
Microservices	Any	Vertical

---

Related Artciles

1. Introduction to FastAPI
2. FastAPI Clean Architecture: A Developer’s Practical Guide
3. Understanding the Relationship Between FastAPI, SQLAlchemy, ORM, and Database Connections