@nakedev/go-scaffold 0.1.0

package/templates/create/base/.claude/skills/go-scaffold/SKILL.md.hbs

@@ -0,0 +1,83 @@
+---
+name: go-scaffold
+description: >
+  Use whenever the user asks to add, create, scaffold, wire up, or generate a
+  new domain/feature/resource OR a new endpoint/method in THIS project —
+  including indirect or paraphrased requests that imply new backend surface
+  area without saying "module"/"method" literally, e.g. "add a products
+  feature", "let admins approve orders", "we need an endpoint for X", "look
+  up a user by email". This project was scaffolded by go-scaffold and has a
+  go-scaffold.config.json at its root — check for that file before assuming
+  this applies. Do NOT use for: business logic inside an already-generated
+  method body, model/DTO field edits, foreign keys/relations between
+  domains, bug fixes, refactors of existing code, or any project that lacks
+  go-scaffold.config.json at its root.
+---
+
+# go-scaffold
+
+This project's domain modules (model, dto, errors, repository, service,
+handler) and their endpoints are generated with the `go-scaffold` CLI — do
+not hand-write a new one. Hand-writing a new `internal/app/<name>/` package,
+or adding a method by editing the handler/service directly, produces a shape
+that doesn't match the rest of the codebase (missing route registration,
+missing AutoMigrate wiring, a `repository` interface out of sync with its
+`fakeRepo` test mock, inconsistent error-catalog naming, etc.).
+
+## When to use this skill
+
+- Any request for a new feature/resource/domain, even named informally
+  ("add invoices", "we need a way to track X")
+- Any request for a new endpoint on an existing feature, even phrased as a
+  capability ("let users do X", "admins should be able to Y", "add a lookup
+  by Z")
+- The user explicitly says "generate", "scaffold", or names the CLI
+
+## When NOT to use this skill
+
+- Filling in business logic inside a method the CLI already generated
+- Editing model fields, DTO validation, or existing method bodies
+- Wiring a foreign key / relation between two domains
+- Bug fixes and refactors
+- The project has no `go-scaffold.config.json` at its root
+
+## How to use it
+
+Run from the project root:
+
+```bash
+go-scaffold generate module <name>
+go-scaffold generate method <module> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]
+```
+
+`<name>` for a module should be a singular, lowercase, one-word domain noun
+(e.g. `order`, not `Orders` or `order-item`) — the CLI derives the Go
+package name, the pluralized REST route (`/orders`), and the table name
+from it.
+
+### `generate module <name>`
+
+What you get: `internal/app/<name>/{model/,dto,errors,repository,service,handler,service_test,handler_test}.go`,
+a route registered under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}
+in `cmd/api/main.go`, the model added to the `AutoMigrate` call, and a new
+file in `migrations/`. There's no per-domain versioning — the route prefix
+is a single project-wide choice made at `create` time.
+
+### `generate method <module> <name>`
+
+Patches the existing module in place — never overwrites a method with the
+same name; if the name collides it asks for a different one instead. Route
+and shape depend on `--type`:
+
+| `--type` | Route | Notes |
+|---|---|---|
+| `get --get-mode all` | `GET /<plural>/<kebab-name>` | list-style, reuses `FindAll` — TODO to add real filtering |
+| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | adds a real `FindBy<F>` query to the repository (and its `repository` interface + `fakeRepo` test stub); `--field` can't be `id` |
+| `post` | `POST /<plural>/<kebab-name>` | adds a body DTO; service body is a TODO stub (`apperror.NewInternal()` until implemented) |
+| `put` / `patch` | `<VERB> /<plural>/:id/<kebab-name>` | finds the record by id, TODO before saving (safe no-op until implemented) |
+| `delete` | `DELETE /<plural>/:id/<kebab-name>` | TODO stub (`apperror.NewInternal()` until implemented) |
+
+What you still do by hand: real field names on the model/DTOs (the generated
+ones are placeholders), any foreign key to another domain (see
+`docs/architect/patterns.md` for the 3 rules), and the actual business logic
+behind every `TODO` the CLI leaves.

package/templates/create/base/.env.example.hbs

@@ -0,0 +1,7 @@
+PORT=8080
+DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable
+LOG_LEVEL=info
+AUTO_MIGRATE=true
+DB_MAX_OPEN_CONNS=10
+DB_MAX_IDLE_CONNS=10
+DB_CONN_MAX_LIFETIME_MIN=5

