Metadata-Version: 2.4
Name: fastapi-struct
Version: 0.2.0
Summary: CLI tool to generate standard, layered enterprise folder structures for FastAPI applications.
License-Expression: MIT
Keywords: fastapi,project-structure,boilerplate,scaffold,cli,template,folder-structure,architecture,repository-pattern,rest-api
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Code Generators
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://pypi.org/project/fastapi-struct/"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" width="320" alt="fastapi-struct"></a>
</p>
<p align="center">
    <em>CLI tool to generate standard, enterprise-ready, layered folder structures for FastAPI applications in seconds.</em>
</p>
<p align="center">
<a href="https://pypi.org/project/fastapi-struct" target="_blank">
    <img src="https://img.shields.io/pypi/v/fastapi-struct.svg?color=%2334D058" alt="Package version">
</a>
<a href="https://pypi.org/project/fastapi-struct" target="_blank">
    <img src="https://img.shields.io/pypi/pyversions/fastapi-struct.svg?color=%2334D058" alt="Supported Python versions">
</a>
<a href="https://github.com/fastapi/fastapi" target="_blank">
    <img src="https://img.shields.io/badge/FastAPI-0.115+-009688.svg?logo=fastapi&logoColor=white" alt="FastAPI">
</a>
<a href="https://github.com/pydantic/pydantic" target="_blank">
    <img src="https://img.shields.io/badge/Pydantic-v2-E92063.svg?logo=pydantic&logoColor=white" alt="Pydantic v2">
</a>
<a href="https://opensource.org/licenses/MIT" target="_blank">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT">
</a>
</p>

---

**FastAPI Documentation:** [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com)  
**PyPI Package:** [https://pypi.org/project/fastapi-struct/](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.

```bash
fastapi-struct my_fastapi_project
```

Or scaffold directly inside your current directory:

```bash
fastapi-struct .
```

---

## 🎯 Architecture Diagram & Data Flow

```text
 ┌────────────────┐
 │ 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

```text
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)*

```bash
uvx fastapi-struct my_fastapi_project
```

Or inside your existing folder:

```bash
uvx fastapi-struct .
```

---

### Option 2: Standard install with `pip`

```bash
pip install fastapi-struct
```

Run:

```bash
fastapi-struct my_fastapi_project
```
*(Or inside the current folder: `fastapi-struct .`)*

---

## 🚀 Running Your Generated Project

### 1. Step into the project folder
```bash
cd my_fastapi_project
```
*(Skip if generated with `fastapi-struct .`)*

### 2. Create and activate a virtual environment

**Windows PowerShell:**
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

**Windows CMD:**
```cmd
python -m venv .venv
call .venv\Scripts\activate.bat
```

**macOS & Linux:**
```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Install dependencies
```bash
pip install -r requirements.txt
```
*(Or `pip install -e ".[dev]"`)*

### 4. Start the development server
```bash
python -m uvicorn app.main:app --reload
```

---

## 🔍 Interactive API Documentation

Once running, visit:

- **Swagger UI**: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
- **ReDoc**: [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)

---

## 🧪 Running Automated Tests

Run the included Pytest suite:

```bash
python -m pytest
```

Output:
```text
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](https://opensource.org/licenses/MIT).
