devtools
Hoatzin PoC: FastAPI, Next.js, and MkDocs Setup
A straightforward guide to setting up Hoatzin's backend, frontend, and documentation using FastAPI, Next.js, and MkDocs.
Shipped January 2026
This archive contains three top-level projects:
hoatzin-backend– FastAPI + Postgres backend (includes infra and Caddy).hoatzin-frontend– Next.js + TypeScript + Tailwind frontend.hoatzin-docs– MkDocs Material documentation site.
You can push each of these directories to its own GitHub repo if you want:
hoatzin-backend->hoatzin-backendrepohoatzin-frontend->hoatzin-frontendrepohoatzin-docs->hoatzin-docsrepo
High-level startup
1. Backend (API + DB + Caddy)
From hoatzin-backend:
-
Copy
.env.exampleto.envand set secrets. -
Start Postgres + API + Caddy via Docker:
docker compose up --build -
Run migrations (inside a shell with Python deps installed or inside the api container):
alembic upgrade head -
API should be reachable at
http://localhost:8000(or via Caddy with your domain later).
2. Frontend (Next.js)
From hoatzin-frontend:
npm install
npm run dev
Open http://localhost:3000 to view the UI.
3. Docs
From hoatzin-docs:
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve
Open http://127.0.0.1:8000 for the docs.
License
All rights reserved. Personal project, not for redistribution.
Need more context?
Want help adapting this playbook?
Send me the constraints and I'll annotate the relevant docs, share risks I see, and outline the first sprint so the work keeps moving.