Accelerate Innovation with Seamless AI-Driven APIs

Powered by industry-grade technologies

🚀 Why This Boilerplate?

Most FastAPI AI boilerplates lack production-readiness and multi-agent capabilities.

This project solves that with:

• 🧩 Modular architecture for multiple LangGraph workflows, agents, and pipelines
• 🔍 Integrated Langfuse tracing for debugging & observability
• 🐳 Production-ready deployment using Docker + Gunicorn
• 🧠 Optimized for AI workflow orchestration and scalable GenAI apps

📘 For in-depth documentation, visit the /docs folder.

• Overview
• What Makes It Stand Out
• Tech Stack
• Folder Structure
• Getting Started
• Makefile Commands
• Pre-commit Hooks
• Logging Middleware
• Configuration
• Testing & Linting
• Deployment
• Monitoring with Prometheus & Grafana
• Redis Caching
• Docker Compose Setup
• Documentation
• Contributing
• License

fastapi-genai-boilerplate is a scalable and production-ready starter template for building FastAPI applications with modern DevOps practices. It supports:

• Environment-aware configuration
• Observability (logging, tracing)
• Security (rate limiting)
• Maintainability (typed config, modular API)
• CI-ready with code quality hooks and Docker support

This template empowers you to build robust, scalable, and maintainable APIs with:

• 🌐 Environment-aware Config Seamlessly toggle between development and production settings for streamlined deployments.

• 🔎 Request Tracing & Logging Full observability using loguru, with structured logs, X-Request-ID headers, and performance metrics.

• 🛡️ Rate Limiting Middleware Protect endpoints from abuse using fastapi-limiter, based on identity/IP-based throttling.

• 🐳 Dockerized Deployment Container-first architecture with clean Dockerfile and production startup scripts using Gunicorn + Uvicorn.

• 🚀 Production Server Setup Efficient worker scaling with CPU-aware concurrency, custom Makefile for simplified operations.

• 🧩 Modular API Architecture Clean separation of concerns with well-defined folder structure, ready for features like chat, auth, etc.

fastapi_genai_boilerplate/
├── app/
│   ├── api/                     # API routes and handlers
│   ├── core/
│   │   ├── config.py            # App settings and environment config
│   │   └── middlewares/         # Logging, rate limit middleware
│   └── main.py                  # App bootstrap logic
├── tests/                       # Test cases
├── .env                         # Local environment variables
├── Dockerfile                   # Docker setup
├── Makefile                     # Developer shortcuts
├── pyproject.toml               # UV dependencies & configs
├── pre-commit-config.yaml       # Git hook configs
└── README.md                    # Project documentation

# Clone the repository
git clone https://github.com/kevaldekivadiya2415/fastapi-genai-boilerplate
cd fastapi-genai-boilerplate

# Optional: create and activate virtual environment (recommended)
uv venv
source .venv/bin/activate

# Install uv via pip
pip3 install uv

# Sync dependencies from pyproject.toml and uv.lock
uv sync

# Start an interactive Python shell with uv
uv run main.py

LOG_LEVEL=DEBUG
ENVIRONMENT=development
HOST=0.0.0.0
PORT=8002
WORKER_COUNT=4

Enforce standards before every commit. Tools include:

• ✅ ruff for linting
• ✅ black for formatting
• ✅ isort for import order
• ✅ mypy for type checks

Install hooks:

make pre-commit-install

Each request gets a unique ID:

• Injected via X-Request-ID header
• Auto-generated if missing
• Passed into log messages using loguru
• Added in response header for traceability

Ideal for debugging and log correlation across microservices.

All environment values are type-safe using pydantic.BaseSettings. Defaults can be overridden via .env file.

class AppConfig(BaseSettings):
    LOG_LEVEL:syr = LogLevel.TRACE
    RELEASE_VERSION: str = "0.0.1"
    ENVIRONMENT: str = AppEnvs.DEVELOPMENT
    HOST: str = "0.0.0.0"
    PORT: int = 8002
    WORKER_COUNT: Union[int, None] = None

    # Redis
    REDIS_HOST: str = ""
    REDIS_PORT: str = ""
    REDIS_PASSWORD: str = ""

