IAM Starter

A fork-and-go starter template for new web apps. You get a modern stack with auth, RBAC, orgs, MFA, and passkeys already wired end-to-end — clone, rename, flip the feature flags you want, ship.

Not a hosted auth service. The frontend is your app's frontend; the backend is your app's API. Auth lives in-process. Delete what you don't need.

Stack

• Backend: FastAPI (Python 3.13) + SQLAlchemy 2.0 async + Alembic
• Frontend: Next.js 15 App Router + Tailwind v4 + shadcn/ui + TanStack Query
• Data: Postgres 16, Redis 7, MinIO (S3-compatible)
• Dev: Docker Compose, Mailhog for local email, Playwright for E2E

Quickstart

# 1. Clone and rename
git clone <this-repo> myapp
cd myapp
.\scripts\rename-project.ps1 myapp

# 2. Configure
Copy-Item .env.example .env
# edit .env — at minimum set AUTH_SECRET_KEY

# 3. Bring it up
docker compose -f docker/compose.yml up -d

Open:

• App: http://localhost:3000
• API docs: http://localhost:8000/docs
• Mailhog (dev email inbox): http://localhost:8025
• MinIO console: http://localhost:9001

Local development without Docker

# Backend
pyenv local 3.13.2
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
alembic upgrade head
uvicorn app.main:app --reload

# Frontend (separate shell)
cd frontend
pnpm install
pnpm dev

What's included

Feature	Flag	Phase
Email + password	AUTH_FEATURE_EMAIL_PASSWORD_ENABLED	1
RBAC + orgs	AUTH_FEATURE_ORGS_ENABLED	1
Sessions UI	(always)	1
Audit log writes	AUTH_FEATURE_AUDIT_LOG_ENABLED	1
Google OAuth	AUTH_FEATURE_GOOGLE_OAUTH_ENABLED	2
GitHub OAuth	AUTH_FEATURE_GITHUB_OAUTH_ENABLED	2
Magic link / OTP	AUTH_FEATURE_PASSWORDLESS_ENABLED	2
Rate limiting	(always)	2
TOTP MFA	AUTH_FEATURE_TOTP_MFA_ENABLED	3
WebAuthn passkeys	AUTH_FEATURE_PASSKEYS_ENABLED	3
Audit log UI	(always)	3
Avatar upload (S3)	(always)	4

A disabled feature returns 404 — clean signal to clients that the surface doesn't exist. See docs/feature-flags.md for which files/folders/migrations are safe to delete if you want a feature gone, not just disabled.

Docs

• docs/architecture.md — high-level design
• docs/starter-usage.md — fork → rename → ship walkthrough
• docs/feature-flags.md — what each flag toggles
• PRD.md — product requirements

Layout

iam-starter/
├── backend/                FastAPI service + Alembic
├── frontend/               Next.js app (your app's frontend)
├── docker/                 compose files + service init scripts
├── docs/                   architecture + usage guides
├── scripts/                rename-project, dev, seed
└── .github/workflows/      CI