package/templates/create/base/.github/workflows/ci.yml.hbs

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: {{dbName}}
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - run: go build ./...
+
+      - run: go vet ./...
+
+      - name: gofmt check
+        run: |
+          diff <(gofmt -l .) <(printf '')
+
+      - uses: golangci/golangci-lint-action@v6
+        with:
+          version: latest
+
+      # TEST_DB_DSN not set: the default in handler_test.go already points at
+      # localhost:5432/{{dbName}} with postgres/postgres, matching the service above
+      - run: go test ./...

package/templates/create/base/.gitignore.hbs

@@ -0,0 +1,5 @@
+app.db
+*.db
+.env
+bin/
+docs/openapi.bundled.yaml

package/templates/create/base/.golangci.yml.hbs

@@ -0,0 +1,32 @@
+# golangci-lint v2 config format — v1's `run:`/`linters: enable:` + `issues: exclude-dirs:`
+# top-level keys were replaced by `version: "2"` + `linters:`/`formatters:` with their own
+# `exclusions:` blocks (see https://golangci-lint.run/docs/product/migration-guide/).
+version: "2"
+
+linters:
+  enable:
+    - errcheck
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+  settings:
+    errcheck:
+      exclude-functions:
+        # gin.Context.Error()'s return value is intentionally never checked —
+        # it just appends to Context.Errors for middleware.Error() to render,
+        # the "handling" of the error already happened via `return` right after.
+        - (*github.com/gin-gonic/gin.Context).Error
+  exclusions:
+    paths:
+      - migrations
+
+formatters:
+  # gofmt only, not goimports: the CLI's own gofmtTree() only runs `gofmt -w .`
+  # (goimports needs a separate binary install), so keep the lint config matching
+  # what actually formats generated code, or every fresh project starts pre-failing.
+  enable:
+    - gofmt
+  exclusions:
+    paths:
+      - migrations

package/templates/create/base/.vscode/settings.json.hbs

@@ -0,0 +1,11 @@
+{
+  "go.useLanguageServer": true,
+  "go.lintTool": "golangci-lint",
+  "go.formatTool": "gofmt",
+  "[go]": {
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": "explicit"
+    }
+  }
+}

package/templates/create/base/AGENTS.md.hbs

@@ -0,0 +1,68 @@
+# Agent Guidance: {{projectName}}
+
+This project was scaffolded by `@nakedev/go-scaffold` and is maintained using
+its `generate` subcommands — new domain modules and new endpoints are not
+hand-written.
+
+## Hard rule: use the CLI to add a new domain module or a new endpoint
+
+If you are about to create a **new** domain (a new `internal/app/<name>/`
+package with its own model/handler/service/repository), or add a **new**
+endpoint to an existing one — stop and run the CLI instead:
+
+```bash
+go-scaffold generate module <name>
+go-scaffold generate method <module> <name> --type <get|post|put|patch|delete>
+```
+
+This applies **even when the request doesn't say "module"/"method" or name
+the CLI at all**. Recognize indirect asks as generation work, for example:
+
+- "add a products feature" → a new domain (`generate module products`)
+- "let admins approve orders" → a new method on an existing module
+  (`generate method orders approve --type patch`)
+- "we need an endpoint that lists overdue invoices" → a new `get` method
+  (`generate method invoices findOverdue --type get --get-mode all`)
+- "add a way to look up a user by email" → a new `get` lookup
+  (`generate method users findByEmail --type get --get-mode one --field email`)
+
+Run `go-scaffold generate module --help` / `generate method --help` before
+hand-rolling anything that looks like scaffolding.
+
+## What the CLI does NOT do — these are still done by hand, as normal
+
+- Business logic inside a generated method (the CLI leaves a TODO-marked
+  stub — filling in real behavior is your job)
+- Adding fields to a generated model/DTO beyond `id`/`created_at`/`updated_at`
+- Foreign keys / relations between domains — add the column, the migration
+  `REFERENCES ... ON DELETE ...` clause, and the `dberr.IsForeignKey` mapping
+  yourself; see `docs/architect/patterns.md` for the 3 rules domains with a
+  relation must follow
+- Bug fixes, refactors, or edits to existing logic
+- Anything in a project that does **not** have `go-scaffold.config.json` at
+  its root — that means the project wasn't scaffolded by this CLI, and this
+  rule does not apply
+
+## Command quick reference
+
+- `go-scaffold generate module <name>` — model + dto + errors + repository +
+  service + handler + tests, wired into `cmd/api/main.go` (AutoMigrate +
+  route registration) and appended to `migrations/`. Use `--no-full` for a
+  bare skeleton (no default CRUD/routes) when you'd rather add endpoints one
+  at a time with `generate method`
+- `go-scaffold generate method <module> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]` —
+  patches an *existing* module's handler + service (and repository, for a
+  `get --get-mode one --field` lookup) in place; never overwrites a method
+  with the same name — pick a different one if it collides. Endpoint docs in
+  `docs/openapi.yaml` are **not** auto-updated for methods — the command
+  prints the route so you can add the spec entry by hand
+- `go-scaffold remove module <name>` — the inverse of `generate module`:
+  deletes the package and un-wires main.go / openapi.yaml / migrations. Use
+  this to drop a domain instead of hand-deleting the folder (a partial
+  hand-delete leaves duplicate wiring behind)
+- Every route in this project is grouped under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}
+  (set once at `create` time via `--api-prefix`) — there is no per-domain
+  versioning; a breaking API change gets a new domain package or a new DTO
+  field, not a duplicated model
+- Full architecture rationale for this project's configuration: see
+  `docs/architect/`