Run checks with:

make lint
make typecheck
make format

Use pytest (not included yet) for writing unit/integration tests inside tests/.

make docker-build
make docker-run

Production uses:

• Gunicorn with UvicornWorker
• .env to control concurrency

This boilerplate includes built-in observability via the prometheus-fastapi-instrumentator library.

All FastAPI metrics (latency, requests, status codes, etc.) are exposed at:

http://HOST:PORT/metrics

A docker-compose.yml file is included to run the full observability stack:

• ✅ FastAPI App
• 📊 Prometheus (for metrics collection)
• 📈 Grafana (for dashboards)
• 🧠 Redis (for caching and Celery task queue)
• 🧰 RedisInsight (for Redis GUI)

Run everything with:

docker-compose up --build

By default, Grafana uses the following login credentials (configured via environment variables):

Username: admin
Password: supersecurepassword

You can modify these in the docker-compose.yml under the grafana service:

grafana:
  image: grafana/grafana
  ports:
    - "3000:3000"
  environment:
    - GF_SECURITY_ADMIN_USER=admin
    - GF_SECURITY_ADMIN_PASSWORD=supersecurepassword

Make sure the following file exists:

docker/
└── prometheus/
    └── prometheus.yml

Example:

# docker/prometheus/prometheus.yml

global:
  scrape_interval: 5s

scrape_configs:
  - job_name: 'fastapi'
    metrics_path: /metrics
    static_configs:
      - targets: ['fastapi:8002']

🔁 Prometheus scrapes /metrics from FastAPI every 5 seconds.

This boilerplate uses Redis with aiocache for request-level caching and task results.

• Uses Redis as the cache backend
• JSON serialization of values
• TTL (Time-To-Live) support
• Namespace isolation
• Authentication support (username/password)

Caching is set up in app/core/cache/cache.py:

from aiocache import Cache
from aiocache.serializers import JsonSerializer
from app.core.config import settings

cache = Cache(
    cache_class=Cache.REDIS,  # Redis backend
    endpoint=settings.REDIS_HOST,
    port=settings.REDIS_PORT,
    username=settings.REDIS_USER,
    password=settings.REDIS_PASSWORD,
    ttl=300,  # Cache timeout in 300 seconds (5 mins)
    namespace="fastapi_cache",
    serializer=JsonSerializer(),
    db=1,
)

To prevent cache pollution by brute-force query changes:

• Normalize/cache keys using request fingerprinting
• Apply rate-limiting middleware (already included via fastapi-limiter)
• Use checksum-based cache keys (e.g. hashlib.sha256(json.dumps(payload)))

Redis (with RedisInsight UI) is exposed via Docker:

docker-compose down

This boilerplate is compatible with Langfuse for observability, tracing, and debugging of LLM-based applications.

• Trace all API interactions and GenAI requests
• View detailed logs, timings, metadata, and user sessions
• Works with OpenAI, Anthropic, HuggingFace, and custom model providers

1. Start Langfuse via Docker Compose

   docker compose -f docker-compose-langfuse.yaml up -d

2. Access the Langfuse UI

   Open your browser at http://localhost:3000

3. Sign Up & Create Project

   • Register your admin user
   • Create a new project
   • Copy the Public and Secret API keys

4. Add Langfuse Credentials to .env

   LANGFUSE_HOST=http://localhost:3000
   LANGFUSE_PUBLIC_KEY=your-public-key-here
   LANGFUSE_SECRET_KEY=your-secret-key-here

• 🧠 Logging Middleware
• 🛠️ Makefile Commands
• 🌍 Environment Variables
• 🐳 Docker Compose Setup
• 🛡️ Rate Limiting with FastAPI-Limiter
• 🧭 Trace Decorator
• 📊 Langfuse Integration Guide

You're welcome to contribute! Please:

1. Fork this repo
2. Create a new branch
3. Ensure pre-commit and linters pass
4. Open a PR with a clear description

This project is licensed under the MIT License — see the LICENSE file for details.