Deploy Lions to lions.codes

[planeyang]

Goal

Deploy Lions (frontend + backend) to lions.codes for public access.

Architecture Reference

Per docs/architecture/05-system-architecture.md:

Lions is two independently deployable components connected by a JSON interface contract.

• Component 1: Annotation Pipeline — Python / FastAPI (REST API + CLI for batch processing)
• Component 2: Web Application — Next.js + React + TypeScript
• Interface: JSON annotation schema (per-file annotations, reading guides, repo analysis)
• Storage: SQLite (WAL mode) for annotations + repo analysis
• Future: Modal for sandbox execution (not deployed yet)

Tech stack from the doc:

Component	Technology
Annotation Pipeline	Python, FastAPI, tree-sitter, Anthropic SDK
Web Application	Next.js 16, React 19, TypeScript, Tailwind 4, Shiki
LLM	Claude (Sonnet for annotation, Haiku for summarization)
Storage	SQLite + JSON

Current State

• Frontend and backend work locally (localhost:3000 + localhost:8000)
• SQLite DB with annotated repos exists locally
• Backend deployed to Fly.io (lions-api.fly.dev)
• Frontend deployed to Vercel (lions-codes.vercel.app)
• Domain lions.codes purchased from Namecheap, nameservers pointed to Vercel
• 3 repos/gists annotated: mini-sglang (102 files), micrograd (5 files), microGPT gist (1 file)
• Gist pipeline supports full stages 1-5 with display names

Deployment Plan

Recommended: Vercel (frontend) + Fly.io (backend)

Why this split:

• Aligns with the "two independently deployable components" architecture
• Vercel: zero-config Next.js, edge CDN, automatic SSL, custom domain
• Fly.io: persistent SQLite volume, good for long-running Python processes, auto-deploy

Tasks

Infrastructure

• Create backend/Dockerfile (Python 3.13 + uv + FastAPI)
• Create frontend/Dockerfile (Node + pnpm + Next.js standalone build)
• Create docker-compose.yml for local production testing
• Create .env.example documenting required env vars
• Deployment docs: docs/dev/deployment.md
• Claude Code skills: /annotate-repo, /update-database

Backend Deployment (Fly.io)

• Create fly.toml for backend
• Persistent SQLite volume mount (/data/lions.db)
• Update DB_PATH to use env var or /data/lions.db in production
• Set ANTHROPIC_API_KEY and GITHUB_TOKEN as Fly secrets
• Add health check endpoint (GET /api/health)
• Restrict CORS from * to https://lions.codes

Frontend Deployment (Vercel)

• Connect Vercel to GitHub repo
• Set BACKEND_URL env var pointing to Fly backend
• Custom domain: lions.codes (nameservers configured via Namecheap)
• Verify SSR works (Next.js server components fetch from backend)
• Framework Preset set to "Next.js" (not "Other")
• Root directory set to frontend

DNS & TLS

• Point lions.codes → Vercel (frontend) via nameservers
• Point api.lions.codes → Fly.io (backend) — currently using lions-api.fly.dev directly
• SSL/TLS automatic via Vercel + Fly

CI/CD

• GitHub Actions: build + deploy backend to Fly on push to master
• Vercel auto-deploys frontend from master (built-in)

Data

• Copy local lions.db to Fly volume (initial seed)
• Re-run pipeline for additional repos (micrograd, microGPT gist)
• Gist pipeline with summarize + reading guide (stages 4-5)
• Display names for gists (e.g., "microGPT" instead of hex ID)

Post-deploy Smoke Test

• https://lions-api.fly.dev/api/repos — Returns 3 repos with summaries and guides
• https://lions.codes/ — Library page shows repo cards
• https://lions.codes/repo/... — Repo Landing with chapters
• https://lions.codes/guide/... — Guide View with prose + code snippets
• https://lions.codes/view?... — Code View with file tree + sidebar tabs
• Theme toggle works on all pages
• Unannotated files render via /api/source fallback
• Disable Vercel deployment protection for public access

Related PRs

• Add Fly.io deployment config and health check endpoint #14 — Deployment config, skills, gitignore (merged)
• Add Claude Code skills for pipeline and deployment #15 — Gist full pipeline, display names, frontend support (open)