FastAPI-New

A modular project generator for FastAPI applications.

FastAPI-New provides a command-line tool to generate well-structured FastAPI projects with modular architecture, automatic route registration, and clean separation of concerns.

Overview

FastAPI-New is a project scaffolding tool that generates production-ready FastAPI projects with:

Modular Architecture - Organize your application into independent, reusable modules
Automatic Registration - Modules are automatically discovered and loaded
MSSR Pattern - Structured layers for Models, Schemas, Services, and Repositories
CLI Tools - Generate modules and manage database configurations from the command line
Database Flexibility - Works with any database or ORM of your choice
Minimal Boilerplate - Clean starter templates with helpful examples

Installation

FastAPI-New requires uv for project management.

Install uv

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Create a Project

uvx fastapi-new myproject

This creates a new FastAPI project in the myproject directory.

Quick Example

# Create a new project
uvx fastapi-new myapi
cd myapi

# Generate application modules
fastapi-new createapp users
fastapi-new createapp products

# Start the development server
uv run fastapi dev

Visit http://localhost:8000/docs to see your API documentation.

Project Structure

A newly created project has the following structure:

myproject/
├── app/
│   ├── main.py          # Application entry point
│   ├── core/            # Core application components
│   │   ├── config.py    # Configuration management
│   │   ├── registry.py  # Module registry
│   │   ├── database.py  # Database configuration
│   │   └── security.py  # Security utilities
│   ├── apps/            # Application modules
│   └── db/              # Database layer
│       ├── base.py      # Base model definitions
│       └── session.py   # Session management
├── .env                 # Environment variables
└── pyproject.toml       # Project dependencies

Core Components

`main.py`

The application entry point that creates the FastAPI instance and registers all modules:

from fastapi import FastAPI
from app.core.config import settings
from app.core.registry import INSTALLED_APPS

app = FastAPI(
    title=settings.PROJECT_NAME,
    description=settings.PROJECT_DESCRIPTION,
    version=settings.VERSION,
)

# Modules are automatically loaded from INSTALLED_APPS

`core/registry.py`

Manages module registration:

INSTALLED_APPS: list[str] = [
    "users",
    "products",
]

`core/config.py`

Application settings using Pydantic:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    PROJECT_NAME: str = "MyAPI"
    DEBUG: bool = True
    
    class Config:
        env_file = ".env"

CLI Commands

Create a New Project

# Create in a new directory
uvx fastapi-new myproject

# Initialize in current directory
uvx fastapi-new

Options:

--python, -p - Specify Python version (e.g., --python 3.12)

Generate Application Modules

fastapi-new createapp <module_name>

Creates a new module with the MSSR structure:

app/apps/<module_name>/
├── __init__.py
├── models.py        # Data models
├── schemas.py       # Pydantic schemas
├── services.py      # Business logic
├── repositories.py  # Data access layer
├── routes.py        # API routes
└── dependencies.py  # FastAPI dependencies

The module is automatically added to INSTALLED_APPS in core/registry.py.

Example:

fastapi-new createapp users

Generates:

# app/apps/users/routes.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def list_users():
    return {"users": []}

Add Database Support

fastapi-new add-db <engine>

Configures database support for the specified engine.

Supported engines:

postgres - PostgreSQL
mysql - MySQL
sqlite - SQLite
mongodb - MongoDB

Options:

--install, -i - Automatically install required dependencies

Example:

fastapi-new add-db postgres --install

List Installed Modules

fastapi-new list

Displays all registered application modules.

Options:

--verbose, -v - Show detailed module information

Diagnose Project

fastapi-new doctor

Checks project structure and configuration:

Required directories exist
Core files are present
Module files are valid
Environment is configured

Architecture

MSSR Pattern

FastAPI-New follows the Model-Schema-Service-Repository pattern for clean architecture:

Client Request
    ↓
API Route (routes.py)
    ↓
Business Logic (services.py)
    ↓
Data Access (repositories.py)
    ↓
Data Model (models.py)
    ↓
Database

Benefits:

Separation of Concerns - Each layer has a single responsibility
Testability - Layers can be tested independently
Maintainability - Changes are localized to specific layers
Flexibility - Database or business logic can be swapped easily

Layer Responsibilities

Layer	File	Purpose
Model	`models.py`	Database schema and ORM models
Schema	`schemas.py`	Request/response validation with Pydantic
Service	`services.py`	Business logic and operations
Repository	`repositories.py`	Database queries and data access
Route	`routes.py`	HTTP endpoints and request handling

Example Implementation

Models

# app/apps/users/models.py
from sqlalchemy import Column, Integer, String
from app.db.base import Base

class User(Base):
    __tablename__ = "users"
    
    id = Column(Integer, primary_key=True, index=True)
    email = Column(String, unique=True, index=True)
    name = Column(String)

Schemas

# app/apps/users/schemas.py
from pydantic import BaseModel, EmailStr

class UserCreate(BaseModel):
    email: EmailStr
    name: str

class UserResponse(BaseModel):
    id: int
    email: str
    name: str
    
    class Config:
        from_attributes = True

Repositories

# app/apps/users/repositories.py
from sqlalchemy.orm import Session
from app.apps.users.models import User

class UserRepository:
    def __init__(self, db: Session):
        self.db = db
    
    def get_by_email(self, email: str):
        return self.db.query(User).filter(User.email == email).first()
    
    def create(self, user_data: dict):
        user = User(**user_data)
        self.db.add(user)
        self.db.commit()
        self.db.refresh(user)
        return user

Services