package/templates/create/base/CLAUDE.md.hbs

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/create/base/Makefile.hbs

@@ -0,0 +1,93 @@
+DB_HOST ?= localhost
+DB_PORT ?= 5432
+DB_USER ?= postgres
+DB_NAME ?= {{dbName}}
+PGPASSWORD ?= postgres
+
+.PHONY: run build test fmt vet lint tidy db-create db-drop migrate-up migrate-down{{#if openapiDocs}} openapi-bundle{{/if}}{{#if docker}} docker-up docker-down{{/if}}
+
+run:
+	go run ./cmd/api
+
+build:
+	go build -o bin/api ./cmd/api
+
+test:
+	go test ./...
+
+fmt:
+	gofmt -w .
+
+vet:
+	go vet ./...
+
+lint:
+	golangci-lint run
+
+tidy:
+	go mod tidy
+
+# creates the database itself (not the schema — AUTO_MIGRATE or migrate-up does that).
+# connects to the always-present "postgres" maintenance DB to run CREATE DATABASE,
+# since the target DB may not exist yet. Safe to re-run — skips if it already exists.
+# \gexec only works read from stdin, not through -c, hence the pipe.
+# no local psql? falls back to `docker exec` into whatever container is publishing
+# DB_PORT — the project's own `docker compose up`'d postgres, or an unrelated
+# shared Postgres container you already have running, either works the same way.
+# override DB_HOST/DB_PORT/DB_USER/DB_NAME/PGPASSWORD to point at a different server.
+db-create:
+	@if command -v psql >/dev/null 2>&1; then \
+		echo "SELECT 'CREATE DATABASE $(DB_NAME)' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$(DB_NAME)')\gexec" | \
+			PGPASSWORD=$(PGPASSWORD) psql -h $(DB_HOST) -p $(DB_PORT) -U $(DB_USER) -d postgres && echo "SUCCESS! database $(DB_NAME) is ready"; \
+	elif [ "$(DB_HOST)" = "localhost" ] || [ "$(DB_HOST)" = "127.0.0.1" ]; then \
+		container=$$(docker ps -q --filter "publish=$(DB_PORT)" | head -1); \
+		if [ -z "$$container" ]; then \
+			echo "psql not found and no container is publishing port $(DB_PORT) — install the PostgreSQL client (brew install libpq && brew link --force libpq), or start Postgres any way you like and re-run" >&2; \
+			exit 1; \
+		fi; \
+		echo "no local psql — using docker exec into $$container"; \
+		echo "SELECT 'CREATE DATABASE $(DB_NAME)' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$(DB_NAME)')\gexec" | \
+			docker exec -i -e PGPASSWORD=$(PGPASSWORD) $$container psql -U $(DB_USER) -d postgres && echo "SUCCESS! database $(DB_NAME) is ready"; \
+	else \
+		echo "psql not found — install the PostgreSQL client (brew install libpq && brew link --force libpq) to connect to $(DB_HOST):$(DB_PORT)" >&2; \
+		exit 1; \
+	fi
+
+db-drop:
+	@if command -v psql >/dev/null 2>&1; then \
+		PGPASSWORD=$(PGPASSWORD) psql -h $(DB_HOST) -p $(DB_PORT) -U $(DB_USER) -d postgres -c "DROP DATABASE IF EXISTS $(DB_NAME);" && echo "SUCCESS! database $(DB_NAME) dropped"; \
+	elif [ "$(DB_HOST)" = "localhost" ] || [ "$(DB_HOST)" = "127.0.0.1" ]; then \
+		container=$$(docker ps -q --filter "publish=$(DB_PORT)" | head -1); \
+		if [ -z "$$container" ]; then \
+			echo "psql not found and no container is publishing port $(DB_PORT) — install the PostgreSQL client (brew install libpq && brew link --force libpq), or start Postgres any way you like and re-run" >&2; \
+			exit 1; \
+		fi; \
+		docker exec -i -e PGPASSWORD=$(PGPASSWORD) $$container psql -U $(DB_USER) -d postgres -c "DROP DATABASE IF EXISTS $(DB_NAME);" && echo "SUCCESS! database $(DB_NAME) dropped"; \
+	else \
+		echo "psql not found — install the PostgreSQL client (brew install libpq && brew link --force libpq) to connect to $(DB_HOST):$(DB_PORT)" >&2; \
+		exit 1; \
+	fi
+
+migrate-up:
+	migrate -path migrations -database "$$DB_DSN" up
+
+migrate-down:
+	migrate -path migrations -database "$$DB_DSN" down 1
+{{#if openapiDocs}}
+
+# docs/openapi.yaml is hand-written and split across sibling files via relative
+# $ref (common/, health/, per-domain folders) — fine for tools that resolve
+# $ref over HTTP (Scalar, Swagger UI, Redoc), but importers that read a local
+# file as-is (Bruno, some Postman flows) never follow $ref and see zero routes.
+# This bundles everything into one fully-resolved file for those tools.
+openapi-bundle:
+	npx --yes @redocly/cli bundle docs/openapi.yaml -o docs/openapi.bundled.yaml
+{{/if}}
+{{#if docker}}
+
+docker-up:
+	docker compose up -d
+
+docker-down:
+	docker compose down
+{{/if}}

package/templates/create/base/README.md.hbs

@@ -0,0 +1,143 @@
+# {{projectName}}
+
+Gin + GORM backend, scaffolded by [go-scaffold](https://github.com/nakedev/go-scaffold). Organized by feature (domain), Postgres-backed, schema managed with [golang-migrate](https://github.com/golang-migrate/migrate).
+
+This is a bare skeleton — no domain modules yet. Add one with:
+
+```bash
+go-scaffold generate module orders
+```
+
+See `docs/architect/` for the conventions every generated module follows, and `AGENTS.md`/`CLAUDE.md` if you're working with an AI coding agent in this repo.
+
+## Layout
+
+```
+cmd/
+└── api/
+    └── main.go                # config, slog, graceful shutdown, wires domains — the only entry point for now
+internal/
+├── platform/                  # talks to real external systems (DB, later: cache, queue, mail, ...)
+│   └── database/              # opens the connection + pool (GORM)
+├── shared/                    # pure logic/framework glue, no I/O
+│   ├── config/                # loads config from env
+│   ├── apperror/               # central error type (status + payload)
+│   ├── dberr/                 # maps DB errors to constraint kind (IsDuplicate, IsForeignKey) — shared by every domain
+│   ├── httpx/                 # HTTP helpers shared by every domain (ParseID, BindErr)
+│   ├── middleware/            # RequestID, Logger (slog), Error
+│   └── pagination/             # parses ?limit=&offset=, response envelope
+└── app/                       # domain packages — empty until you `generate module`
+```
+
+## Run
+
+```bash
+{{#if docker}}
+make docker-up                     # local Postgres (postgres:5432)
+{{/if}}
+make db-create                     # create the {{dbName}} database itself (once — safe to re-run)
+go mod tidy
+make run                           # AUTO_MIGRATE=true creates the schema automatically in dev
+# or override with env (the app reads os.Getenv directly, see .env.example):
+export $(grep -v '^#' .env.example | xargs) && make run
+```
+
+`make db-create` connects to Postgres at `DB_HOST`/`DB_PORT`/`DB_USER` (default:
+`localhost`/`5432`/`postgres`, matching `.env.example`) using the `psql`
+client — works the same whether Postgres came from `make docker-up` or an
+existing instance you already have running. Override any of
+`DB_HOST`/`DB_PORT`/`DB_USER`/`DB_NAME`/`PGPASSWORD` to point at a different
+server. If `psql` isn't installed locally and `DB_HOST` is `localhost`, it
+falls back to `docker exec` into whichever container is publishing
+`DB_PORT` — this project's own Postgres (`make docker-up` first) or any
+other Postgres container you already have running.
+
+Server listens on `:8080` (override with `PORT`). Ctrl+C = graceful shutdown.
+
+## Makefile
+
+```bash
+make run            # go run ./cmd/api
+make build          # go build -o bin/api ./cmd/api
+make test           # go test ./...
+make fmt            # gofmt -w .
+make vet            # go vet ./...
+make lint           # golangci-lint run (see .golangci.yml)
+make tidy           # go mod tidy
+make db-create       # create the database itself (safe to re-run)
+make db-drop         # drop the database
+make migrate-up      # apply migrations (needs $DB_DSN)
+make migrate-down     # roll back one migration
+{{#if docker}}make docker-up       # docker compose up -d
+make docker-down     # docker compose down
+{{/if}}```
+
+## Migrations
+
+Schema is managed with [golang-migrate](https://github.com/golang-migrate/migrate), files live in `migrations/`.
+
+```bash
+brew install golang-migrate
+# or: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
+
+migrate -path migrations -database "$DB_DSN" up
+migrate -path migrations -database "$DB_DSN" down 1
+migrate create -ext sql -dir migrations -seq add_something
+```
+
+**dev:** leave `AUTO_MIGRATE=true` (default) so GORM's AutoMigrate creates the schema quickly.
+**prod:** set `AUTO_MIGRATE=false` and run `migrate up` as a separate deploy step — versioned, has rollback (`down`), doesn't lock the table the way AutoMigrate does once there's real data.
+
+## Env vars
+
+| var | default | notes |
+|---|---|---|
+| `PORT` | `8080` | |
+| `DB_DSN` | `postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable` | used by both GORM and the `migrate` CLI |
+| `LOG_LEVEL` | `info` | debug/info/warn/error |
+| `AUTO_MIGRATE` | `true` | disable in prod and use `migrate up` (see Migrations) |
+| `DB_MAX_OPEN_CONNS` | `10` | |
+| `DB_MAX_IDLE_CONNS` | `10` | |
+| `DB_CONN_MAX_LIFETIME_MIN` | `5` | minutes |
+
+## Tests
+
+Integration tests (handler-level) run against a **real Postgres** instance (same engine as prod), each test in a transaction that's rolled back — no leftover rows. If the DB isn't reachable those tests **skip** (unit tests using a fake repo always run).
+
+```bash
+{{#if docker}}
+make docker-up      # local postgres first
+{{/if}}
+make test
+# point at a different test DB: TEST_DB_DSN=postgres://... go test ./...
+```
+
+## Error payload
+
+```json
+{"error":{"code":"VALIDATION_ERROR","message":"invalid input","details":{"email":"email"},"request_id":"a1b2..."}}
+```
+
+`code` is machine-readable, `details` names the field that failed, `request_id` correlates with server logs (header `X-Request-ID`).
+{{#if openapiDocs}}
+
+## API spec
+
+`docs/openapi.yaml` is hand-written and served, along with every file it `$ref`s (`common/`, `health/`, per-domain folders), under `/docs` while the server runs — point a renderer (Scalar, Swagger UI, Redoc) or a client generator (Hey API) at `http://localhost:8080/docs/openapi.yaml`. Update the spec by hand whenever an endpoint/DTO changes.
+
+Some tools don't resolve external `$ref`s when importing a local file — they read it as-is and see zero routes (Bruno's "Import Collection" does this; some Postman flows too). For those, bundle the spec into one fully-resolved file first:
+
+```bash
+make openapi-bundle          # writes docs/openapi.bundled.yaml (gitignored — regenerate anytime)
+```
+
+Import `docs/openapi.bundled.yaml` instead. Tools that resolve `$ref` over HTTP or when reading a URL (Scalar, Swagger UI, Redoc) don't need this — point them at the live `/docs/openapi.yaml` URL above.
+{{/if}}
+
+## Adding a domain
+
+```bash
+go-scaffold generate module orders
+```
+
+Scaffolds `internal/app/orders/` (model/dto/errors/repository/service/handler + tests), wires it into `cmd/api/main.go` (AutoMigrate, route registration), and appends a migration file. See `docs/architect/patterns.md` for the module shape and the rules for domains with foreign keys.

package/templates/create/base/cmd/api/main.go.hbs

@@ -0,0 +1,116 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"{{goModule}}/internal/platform/database"
+	"{{goModule}}/internal/shared/config"
+	"{{goModule}}/internal/shared/middleware"
+	// go-scaffold:imports
+
+	"github.com/gin-gonic/gin"
+)
+
+func main() {
+	cfg := config.Load()
+
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))
+	slog.SetDefault(logger)
+
+	db, err := database.Open(cfg)
+	if err != nil {
+		logger.Error("open db", "error", err)
+		os.Exit(1)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		logger.Error("db handle", "error", err)
+		os.Exit(1)
+	}
+
+	if cfg.AutoMigrate {
+		// ponytail: AutoMigrate is for dev only (add-only, locks the table once data grows)
+		// prod: set AUTO_MIGRATE=false and run golang-migrate as versioned SQL instead
+		if err := db.AutoMigrate(
+			// go-scaffold:models
+		); err != nil {
+			logger.Error("migrate", "error", err)
+			os.Exit(1)
+		}
+	}
+
+	r := gin.New()
+	r.Use(gin.Recovery(), middleware.RequestID(), middleware.Logger(logger), middleware.Error())
+
+	// liveness = is the process up / readiness = ready for traffic (can it reach the DB)
+	r.GET("/livez", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"status": "ok"}) })
+	r.GET("/readyz", func(c *gin.Context) {
+		if err := sqlDB.PingContext(c.Request.Context()); err != nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"status": "unavailable"})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+{{#if openapiDocs}}
+	// hand-written spec at docs/openapi.yaml, split across sibling files (common/, health/,
+	// <domain>/) via relative $ref — serve the whole tree under one prefix so a client that
+	// resolves $ref over HTTP (Scalar, Swagger UI, Redoc, Hey API pointed at a URL) can reach
+	// them too; StaticFile on just the index file would 404 on every $ref it follows.
+	r.Static("/docs", "./docs")
+{{/if}}
+
+	api := r.Group("/{{apiPrefix}}")
+	// go-scaffold:routes
+	_ = api // dropped once `generate module` registers the first route
+
+	srv := &http.Server{
+		Addr:         ":" + cfg.Port,
+		Handler:      r,
+		ReadTimeout:  10 * time.Second,
+		WriteTimeout: 10 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	// graceful shutdown: catch SIGINT/SIGTERM, let in-flight requests finish before closing
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	go func() {
+		logger.Info("listening", "addr", srv.Addr)
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			logger.Error("server", "error", err)
+			os.Exit(1)
+		}
+	}()
+
+	<-ctx.Done()
+	logger.Info("shutting down")
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		logger.Error("shutdown", "error", err)
+	}
+	logger.Info("stopped")
+}
+
+func parseLevel(s string) slog.Level {
+	switch s {
+	case "debug":
+		return slog.LevelDebug
+	case "warn":
+		return slog.LevelWarn
+	case "error":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo
+	}
+}

package/templates/create/base/go.mod.hbs

@@ -0,0 +1,11 @@
+module {{goModule}}
+
+go 1.25
+
+require (
+	github.com/gin-gonic/gin v1.10.0
+	github.com/go-playground/validator/v10 v10.20.0
+	github.com/google/uuid v1.6.0
+	gorm.io/driver/postgres v1.5.9
+	gorm.io/gorm v1.25.12
+)

package/templates/create/base/internal/platform/database/database.go.hbs

@@ -0,0 +1,28 @@
+package database
+
+import (
+	"{{goModule}}/internal/shared/config"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+// Open connects to Postgres and sets the connection pool — it talks to a
+// real external system, so it lives in platform/, not shared/.
+// Schema is managed via golang-migrate (migrations/) in prod, not AutoMigrate — see README.
+func Open(cfg config.Config) (*gorm.DB, error) {
+	db, err := gorm.Open(postgres.Open(cfg.DBDSN), &gorm.Config{TranslateError: true})
+	if err != nil {
+		return nil, err
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, err
+	}
+	sqlDB.SetMaxOpenConns(cfg.DBMaxOpenConns)
+	sqlDB.SetMaxIdleConns(cfg.DBMaxIdleConns)
+	sqlDB.SetConnMaxLifetime(cfg.DBConnMaxLifetime)
+
+	return db, nil
+}