fullstack-template CLAUDE.md

Project Guide

Stack

Layer	Tech
Frontend	Next.js 16, React 19, TypeScript 5, Tailwind CSS 4
Backend	Go 1.25, Gin, database/sql + pgx v5 stdlib
Database	PostgreSQL 16 via Docker Compose
Mobile	Android, Kotlin 2.2, Jetpack Compose BOM 2026.02, Material3
Dev tools	pnpm, Air (Go hot reload), Testcontainers, Gradle 9.4

Run commands

cd backend && make docker-run   # start Postgres
cd backend && make watch        # backend dev with hot reload (Air) → :8080
cd web && pnpm dev              # web dev → :3000

cd backend && make test         # all tests
cd backend && make itest        # integration tests only (requires Docker)
cd web && pnpm lint && pnpm build
cd web && pnpm test             # Vitest unit + component tests
cd web && pnpm test:watch       # watch mode during TDD

cd mobile && ./gradlew assembleDebug          # build Android APK
cd mobile && ./gradlew lint && ./gradlew test # mobile quality gate
cd mobile && ./gradlew connectedAndroidTest   # instrumented tests (emulator/device required)

Migration commands (run from backend/)

make migrate-create name=<slug>   # create a new timestamped SQL migration file
make migrate-status               # show applied vs. pending migrations
make migrate-up                   # apply all pending migrations
make migrate-up-one               # apply the next pending migration only
make migrate-down                 # roll back the last applied migration
make migrate-reset                # roll back everything to version 0
make migrate-version              # print current schema version

Feature development workflow — always follow this

1. Check docs first — delegate to docs agent: find relevant topic docs, verify they match the current code
2. Fix stale docs — if docs diverge from code, update docs before implementing
3. Migrate — if the feature needs new or changed tables: make migrate-create name=<slug>, write the SQL, make migrate-up
4. Write tests first (TDD) — write failing tests that describe the intended behaviour before writing any implementation code
5. Implement — delegate to backend or web agent, passing the relevant doc content as context; implementation is complete when all tests pass
6. Env vars — if any new env vars were added to loadConfig(), add them to backend/.env.example with a safe placeholder value and a comment explaining the format
7. Update docs — delegate to docs agent: update last_verified, add new topics if introduced
8. Quality gate — run /project:check before declaring done