fastapi-struct 0.2.0

CLI tool to generate standard, enterprise-ready, layered folder structures for FastAPI applications in seconds.

---

FastAPI Documentation: https://fastapi.tiangolo.com
PyPI Package: https://pypi.org/project/fastapi-struct/

---

⚡ What is fastapi-struct?

fastapi-struct generates a clean, scalable, layered enterprise architecture for FastAPI applications. It organizes code into distinct responsibilities: API Routes, Services, Repositories, Schemas, Models, and Core Settings, avoiding messy spaghetti code and giving you a production-ready codebase instantly.

fastapi-struct my_fastapi_project

Or scaffold directly inside your current directory:

fastapi-struct .

---

🎯 Architecture Diagram & Data Flow

 ┌────────────────┐
 │ Client Request │
 └───────┬────────┘
         │
         ▼
 ┌────────────────────────┐
 │   API Routes (v1)      │  Handles HTTP requests & route decorators
 └───────┬────────────────┘
         │
         ▼
 ┌────────────────────────┐
 │     Services Layer     │  Encapsulates core business logic
 └───────┬────────────────┘
         │
         ▼
 ┌────────────────────────┐
 │   Repositories Layer   │  Database interactions & CRUD operations
 └───────┬────────────────┘
         │
         ▼
 ┌────────────────────────┐
 │  Database / ORM Models │  SQLAlchemy / SQLModel / Database tables
 └────────────────────────┘

---

📂 Generated Project Structure

my_fastapi_project/
│
├── app/                        # Main application package
│   ├── __init__.py
│   ├── main.py                 # FastAPI app initialization & entry point
│   │
│   ├── api/                    # API endpoints & route definitions
│   │   ├── __init__.py
│   │   └── v1/                 # API Versioning
│   │       ├── __init__.py
│   │       ├── api.py          # Central router aggregating endpoints
│   │       └── routes/         # Route handlers
│   │           ├── __init__.py
│   │           ├── items.py    # Endpoint logic for items
│   │           └── users.py    # Endpoint logic for users
│   │
│   ├── core/                   # Application configurations & settings
│   │   ├── __init__.py
│   │   ├── config.py           # Environment variables (Pydantic BaseSettings)
│   │   ├── database.py         # DB connection & session creation
│   │   └── security.py         # Password hashing & security helpers
│   │
│   ├── models/                 # Database ORM models (SQLAlchemy / SQLModel)
│   │   ├── __init__.py
│   │   ├── item.py
│   │   └── user.py
│   │
│   ├── schemas/                # Pydantic models for request validation & responses
│   │   ├── __init__.py
│   │   ├── item.py
│   │   └── user.py
│   │
│   ├── services/               # Core business logic layer
│   │   ├── __init__.py
│   │   ├── item_service.py
│   │   └── user_service.py
│   │
│   ├── repositories/           # Database interactions & CRUD queries layer
│   │   ├── __init__.py
│   │   ├── item_repository.py
│   │   └── user_repository.py
│   │
│   └── utils/                  # Utility functions & helpers
│       ├── __init__.py
│       └── email.py
│
├── tests/                      # Unit and integration tests
│   ├── __init__.py
│   ├── conftest.py             # Pytest fixtures
│   ├── test_items.py           # Item API test cases
│   └── test_users.py           # User API test cases
│
├── .gitignore
├── .env                        # Environment variables (local)
├── .env.example                # Sample environment variables template
├── README.md                   # Project documentation
├── requirements.txt            # Project dependencies
└── pyproject.toml              # Build & test configurations

---

📦 Installation & Quick Start

Option 1: Instant with uvx (No installation needed)

uvx fastapi-struct my_fastapi_project

Or inside your existing folder:

uvx fastapi-struct .

---

Option 2: Standard install with pip

pip install fastapi-struct

Run:

fastapi-struct my_fastapi_project

(Or inside the current folder: fastapi-struct .)

---

🚀 Running Your Generated Project

1. Step into the project folder

cd my_fastapi_project

(Skip if generated with fastapi-struct .)

2. Create and activate a virtual environment

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Windows CMD:

python -m venv .venv
call .venv\Scripts\activate.bat

macOS & Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

(Or pip install -e ".[dev]")

4. Start the development server

python -m uvicorn app.main:app --reload

---

🔍 Interactive API Documentation

Once running, visit:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

---

🧪 Running Automated Tests

Run the included Pytest suite:

python -m pytest

Output:

tests\test_items.py ..                                                   [ 50%]
tests\test_users.py ..                                                   [100%]
============================== 4 passed in 0.25s ==============================

---

📜 License

This project is licensed under the terms of the MIT License.