- Five-minute clone-to-page onboarding doc covering prereqs, bootstrap,
two-terminal dev workflow, common commands, and troubleshooting.
- Documents docker compose fallback for contributors not on podman (D-11).
- Documents two-terminal workflow: just dev + just styles-watch (D-14).
- Every `just <recipe>` referenced is a real recipe in backend/justfile.
- Uses 'bootstrap-downloaded' wording (not 'vendored') for tailwindcss
and htmx.min.js per Codex review concern #4.
- Clarifies HTMX runtime no-CDN policy; the unpkg URL in justfile is the
single authoritative version pin (D-10 / Codex concern #5).
- Top 3 pitfalls from RESEARCH surfaced in Troubleshooting.
- 195 lines, no emoji, no marketing voice.
- Opens pgxpool from DATABASE_URL, logs 'worker ready', blocks on
SIGINT/SIGTERM, closes pool, exits 0
- Reuses web.NewSlogHandler — pure helper, no HTTP coupling
- No job queue libraries (river/asynq/pg_notify) — Phase 6 replaces this
file in full
- 48 lines (under 80-line budget signals 'we did not implement Phase 6
by accident')
- Reads DATABASE_URL (required), PORT (default 8080), ENV (default
development) from os.Getenv only — no third-party env loader (D-15:
.env exported by just dev, prod injects real env)
- slog.SetDefault wired before fatal-on-missing-DSN so even startup errors
emit structured output; sanitization per T-01-12 (never log DSN)
- pgxpool opened via db.NewPool; chi router mounted with ./static as the
asset root
- http.Server: ReadTimeout=15s, WriteTimeout=15s, IdleTimeout=60s
(T-01-10 slow-client mitigation)
- signal.NotifyContext (Go 1.21+) traps SIGINT/SIGTERM, propagates through
ctx; on signal: srv.Shutdown with 10s timeout, then explicit pool.Close
(Pitfall 4 — never via defer)
- No /readyz route (Phase 7 scope)
- templates/layout.templ: base HTML shell per UI-SPEC §Base Layout Contract
(max-w-5xl container, slate-50 header, slate-200 borders, footer copy,
/static/tailwind.css in <head>, /static/htmx.min.js deferred at body end —
D-10: HTMX never loaded from a CDN)
- templates/index.templ: root page consuming @ui.Card and @ui.Button for the
canonical HTMX demo (UI-SPEC §Component Library Contract canonical block)
- templates/fragments.templ: TimeFragment renders <span> with RFC3339 UTC
timestamp; templ auto-escapes interpolation (T-01-13)
- internal/web/handlers.go: HealthzHandler (200 ok / 503 degraded per D-20,
2s Ping timeout), IndexHandler, DemoTimeHandler with injected clock
- internal/web/router.go: Pinger interface; NewRouter wires
RequestIDMiddleware → RealIP → SlogLoggerMiddleware → Recoverer (D-08
+ Pitfall 6 — chi middleware.Logger deliberately NOT registered) and
routes /, /healthz, /demo/time, /static/* via http.FileServer (T-01-08
path traversal blocked by http.Dir)
All six handler tests + ui package tests are GREEN under default go test.
- Remove //go:build red_gate tag from internal/web/handlers_test.go and
internal/db/pool_test.go now that consumer symbols are about to exist
- go mod tidy after real importers land (deferred from Plan 01-01 per
Codex concern #1) — chi/v5, templ, pgx/v5, google/uuid now in require list
- internal/db/pool.go: NewPool(ctx, dsn) builds a pgxpool.Pool with
MaxConns=10, MinConns=1; no eager Ping (RESEARCH Pitfall 2)
- internal/web/slog.go: NewSlogHandler returns JSON when env='production',
text otherwise; pure helper, no slog.SetDefault side effect
- internal/web/middleware.go: RequestIDMiddleware (UUIDv4 → ctx +
X-Request-ID header), LoggerFromContext helper, SlogLoggerMiddleware
factory using chi WrapResponseWriter; field allowlist per V7/T-01-09
- handlers_test.go (//go:build red_gate): TestHealthz_OK, TestHealthz_Down,
TestIndex_RendersHxGet, TestDemoTime_Fragment, TestRequestID_HeaderSet,
TestSlog_HandlerSwitch — reference web.HealthzHandler / NewRouter /
NewSlogHandler / Pinger to be implemented in Plan 01-03
- pool_test.go (//go:build red_gate): TestPool_Connects with t.Skip
fallback when DATABASE_URL is unset
- Build tag isolates the RED state from default 'go test ./...' (Codex #3)
- sqlc.yaml: postgresql engine, schema points at migrations/ (Pitfall 7), pgx/v5 sql_package
- tailwind.input.css: @source globs for templ + internal/web Go files (Pitfall 3), @imports four ui/*.css files per UI-SPEC
- .air.toml: watches .go + .templ, excludes generated *_templ.go (Pitfall 5), runs 'templ generate' pre-build
- Tailwind watch is NOT wired into air pre_cmd (two-terminal workflow per RESEARCH Open Q2)
Adds a Component Library Contract section locking in a small in-house
templ design-system under backend/internal/web/ui/, modeled on the
reference at go-backend/internal/web/ui/. Phase 1 ships only Button,
Card, and Badge; later phases extend the same package.
Lock base layout, spacing/typography/color tokens, and the canonical
HTMX interaction pattern that later phases inherit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
