# [App Name] · Go + HTMX

A Go web app. Server-rendered HTML, HTMX for partial updates, SQLite for state. Single binary, single deploy.

## Source of truth
GitHub. CI builds a single static binary (CGO_ENABLED=0 GOOS=linux). The deployed binary is canonical. SQLite file is included in the volume; nightly backup to S3.

## Tech stack
Go 1.23+ + `chi` for routing + `templ` for typed templates + HTMX for interactivity + Alpine.js (only where HTMX falls short). SQLite via `mattn/go-sqlite3` (or `modernc.org/sqlite` for pure Go). Tailwind v4 via the standalone CLI (no Node). Litestream for SQLite replication.

## Deploy
- Build: `go build -o bin/app ./cmd/server`
- Run: `./bin/app` (port 8080)
- Production: systemd service + Caddy in front for TLS. OR Fly.io with a single VM and persistent volume.
- Backups: Litestream replicates SQLite to S3 continuously.

## File map
- `cmd/server/main.go` server entrypoint, HTTP setup
- `internal/handlers/` chi handlers, one per resource
- `internal/views/` `*.templ` templates (compiled to Go via `templ generate`)
- `internal/db/` sqlc queries (typed Go from SQL) OR raw `database/sql`
- `internal/middleware/` auth, logging, request ID
- `migrations/` numbered SQL migrations applied via `goose`
- `static/` JS (htmx, alpine), CSS (compiled Tailwind), images
- `Caddyfile` reverse proxy config (production)

## .env keys
- `DB_PATH` default `./data/app.db`
- `PORT` default 8080
- `SESSION_SECRET` random 32-byte hex
- `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET` (Litestream)
- `ENV` `dev` | `prod`

## Hard rules
- Templates are `.templ` files compiled with `templ generate`. Never edit generated `.templ.go` files.
- SQLite is single-writer. Don't run multiple processes against the same DB file. Litestream is for backup, not for distribution.
- HTMX swaps are SCOPED. Every endpoint returns a fragment that exactly matches the swap target. Don't return full pages and then style-hide chunks.
- Migrations via `goose up`. Migration files are immutable once shipped to prod.
- Session cookie is httpOnly, secure, sameSite=lax. Random 32-byte token, NOT a JWT.
- Single binary deploy. No `node_modules`. No `vendor/` committed unless you have a hard reason.

## Recent significant changes
- 2026-05-11: Scaffolded. Locked: templ over html/template (type safety), HTMX over full SPA (boring is good), Litestream over manual backups (works while you sleep).

## Next session: start here
1. `templ generate` to compile templates. Set up a `make` target so this runs on every save.
2. `goose -dir migrations create init sql` and write your first schema.
3. Implement first resource: handler + template + SQL query. Click through it.
4. Set up Litestream pointing at S3. Confirm a backup appears within 10 minutes.
5. Deploy to a single Fly VM with a persistent volume. Confirm restart doesn't lose data.