Why project structure matters at scale in FastAPI - See It in Action

Why project structure matters at scale

📖 Scenario: You are building a simple FastAPI application to manage a small library of books. As the app grows, organizing your code well will help keep it easy to understand and maintain.

🎯 Goal: Build a FastAPI app with a clear project structure by creating a data list, a configuration variable, a route to get books, and finally include the router in the main app.

📋 What You'll Learn

Create a list of books with exact titles and authors

Add a configuration variable for the API prefix

Create a FastAPI router with a GET endpoint to return the books list

Include the router in the main FastAPI app with the prefix

💡 Why This Matters

🌍 Real World

Organizing FastAPI projects clearly helps teams work together and makes adding features easier.

💼 Career

Understanding project structure is key for backend developers building scalable APIs with FastAPI.

1

Create the initial data list

Create a list called books with these exact dictionaries: {'title': '1984', 'author': 'George Orwell'}, {'title': 'Brave New World', 'author': 'Aldous Huxley'}, and {'title': 'Fahrenheit 451', 'author': 'Ray Bradbury'}.

FastAPI

# Create the books list with exact entries
# Your code here

Hint

Use a list of dictionaries with the exact keys and values given.

2

Add API prefix configuration

Create a string variable called API_PREFIX and set it to "/library".

FastAPI

books = [
    {'title': '1984', 'author': 'George Orwell'},
    {'title': 'Brave New World', 'author': 'Aldous Huxley'},
    {'title': 'Fahrenheit 451', 'author': 'Ray Bradbury'}
]
# Create API_PREFIX variable
# Your code here

Hint

Just assign the string "/library" to API_PREFIX.

3

Create a FastAPI router with GET endpoint

Import APIRouter from fastapi. Create a router called router. Add a GET endpoint /books to router that returns the books list.

FastAPI

books = [
    {'title': '1984', 'author': 'George Orwell'},
    {'title': 'Brave New World', 'author': 'Aldous Huxley'},
    {'title': 'Fahrenheit 451', 'author': 'Ray Bradbury'}
]

API_PREFIX = "/library"

# Import APIRouter and create router
# Add GET /books endpoint returning books
# Your code here

Hint

Use @router.get("/books") decorator and an async function returning books.

4

Include the router in the main FastAPI app

Import FastAPI from fastapi. Create an app called app. Include the router in app using API_PREFIX as the prefix.

FastAPI

from fastapi import APIRouter

books = [
    {'title': '1984', 'author': 'George Orwell'},
    {'title': 'Brave New World', 'author': 'Aldous Huxley'},
    {'title': 'Fahrenheit 451', 'author': 'Ray Bradbury'}
]

API_PREFIX = "/library"

router = APIRouter()

@router.get("/books")
async def get_books():
    return books

# Import FastAPI, create app, and include router with prefix
# Your code here

Hint

Use app.include_router(router, prefix=API_PREFIX) to add the router.

Practice

1. Why is having a clear project structure important when building a FastAPI app that will grow over time?

easy

A. It keeps the code organized and easier to maintain as the app grows.

B. It makes the app run faster by optimizing imports.

C. It automatically fixes bugs in the code.

D. It reduces the size of the app's files on disk.

Solution

1. Step 1: Understand the role of project structure

   A clear project structure organizes code logically, making it easier to find and update parts as the app grows.

2. Step 2: Consider the impact on maintenance

   Without good structure, code becomes messy and hard to maintain, especially with many files and developers.

3. Final Answer:

   It keeps the code organized and easier to maintain as the app grows. -> Option A

4. Quick Check:

   Project structure = organized, maintainable code [OK]

Hint: Good structure means easier teamwork and maintenance [OK]

Common Mistakes:

• Thinking structure speeds up runtime
• Believing structure fixes bugs automatically
• Confusing file size with structure benefits

2. Which of the following is the correct way to organize FastAPI routes in a large project?

easy

