Bluefox Stack

The foundation
of every Bluefox app

Settings, database, structured logging, health endpoints, and an app factory. One function call from zero to a production-ready FastAPI application.

Quick start
01

Create a project and install

$ uv init my-app && cd my-app
$ uv add bluefox-core
02

Write your app

main.py 
from bluefox_core import BluefoxSettings, create_bluefox_app

settings = BluefoxSettings()
app = create_bluefox_app(settings)
03

Start the server

$ uv run uvicorn main:app --reload
See it in action

Pass demo=True to get a working Todo CRUD app with full create, read, update, and delete operations.

main.py 
from bluefox_core import BluefoxSettings, create_bluefox_app

settings = BluefoxSettings()
app = create_bluefox_app(settings, demo=True)
$ uv run uvicorn main:app --reload
# Visit /docs to interact with the Todo API
# POST /demo/todos, GET /demo/todos, PATCH, DELETE
What you get

Settings

Typed configuration via pydantic-settings. Reads from environment variables and .env files. Subclass to add your own fields.

Async database

SQLAlchemy 2.x with asyncpg. Engine lifecycle, session dependency, URL normalization. Skip it entirely if you don't need a database.

Structured logging

structlog with JSON in production, colored console in development. Request IDs bound automatically via contextvars.

Health endpoints

/health for liveness, /readiness for dependency checks. Database and Redis verified automatically when configured.

Request ID middleware

Generates or preserves X-Request-ID headers. Binds to log context so every log line traces back to a request.

App factory

One function wires settings, database, Redis, logging, middleware, CORS, and health endpoints. Returns a standard FastAPI app.

Add your own routes

The factory returns a regular FastAPI instance. Add routers, dependencies, and middleware as you normally would.

main.py 
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from bluefox_core import BluefoxSettings, create_bluefox_app, get_session

settings = BluefoxSettings()
app = create_bluefox_app(settings)

router = APIRouter()

@router.get("/users")
async def list_users(db: AsyncSession = Depends(get_session)):
    result = await db.execute(select(User))
    return result.scalars().all()

app.include_router(router, prefix="/api")