Core

A FastAPI backend focused on authentication and user management, built with async PostgreSQL, OAuth, and JWT session cookies.

Tech Stack

• Framework: FastAPI
• Database: PostgreSQL (async via asyncpg)
• ORM: SQLAlchemy 2.0 (async)
• Auth: Authlib (Google OAuth), JWT in httpOnly cookie
• Rate limiting: slowapi

Features

• Auth — Google OAuth, session cookie, logout
• Users — GET /me; admin CRUD for users

Prerequisites

• Python 3.14+
• PostgreSQL
• Docker (optional, for running PostgreSQL)

Quick Start

1. Clone and install

uv sync

2. Configure environment

Copy .env.example to .env and set required variables:

cp .env.example .env

Required: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, JWT_SECRET_KEY, SESSION_SECRET_KEY. Generate secrets with openssl rand -hex 32.

3. Start PostgreSQL

docker compose up -d

4. Run migrations

alembic upgrade head

5. Start the API

uv run uvicorn app.main:app --reload

API: http://localhost:8000
Docs: http://localhost:8000/docs

Commands

Command	Purpose
uv sync	Install dependencies (from pyproject.toml)
uv run uvicorn app.main:app --reload	Run API (dev)
alembic upgrade head	Apply migrations
alembic revision --autogenerate -m "message"	Create migration
pytest	Run tests
pytest -n auto	Run tests in parallel (pytest-xdist)
pytest --drop-test-db	Run tests and drop test DB after
ruff check .	Lint
ruff format .	Format

See docs/commands.md for Docker, pre-commit, and more.

API Overview

Interactive API docs: http://localhost:8000/docs

Testing

Tests use a separate DB ({postgres_db}_test). Migrations run automatically before tests.

pytest -v
pytest -n auto   # Parallel execution (pytest-xdist)

Unit, integration, E2E, security, and smoke tests. See docs/commands.md for Pytest commands.