Skip to content

FastAPI Application Layers

A well-structured FastAPI application is organized into several layers, each with a clear responsibility. This separation of concerns makes your codebase easier to maintain, test, and scale. Below are the typical layers you should find in a FastAPI project:

1. Model Layer (models.py)

  • Defines ORM models that map to your database tables (e.g., using SQLModel or SQLAlchemy).
  • Example: User class describing the structure and types of your data as stored in the database.

2. Schema Layer (schemas.py)

  • Defines Pydantic models for data validation, serialization, and deserialization.
  • Used for request and response bodies in your API endpoints.
  • Keeps your API contracts separate from your database models.

3. Service Layer (services.py)

  • Contains business logic and operations that act on your models.
  • Implements higher-level operations, such as bulk create, update, delete, or more complex workflows.
  • Sits between the API routes and the database/ORM layer, making your code more modular and testable.

4. CRUD Layer (crud.py) (optional)

  • Contains basic Create, Read, Update, Delete functions that directly interact with the database.
  • Keeps raw database access logic separate from business logic.
  • In some projects, CRUD logic is merged into the service layer.

5. Routes Layer (routes.py)

  • Defines the API endpoints (HTTP routes) and connects them to the service or CRUD functions.
  • Handles request/response, dependency injection, and error handling.

6. Dependencies Layer (dependencies.py)

  • Contains reusable dependency functions for authentication, authorization, database sessions, etc.
  • Used with FastAPI’s Depends system to inject shared logic into routes.

Typical Flow in a FastAPI App

  • Client Request → Route → Service/CRUD → Model/Database
  • Database Result → Model → Schema → Route → Client Response

Example File Structure

users/
    models.py      # ORM models
    schemas.py     # Pydantic schemas
    services.py    # Business logic
    crud.py        # (Optional) CRUD operations
    routes.py      # API endpoints
    dependencies.py# Dependency functions

This structure is scalable and aligns with FastAPI best practices.