FastAPI Boilerplate

A clean, well-structured FastAPI boilerplate project with organized architecture and best practices.

🚀 Features

• FastAPI - Modern, fast web framework for building APIs
• Structured Architecture - Clean separation of concerns with organized directories
• CORS Support - Cross-Origin Resource Sharing enabled
• Logging - Comprehensive logging with file and console output
• Environment Configuration - Environment variables support with python-dotenv
• Production Ready - Gunicorn configuration for production deployment
• Docker Support - Containerized application setup

📁 Project Structure

mini_fastapi_boilerplate/
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
├── Makefile              # Development commands
├── Dockerfile            # Docker configuration
├── app.log               # Application logs
├── assets/               # Non-Python files (.json, .txt, etc.)
├── src/
│   ├── apis/             # API route definitions
│   │   └── v1/           # API version 1
│   │       ├── admin/    # Admin-specific endpoints
│   │       └── user/     # User-specific endpoints
│   ├── core/             # Core project files (config.py, etc.)
│   ├── models/           # Database models (if applicable)
│   ├── schemas/          # Type definitions (BaseModel, enums)
│   ├── services/         # External service integrations
│   └── utils/            # Project-specific utilities

🛠️ Directory Descriptions

assets/

Contains non-Python files such as:

• JSON configuration files
• Text files
• Static assets
• Data files

core/

Core project files including:

• Configuration management (config.py)
• Database connections
• Application settings
• Core business logic

models/

Database models and ORM definitions:

• SQLAlchemy models
• Database schemas
• Entity definitions

schemas/

Type definitions and data validation:

• Pydantic BaseModel classes
• Enum definitions
• Request/response schemas
• Data validation models

services/

External service integrations:

• Third-party API clients
• Web service requests
• External system integrations
• Service layer implementations

utils/

Project-specific utilities:

• Helper functions
• Common utilities
• Project-specific tools
• Internal management functions

🚀 Quick Start

Prerequisites

• Python 3.8+
• pip

Installation

1. Clone the repository

   git clone <repository-url>
   cd mini_fastapi_boilerplate

2. Install dependencies

   make install
   # or
   pip install -r requirements.txt

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Run the application

   # Development mode
   make run
   
   # Production mode
   make run_prod

Manual Commands

# Development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Production server
gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000

📚 API Documentation

Once the server is running, you can access:

• Interactive API docs (Swagger UI): http://localhost:8000/docs
• Alternative API docs (ReDoc): http://localhost:8000/redoc
• OpenAPI schema: http://localhost:8000/openapi.json

🐳 Docker Support

Build and run with Docker

# Build the image
docker build -t fastapi-boilerplate .

# Run the container
docker run -p 8000:8000 fastapi-boilerplate

🔧 Configuration

The application uses environment variables for configuration. Create a .env file in the root directory:

# Example environment variables
DEBUG=True
LOG_LEVEL=INFO
DATABASE_URL=sqlite:///./app.db

📝 API Response Format

All API endpoints follow a consistent response format:

{
  "status": true,
  "message": "Success message or null",
  "data": "Response data or null"
}

🏗️ Development

Adding New Endpoints

1. Create your endpoint in the appropriate directory under src/apis/v1/
2. Import and include the router in the main router
3. Follow the existing pattern for error handling and response formatting

Example Endpoint

from src.schemas.api_response import ApiResponse
from fastapi import APIRouter

router = APIRouter(prefix="/example", tags=["Example"])

@router.get("", response_model=ApiResponse)
async def get_example():
    status = False
    message = ""
    data = None
    try:
        # Your logic here
        data = {"example": "data"}
        status = True
    except Exception as e:
        message = str(e)
    return ApiResponse(status=status, message=message, data=data)

📦 Dependencies

• FastAPI - Web framework
• Uvicorn - ASGI server
• python-dotenv - Environment variable management
• cryptography - Cryptographic utilities
• Gunicorn - Production WSGI server

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Support

If you encounter any issues or have questions, please open an issue in the repository.

---

Happy coding! 🎉