[jayleaton]

Problem

The Go successor to the Next.js template has no foundation yet. There is no server, no database layer, no layering enforcement, no CI and no agent docs, so feat/auth and feat/web-ui have nothing to plug into.

How

Same layers as the original, rebuilt in Go and enforced by lint:

packages/database (goose migrations → sqlc queries → UserRepository)
        ↓
apps/web/internal/services (UserService: 403-not-self, typed service errors)
        ↓
apps/web/internal/api (JSON envelope, Public/Authenticated wrapper)   apps/web/ui (feat/web-ui)
        ↑ mounted by apps/web/internal/server: /healthz · /api/auth/ (auth.Handler) · /api/core/v1 · / (UI)

• Binary: server serve binds 0.0.0.0:PORT with slog logging, rejects cross-origin browser writes, and shuts down gracefully. server migrate runs auth migrations, then app migrations (goose_app).
• Config: env is validated once at boot and every problem is reported together. AppRoutes/APIRoutes and Features live in apps/web/internal/config. There are no hardcoded origins.
• Users API: GET/PATCH/DELETE /api/core/v1/users and PATCH /api/core/v1/users/{id}. Input types live in validate; each handler is about five lines.
• Layering: depguard rules live in .golangci.yml. scripts/check-layering.sh proves they still reject forbidden imports.
• Tests: service and handler tests use in-memory fakes. Repository tests run against real Postgres: one throwaway tmpfs server and a migrated template database cloned per test, so tests run in parallel.
• Tooling: Makefile, compose (Postgres 18 + pgweb on 127.0.0.1), distroless Dockerfile, railway.json (pre-deploy /server migrate, healthcheck /healthz), one CI workflow (path filters, generated-code diff, golangci-lint, race tests, ci-ok as the single required check, merge_group, drafts skipped), plus AGENTS.md, CLAUDE.md, CONTEXT.md and README.md.

Evidence

All numbers are from local runs.

Docker image (distroless static)	5.1 MB compressed; binary 11.4 MB
Idle RSS, running container	13.1 MB VmRSS (cgroup 4.1 MiB), after 200 requests
Warm make ci (build, generated-code diff, lint, layering proof, race tests)	5.3 s; 6.2 s with the test cache cleared
Repository tests	about 0.1 s each
GitHub Actions, cold cache (run 39733960845, attempt 1)	1m54s wall; go job 1m44s (build 23 s, tests 33 s)
GitHub Actions, warm cache (same run, attempt 2)	about 45 s wall; go job 36 s, of which service container 10 s and setup-go cache restore 12 s

• Fresh clone: make db-up && make migrate && make dev served /healthz and the users API with the dev auth fake. make lint test gave 0 issues and all packages passed.
• Users API, end to end: PATCH rename, image set and clear → 200. PATCH another user → 403. Bad body → 400 with field details. DELETE → 200, then GET → 401.
• Layering proof: all 6 probes are rejected. With the api/ui rule removed, 4 probes fail and the script exits 1.

Decisions to revisit

• No email changes through UpdateUserSettings: the app may only change name and image, so an email field gets a 400. Email changes belong in the auth flows.
• image: null clears the image. The original couldn't clear it once set.
• Dev auth fake and the stand-in user table: until packages/auth lands, migrate creates user from a stub (packages/database/authstub). In development every request is signed in as a seeded dev user; outside development, protected routes return 401. A dev database migrated with the stub may need docker compose down -v once real auth lands.
• Settings beyond the original list: PORT (Railway sets it), TRUSTED_ORIGINS and FROM_EMAIL.
• Dev tools live in tools/go.mod, not the root go.mod. actionlint has its own tools/actionlint/go.mod, because its yaml dependency clashes with golangci-lint's.
• make dev and make build don't regenerate code. sqlc needs cgo, and the generated code is committed; CI checks it's up to date.
• No ENTRYPOINT in the image, so Railway's /server migrate override can't be prefixed with a second /server.

Wiring left for the merges

• feat/auth (marked TODO(feat/auth) in the code):
  • Use auth.Migrate instead of authstub.Migrate, in apps/web/cmd/server (migrations) and in packages/database/dbtest/app.go.
  • Point the sqlc schema in packages/database/sqlc.yaml at ../auth/migrations.
  • Pass *auth.Auth as server.Deps.Auth, plus a ~6-line function that turns auth.UserFrom into an api.CallerFrom.
  • Delete apps/web/internal/server/devauth and packages/database/authstub.
• feat/web-ui: pass the UI's http.Handler as server.Deps.UI; it is mounted at /. Add templ as a tool in the root go.mod. make generate and CI already run templ generate once apps/web/ui exists.

Merge Danger

Door: two-way. Nothing is deployed, and the branch only adds files.

Blast Radius: repo-wide. Every later branch builds on these layers, the lint rules and CI.

🤖 Generated with Claude Code