# app/apps/users/services.py
from app.apps.users.repositories import UserRepository
from app.apps.users.schemas import UserCreate

class UserService:
    def __init__(self, repository: UserRepository):
        self.repository = repository
    
    def create_user(self, user_data: UserCreate):
        # Business logic here
        if self.repository.get_by_email(user_data.email):
            raise ValueError("Email already registered")
        return self.repository.create(user_data.dict())

Routes

# app/apps/users/routes.py
from fastapi import APIRouter, Depends
from app.apps.users.schemas import UserCreate, UserResponse
from app.apps.users.dependencies import get_user_service

router = APIRouter()

@router.post("/", response_model=UserResponse)
async def create_user(
    user: UserCreate,
    service = Depends(get_user_service)
):
    return service.create_user(user)

Module Registration

Modules are automatically registered when created with fastapi-new createapp.

Manual Registration

To manually register a module, add it to INSTALLED_APPS in app/core/registry.py:

INSTALLED_APPS: list[str] = [
    "users",
    "products",
    "orders",  # Add your module here
]

How It Works

The main.py file automatically loads routes from registered modules:

from importlib import import_module
from app.core.registry import INSTALLED_APPS

for app_name in INSTALLED_APPS:
    try:
        routes = import_module(f"app.apps.{app_name}.routes")
        if hasattr(routes, "router"):
            app.include_router(
                routes.router,
                prefix=f"/api/v1/{app_name}",
                tags=[app_name.capitalize()],
            )
    except ImportError as e:
        print(f"Could not load {app_name}: {e}")

Configuration

Environment Variables

Configure your application through environment variables in .env:

# Application
PROJECT_NAME=MyAPI
PROJECT_DESCRIPTION=My FastAPI Application
VERSION=0.1.0
DEBUG=true

# Database (add when needed)
# DATABASE_URL=postgresql://user:password@localhost/dbname

# Security (add when needed)
# SECRET_KEY=your-secret-key-here

Settings Management

Settings are managed through Pydantic Settings:

# app/core/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    PROJECT_NAME: str = "MyAPI"
    PROJECT_DESCRIPTION: str = "API Description"
    VERSION: str = "0.1.0"
    DEBUG: bool = True
    
    class Config:
        env_file = ".env"
        case_sensitive = True

settings = Settings()

Access settings anywhere in your application:

from app.core.config import settings

print(settings.PROJECT_NAME)

Database Configuration

FastAPI-New is database-agnostic. Use any database or ORM:

SQLAlchemy Example

# app/core/database.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./app.db"

engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(bind=engine)

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

Tortoise ORM Example

# app/core/database.py
from tortoise import Tortoise

async def init_db():
    await Tortoise.init(
        db_url="sqlite://db.sqlite3",
        modules={"models": ["app.apps.users.models"]}
    )

MongoDB Example

# app/core/database.py
from motor.motor_asyncio import AsyncIOMotorClient

client = AsyncIOMotorClient("mongodb://localhost:27017")
db = client.mydatabase

Development Workflow

1. Create Project

uvx fastapi-new myapi
cd myapi

2. Generate Modules

fastapi-new createapp users
fastapi-new createapp products
fastapi-new createapp orders

3. Implement Features

Edit the generated files to implement your business logic.

4. Check Project Health

fastapi-new doctor

5. Run Development Server

uv run fastapi dev

The server will reload automatically when you make changes.

6. View API Documentation

Visit http://localhost:8000/docs for interactive API documentation.

Best Practices

Module Organization

Keep modules focused on a single domain concept
Use descriptive module names (e.g., users, orders, notifications)
Avoid circular dependencies between modules

Code Structure

Models - Define database schema only
Schemas - Validate and serialize data
Repositories - Isolate database queries
Services - Contain business logic
Routes - Handle HTTP concerns only

Configuration

Use environment variables for configuration
Never commit .env files to version control
Provide .env.example as a template

Testing

# tests/test_users.py
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_create_user():
    response = client.post("/api/v1/users/", json={
        "email": "test@example.com",
        "name": "Test User"
    })
    assert response.status_code == 200

Production Deployment

Using Docker

FROM python:3.12-slim

WORKDIR /app

COPY pyproject.toml .
RUN pip install uv && uv pip install -r pyproject.toml

COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Using Uvicorn

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Requirements

Python 3.10 or higher
uv for dependency management

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation: FastAPI Documentation
Source Code: github.com/fastapi/fastapi-new

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
.github		.github
scripts		scripts
src/fastapi_new		src/fastapi_new
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
release-notes.md		release-notes.md
requirements-tests.txt		requirements-tests.txt
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

FastAPI-New

Overview

Installation

Install uv

Create a Project

Quick Example

Project Structure

Core Components

main.py

core/registry.py

core/config.py

CLI Commands

Create a New Project

Generate Application Modules

Add Database Support

List Installed Modules

Diagnose Project

Architecture

MSSR Pattern

Layer Responsibilities

Example Implementation

Models

Schemas

Repositories

Services

Routes

Module Registration

Manual Registration

How It Works

Configuration

Environment Variables

Settings Management

Database Configuration

SQLAlchemy Example

Tortoise ORM Example

MongoDB Example

Development Workflow

1. Create Project

2. Generate Modules

3. Implement Features

4. Check Project Health

5. Run Development Server

6. View API Documentation

Best Practices

Module Organization

Code Structure

Configuration

Testing

Production Deployment

Using Docker

Using Uvicorn

Requirements

License

Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`main.py`

`core/registry.py`

`core/config.py`

Packages