A. Put all routes in a single main.py file regardless of size.

B. Split routes into separate files or folders by feature or module.

C. Write routes inside the database models file.

D. Place routes randomly in any folder without naming conventions.

Solution

1. Step 1: Identify best practice for route organization

   Splitting routes by feature or module keeps code clean and easier to navigate.

2. Step 2: Evaluate other options

   Putting all routes in one file or mixing routes with models causes confusion and harder maintenance.

3. Final Answer:

   Split routes into separate files or folders by feature or module. -> Option B

4. Quick Check:

   Route organization = split by feature [OK]

Hint: Group routes by feature for clarity [OK]

Common Mistakes:

• Keeping all routes in one file
• Mixing routes with unrelated code
• Ignoring naming conventions

3. Given this FastAPI project structure snippet:

app/
  main.py
  users/
    __init__.py
    routes.py
    models.py
  items/
    __init__.py
    routes.py
    models.py

What is the main benefit of this structure when the app grows?

medium

A. It automatically generates API documentation without extra code.

B. It forces all code to run sequentially, improving speed.

C. It allows importing routes and models by feature, reducing conflicts.

D. It stores all data in a single file for easy access.

Solution

1. Step 1: Analyze the folder grouping by feature

   Each feature (users, items) has its own routes and models, which helps keep code modular and avoids naming conflicts.

2. Step 2: Understand benefits of modular imports

   This structure allows importing only needed parts, making code clearer and easier to maintain.

3. Final Answer:

   It allows importing routes and models by feature, reducing conflicts. -> Option C

4. Quick Check:

   Feature folders = modular imports [OK]

Hint: Feature folders help avoid code conflicts [OK]

Common Mistakes:

• Assuming structure affects execution speed
• Confusing structure with automatic docs generation
• Thinking data is stored in code files

4. You see this error when running a FastAPI app:

ImportError: cannot import name 'users' from 'app'

Given this structure:

app/
  __init__.py
  main.py
  users.py

What is the likely cause?

medium

A. The import statement is incorrect because users.py is a file, not a package.

B. The main.py file is not inside the app folder.

C. The users.py file is missing an __init__.py file to be recognized as a package.

D. FastAPI requires all files to be named routes.py.

Solution

1. Step 1: Understand Python import rules

   Importing 'users' from 'app' expects 'users' to be a package (folder with __init__.py), but here users.py is a file.

2. Step 2: Identify correct import method

   To import users.py, use 'from app import users' if app is a package, or adjust import to match file structure.

3. Final Answer:

   The import statement is incorrect because users.py is a file, not a package. -> Option A

4. Quick Check:

   File vs package import difference = error cause [OK]

Hint: Files import differently than folders with __init__.py [OK]

Common Mistakes:

• Assuming __init__.py is needed for single files
• Ignoring import syntax for files vs packages
• Blaming FastAPI naming rules

5. You want to scale your FastAPI app with multiple teams working on different features. Which project structure approach best supports this?

hard

A. Use a random folder structure and rely on comments to explain code locations.

B. Put all code in one large file to avoid confusion about where code lives.

C. Separate code by file type only, like all routes in one folder and all models in another.

D. Organize the app into feature-based folders each with their own routes, models, and services.

Solution

1. Step 1: Consider team collaboration needs

   Feature-based folders let teams work independently on their parts without conflicts.

2. Step 2: Compare with other structures

   One large file or separating only by file type causes confusion and merge conflicts as app grows.

3. Step 3: Understand maintainability at scale

   Clear, consistent structure reduces bugs and speeds up development for multiple teams.

4. Final Answer:

   Organize the app into feature-based folders each with their own routes, models, and services. -> Option D

5. Quick Check:

   Feature folders = best for team scaling [OK]

Hint: Feature folders help teams work independently [OK]

Common Mistakes:

• Using one big file for all code
• Separating only by file type, not feature
• Ignoring structure importance for teams