groundwork-method 0.0.1 → 0.11.0

package/src/generators/go-microservice/docs/principles/stack/go/testing.md

@@ -0,0 +1,168 @@
+---
+title: Testing
+description: Go honeycomb testing with Testcontainers, table-driven tests, service perimeter tests, and httptest.
+status: active
+last_reviewed: 2026-05-26
+---
+# Testing
+
+## TL;DR
+
+Service perimeter tests are our default: real Postgres via Testcontainers, real HTTP via `httptest`, no mocks inside the service boundary. Unit tests exist for isolated, complex logic only. The default shape is the **test honeycomb** — a fat middle of sociable service tests, a thin solitary-unit layer, a few end-to-end checks — not the pyramid, which assumes a database in a test is expensive. This is the Go idiom of the framework testing canon (`docs/principles/foundations/testing.md`); the canon is the parent principle and wins on any disagreement.
+
+## Why this matters
+
+Tests that mock the database tell you the code compiles and the mock behaves as you programmed it — not that the real system works. Testcontainers has eliminated the main excuse for mocking Postgres. A service perimeter test catches the handler, service, repository, and schema working together; a unit test catches none of those integration points. The cost of a slow test suite is paid once per CI run; the cost of a mock that diverges from production is paid in incidents.
+
+## The testing tiers
+
+### Tier 1 — Service perimeter tests (default)
+
+Most tests live here. They start a real Postgres container, run migrations, exercise the handler through `httptest.NewRecorder`, and assert on HTTP responses and database state.
+
+```go
+func TestCreateMeeting(t *testing.T) {
+    ctx := context.Background()
+
+    pg, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+        ContainerRequest: testcontainers.ContainerRequest{
+            Image:        "postgres:16",
+            ExposedPorts: []string{"5432/tcp"},
+            Env: map[string]string{
+                "POSTGRES_PASSWORD": "test",
+                "POSTGRES_DB":       "service_test",
+            },
+            WaitingFor: wait.ForListeningPort("5432/tcp"),
+        },
+        Started: true,
+    })
+    require.NoError(t, err)
+    t.Cleanup(func() { pg.Terminate(ctx) })
+
+    connStr, _ := pg.ConnectionString(ctx, "sslmode=disable")
+    db, err := sql.Open("pgx", connStr)
+    require.NoError(t, err)
+
+    // run migrations
+    require.NoError(t, migrate.Up(ctx, db))
+
+    handler := buildHandler(db) // your composition root helper
+    rec := httptest.NewRecorder()
+    req := httptest.NewRequest(http.MethodPost, "/meetings", body(t, createReq))
+    handler.ServeHTTP(rec, req)
+
+    require.Equal(t, http.StatusCreated, rec.Code)
+    // assert database state
+}
+```
+
+Use `t.Cleanup` for container teardown. Use `require` for fatal assertions; `assert` for non-fatal checks on the same response.
+
+### Tier 2 — Unit tests (complex isolated logic only)
+
+Write a unit test when:
+
+- The function has complex conditional logic or multiple branches that would be expensive to exercise through HTTP
+- The function is pure (no I/O, no database) and has clear inputs/outputs
+- Validating edge cases would require brittle HTTP request construction
+
+Do not write a unit test because it is faster or easier to write. A unit test that passes while the integrated system is broken is a false signal.
+
+```go
+func TestScoringLogic(t *testing.T) {
+    cases := []struct {
+        name  string
+        input ScoringInput
+        want  float64
+    }{
+        {"zero input", ScoringInput{}, 0},
+        {"full confidence", ScoringInput{Confidence: 1.0, Length: 100}, 1.0},
+        {"penalises short segments", ScoringInput{Confidence: 1.0, Length: 5}, 0.5},
+    }
+
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            got := Score(tc.input)
+            assert.InDelta(t, tc.want, got, 0.001)
+        })
+    }
+}
+```
+
+Table-driven tests are the Go idiom for parameterised cases. Use a `cases` slice with descriptive `name` fields so failure output identifies which case broke.
+
+### Tier 3 — System tests (rare, explicit)
+
+Full end-to-end tests across multiple live services. These run in a dedicated CI stage against a deployed environment, not on every PR. They are expensive to write and maintain — add one only when no Tier 1 test can reach the integration point being verified.
+
+## Test structure
+
+### Package layout
+
+Test files live in `_test.go` files alongside the code they test. Internal tests use the same package name (`package meetings`); black-box tests use the `_test` suffix (`package meetings_test`). Prefer black-box tests for handlers and services to prevent coupling tests to unexported implementation details.
+
+### Shared test helpers
+
+Shared helpers (container setup, database fixtures, request builders) live in `internal/testutil/` and are only compiled for tests (`package testutil`). They are not shipped with the binary.
+
+### Test isolation
+
+Each test creates its own database state. Use a fresh schema per test run, or truncate tables in `t.Cleanup`. Do not share mutable state across tests — parallel tests will race.
+
+### Parallel tests
+
+Mark independent tests with `t.Parallel()`. Tests that share a container must synchronise table state or use separate databases/schemas. Testcontainers supports `ReuseRequest` for container reuse across a test suite; use it for long-lived containers that are read-only.
+
+## What to mock
+
+Mock only what you cannot make real or what is genuinely too expensive:
+
+| Dependency | Approach |
+|---|---|
+| Postgres | Real container via Testcontainers |
+| External HTTP APIs | `httptest.NewServer` returning canned responses |
+| LLM / embedding providers | Interface mock with fixed outputs |
+| Pub/Sub | `testcontainers/modules/pubsub` or interface mock |
+| Time | Pass `time.Time` / `func() time.Time` as dependency; no global `time.Now` |
+
+Do not mock the database. Do not mock internal service or repository interfaces. Mocking your own internals tests the mock, not the code.
+
+## Running tests
+
+```bash
+# all unit and service tests
+go test ./...
+
+# with race detector (required before merging concurrency changes)
+go test -race ./...
+
+# specific package
+go test ./internal/meetings/...
+
+# verbose output for a single test
+go test -v -run TestCreateMeeting ./internal/meetings/...
+```
+
+## Trace assertions — observability is a test surface
+
+A critical-path request must emit an unbroken trace; a missing span is a test failure, not an instrumentation TODO. The mechanism is the OTel SDK's **in-memory span exporter** — register one in the test process, exercise the handler, and assert on the finished spans (the entry span exists, the work span is its descendant, the attributes a dashboard query depends on are present). Use `go.opentelemetry.io/otel/sdk/trace/tracetest` (`NewInMemoryExporter`), no external tooling. Assert what the contract promises and let the rest float — pinning the whole span tree couples the test to implementation.
+
+## Mutation testing — the assertion-quality read-out
+
+A fat service-perimeter test drives many branches through one HTTP call and can *execute* them all while only asserting on the response body. Mutation testing is the instrument that proves the suite checks what it runs: inject a fault, confirm a test fails; a surviving mutant is a covered-but-unchecked line. It is a **signal, never a gate**. Go's tooling is immature (`gremlins` is pre-1.0 and slow; `go-mutesting` is unmaintained), so here it stays a hand-run spot check on a dense package under active change, not a CI expectation.
+
+## Generate the inputs you can't enumerate
+
+Example-based tests check the cases you thought of; the bugs live in the cases you didn't. For dense, boundary-poor logic with a real invariant — a round-trip, a parser that must never panic, a calculation with an algebraic law — state the property and let the framework generate and shrink counterexamples (`pgregory.net/rapid`, or stdlib `testing/quick`). At the byte boundary, native `go test -fuzz` is first-class for parsers and decoders, and a failing input is saved under `testdata/fuzz/` as a permanent regression seed. Reach for these where invariants are real, not everywhere.
+
+## Naming
+
+Name a test by behaviour, not implementation: `[Function] should [expected outcome] when [condition]`. `TestCreateItem_Success` conveys nothing the dashboard does not already show; a failing name should let an on-call engineer form a hypothesis without opening the file.
+
+## Anti-patterns
+
+- **Mocking the database.** The whole point is to test the repository against a real schema.
+- **`testing.Short()` skipping service tests.** Service tests are fast; don't gate-keep them.
+- **Test helpers that test nothing.** A helper that builds a fully valid object in one line is fine; a helper that makes assertions on your behalf hides failures.
+- **Magic `time.Sleep` in tests.** Use `eventually` loops with tight timeouts, or make the behaviour deterministic.
+- **One giant test.** Each test case should be independently runnable and independently failing.

package/src/generators/go-microservice/files/.air.toml.template

@@ -0,0 +1,38 @@
+root = "."
+testdata_dir = "testdata"
+tmp_dir = "tmp"
+
+[build]
+  args_bin = []
+  bin = "./tmp/main"
+  cmd = "go build -o ./tmp/main ./cmd/api"
+  delay = 1000
+  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
+  exclude_file = []
+  exclude_regex = ["_test.go"]
+  exclude_unchanged = false
+  follow_symlink = false
+  full_bin = ""
+  include_dir = []
+  include_ext = ["go", "tpl", "tmpl", "html"]
+  include_file = []
+  kill_delay = "0s"
+  log = "build-errors.log"
+  send_interrupt = false
+  stop_on_error = true
+
+[color]
+  app = ""
+  build = "yellow"
+  main = "magenta"
+  runner = "green"
+  watcher = "cyan"
+
+[log]
+  time = false
+
+[misc]
+  clean_on_exit = false
+
+[screen]
+  clear_on_rebuild = false

package/src/generators/go-microservice/files/.env.template

@@ -0,0 +1,4 @@
+PORT=<%= assignedPort %>
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/<%= name %>?sslmode=disable
+REDIS_URL=redis://localhost:6379
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

package/src/generators/go-microservice/files/.golangci.yml.template

@@ -0,0 +1,82 @@
+version: "2"
+
+run:
+  concurrency: 4
+
+linters:
+  default: none
+  enable:
+    - bodyclose
+    - depguard
+    - errcheck
+    - gosec
+    - govet
+    - ineffassign
+    - nilerr
+    - prealloc
+    - staticcheck
+    - unparam
+    - unused
+  settings:
+    govet:
+      enable:
+        - shadow
+    # depguard enforces the inward dependency rule mechanically: the core
+    # (internal/core/... — domain entities and the application services that
+    # declare the interfaces they consume) must never import an edge adapter or
+    # an infrastructure driver. Adapters (internal/postgres, internal/kafka, …)
+    # and the composition root (cmd/...) may import anything; the arrow only ever
+    # points inward (edge -> core). This makes the architecture a CI gate, not a
+    # convention. A deliberate internal/core -> internal/postgres import fails the
+    # `golangci-lint run`.
+    depguard:
+      rules:
+        core:
+          files:
+            - "**/internal/core/**"
+          deny:
+            - pkg: "<%= name %>/internal/postgres"
+              desc: "the core declares interfaces; it must not import the postgres adapter (edge -> core only)"
+            - pkg: "<%= name %>/internal/kafka"
+              desc: "the core must not import the kafka adapter (edge -> core only)"
+            - pkg: "<%= name %>/internal/pubsub"
+              desc: "the core must not import the pubsub adapter (edge -> core only)"
+            - pkg: "<%= name %>/internal/httpclient"
+              desc: "the core must not import the outbound HTTP adapter (edge -> core only)"
+            - pkg: "<%= name %>/internal/websocket"
+              desc: "the core must not import the websocket adapter (edge -> core only)"
+            - pkg: "<%= name %>/internal/llm"
+              desc: "the core must not import the llm adapter (edge -> core only)"
+            - pkg: "<%= name %>/internal/entrypoints"
+              desc: "the core must not import the inbound HTTP edge (edge -> core only)"
+            - pkg: "database/sql"
+              desc: "the core is persistence-agnostic; SQL belongs in internal/postgres"
+            - pkg: "net/http"
+              desc: "the core is transport-agnostic; HTTP belongs at the edges"
+            - pkg: "github.com/go-chi/chi/v5"
+              desc: "routing is an edge concern; keep web frameworks out of the core"
+            - pkg: "github.com/danielgtaylor/huma/v2"
+              desc: "the API framework is an edge concern; keep it out of the core"
+            - pkg: "github.com/gorilla/websocket"
+              desc: "the websocket driver belongs in internal/websocket, not the core"
+            - pkg: "github.com/lib/pq"
+              desc: "the postgres driver belongs in internal/postgres, not the core"
+            - pkg: "github.com/confluentinc/confluent-kafka-go/v2/kafka"
+              desc: "the kafka driver belongs in internal/kafka, not the core"
+            - pkg: "cloud.google.com/go/pubsub"
+              desc: "the pubsub driver belongs in internal/pubsub, not the core"
+        domain:
+          files:
+            - "**/internal/core/domain/**"
+          deny:
+            - pkg: "<%= name %>/internal"
+              desc: "the domain depends on nothing inside the module; pure types and rules only"
+  exclusions:
+    generated: lax
+    rules:
+      - path: _test\.go
+        linters:
+          - bodyclose
+          - errcheck
+          - gosec
+          - unparam

package/src/generators/go-microservice/files/Dockerfile.dev.template

@@ -0,0 +1,12 @@
+FROM golang:1.25-alpine
+
+WORKDIR /app
+
+RUN go install github.com/air-verse/air@latest
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+CMD ["air", "-c", ".air.toml"]

package/src/generators/go-microservice/files/asyncapi-pubsub.yaml.template

@@ -0,0 +1,33 @@
+asyncapi: 3.0.0
+info:
+  title: <%= name %> PubSub API
+  version: 0.1.0
+  description: Asynchronous event schema for <%= name %> backend message brokers.
+servers:
+  production:
+    host: broker.example.com
+    protocol: <%= messaging === 'kafka' ? 'kafka' : 'googlepubsub' %>
+channels:
+  <%= name %>-events:
+    address: <%= name %>.events
+    messages:
+      publish:
+        $ref: '#/components/messages/cloudEvent'
+components:
+  messages:
+    cloudEvent:
+      payload:
+        type: object
+        properties:
+          specversion:
+            type: string
+          id:
+            type: string
+          type:
+            type: string
+          source:
+            type: string
+          time:
+            type: string
+          data:
+            type: object

package/src/generators/go-microservice/files/asyncapi-ws.yaml.template

@@ -0,0 +1,34 @@
+asyncapi: 3.0.0
+info:
+  title: <%= name %> WebSocket API
+  version: 0.1.0
+  description: WebSocket API for real-time <%= name %> events.
+servers:
+  dev:
+    host: localhost:4000
+    protocol: ws
+    pathname: /api/v1/ws
+channels:
+  events:
+    address: /api/v1/ws
+    messages:
+      subscribe:
+        $ref: '#/components/messages/cloudEvent'
+components:
+  messages:
+    cloudEvent:
+      payload:
+        type: object
+        properties:
+          specversion:
+            type: string
+          id:
+            type: string
+          type:
+            type: string
+          source:
+            type: string
+          time:
+            type: string
+          data:
+            type: object

package/src/generators/go-microservice/files/cmd/api/main.go.template

@@ -0,0 +1,149 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+	_ "github.com/joho/godotenv/autoload"
+	_ "github.com/lib/pq"
+
+	"<%= name %>/internal/config"
+	"<%= name %>/internal/core/service"
+	"<%= name %>/internal/entrypoints/api"
+	"<%= name %>/internal/postgres"
+<% if (websockets) { %>
+	"<%= name %>/internal/websocket"
+<% } %>
+)
+
+func main() {
+	setupLogger()
+
+	cfg := config.Load()
+
+	// Initialize OpenTelemetry
+	otelShutdown, err := config.InitProvider(context.Background(), "<%= name %>", cfg.Telemetry.CollectorURL)
+	if err != nil {
+		log.Fatal().Err(err).Msg("Failed to initialize OpenTelemetry")
+	}
+	defer otelShutdown(context.Background())
+	
+	db, err := postgres.NewDB(cfg.Database.URI)
+	if err != nil {
+		log.Fatal().Err(err).Msg("Failed to connect to database")
+	}
+	defer db.Close()
+
+<% if (websockets) { %>
+	// Initialize WebSocket Hub
+	wsHub := websocket.NewHub(cfg)
+	go wsHub.Run()
+
+	// Composition root: wire adapters into services
+	router, err := buildApp(cfg, db, wsHub)
+<% } else { %>
+	// Composition root: wire adapters into services
+	router, err := buildApp(cfg, db)
+<% } %>
+	if err != nil {
+		log.Fatal().Err(err).Msg("Failed to build application")
+	}
+
+	srv := &http.Server{
+		Addr:         fmt.Sprintf(":%d", cfg.Server.Port),
+		Handler:      router,
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 0,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	go func() {
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			log.Fatal().Err(err).Msg("Server failed to start")
+		}
+	}()
+
+	log.Info().Int("port", cfg.Server.Port).Msg("Service ready")
+
+<% if (websockets) { %>
+	gracefulShutdown(srv, wsHub)
+<% } else { %>
+	gracefulShutdown(srv)
+<% } %>
+}
+
+// buildApp wires all repositories, external clients, and services together,
+// returning the fully configured HTTP handler. This enforces explicit dependency injection.
+<% if (websockets) { %>
+func buildApp(cfg *config.Config, db *postgres.DB, wsHub *websocket.Hub) (http.Handler, error) {
+<% } else { %>
+func buildApp(cfg *config.Config, db *postgres.DB) (http.Handler, error) {
+<% } %>
+	// --- Adapters ---
+
+	txManager := postgres.NewTransactionManager(db)
+	entityRepo := postgres.NewRepository(db)
+<% if (messaging !== 'none') { %>
+	outboxRepo := postgres.NewOutboxRepository(db)
+<% } %>
+
+	// --- Services (Use Cases) ---
+	
+<% if (websockets) { %>
+	appSvc := service.NewAppService(txManager, entityRepo, wsHub<% if (messaging !== 'none') { %>, outboxRepo<% } %>)
+<% } else { %>
+	appSvc := service.NewAppService(txManager, entityRepo, nil<% if (messaging !== 'none') { %>, outboxRepo<% } %>)
+<% } %>
+
+<% if (auth === 'clerk') { %>
+	userRepo := postgres.NewUserRepository(db)
+	userSvc := service.NewUserService(userRepo)
+<% } %>
+
+	// --- Router ---
+<% if (websockets) { %>
+	router := api.RegisterRoutes(cfg, db.DB, appSvc<% if (auth === 'clerk') { %>, userSvc<% } %>, wsHub)
+<% } else { %>
+	router := api.RegisterRoutes(cfg, db.DB, appSvc<% if (auth === 'clerk') { %>, userSvc<% } %>)
+<% } %>
+
+	return router, nil
+}
+
+func setupLogger() {
+	zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
+	log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})
+}
+
+<% if (websockets) { %>
+func gracefulShutdown(srv *http.Server, wsHub *websocket.Hub) {
+<% } else { %>
+func gracefulShutdown(srv *http.Server) {
+<% } %>
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+	<-quit
+
+	log.Info().Msg("Shutting down server...")
+
+<% if (websockets) { %>
+	log.Info().Msg("Stopping WebSocket Hub...")
+	wsHub.Stop()
+<% } %>
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	if err := srv.Shutdown(ctx); err != nil {
+		log.Fatal().Err(err).Msg("Server forced to shutdown")
+	}
+
+	log.Info().Msg("Server exited properly")
+}

package/src/generators/go-microservice/files/cmd/api/main_test.go.template

@@ -0,0 +1,99 @@
+package main
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+	"path/filepath"
+
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/modules/postgres"
+	"github.com/testcontainers/testcontainers-go/wait"
+
+	"<%= name %>/internal/config"
+	pg "<%= name %>/internal/postgres"
+<% if (websockets) { %>
+	"<%= name %>/internal/websocket"
+<% } %>
+)
+
+func TestAPIIntegration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	// 1. Start Postgres Container
+	pgContainer, err := postgres.RunContainer(ctx,
+		testcontainers.WithImage("postgres:16-alpine"),
+		postgres.WithDatabase("<%= name %>_test"),
+		postgres.WithUsername("testuser"),
+		postgres.WithPassword("testpass"),
+		testcontainers.WithWaitStrategy(
+			wait.ForLog("database system is ready to accept connections").
+				WithOccurrence(2).WithStartupTimeout(5*time.Second)),
+	)
+	require.NoError(t, err)
+	defer func() {
+		if err := pgContainer.Terminate(context.Background()); err != nil {
+			t.Fatalf("failed to terminate container: %s", err)
+		}
+	}()
+
+	connStr, err := pgContainer.ConnectionString(ctx, "sslmode=disable")
+	require.NoError(t, err)
+
+	// 2. Set Env variables for Config
+	os.Setenv("DATABASE_URL", connStr)
+	os.Setenv("PORT", "8080")
+	// Dummy OTEL endpoint to prevent failure on startup
+	os.Setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "localhost:4317")
+
+	cfg := config.Load()
+
+	// 3. Apply Schema
+	// In a real integration test, we use the schema diff tool or just execute the SQL
+	// Assuming db/schema.sql is available at the project root relative to cmd/api
+	schemaPath := filepath.Join("..", "..", "db", "schema.sql")
+	schemaBytes, err := os.ReadFile(schemaPath)
+	require.NoError(t, err, "failed to read schema.sql from %s", schemaPath)
+
+	db, err := pg.NewDB(cfg.Database.URI)
+	require.NoError(t, err)
+	defer db.Close()
+
+	_, err = db.DB.ExecContext(ctx, string(schemaBytes))
+	require.NoError(t, err, "failed to apply schema")
+
+<% if (websockets) { %>
+	// 4. Initialize WebSocket Hub
+	wsHub := websocket.NewHub(cfg)
+	go wsHub.Run()
+	defer wsHub.Stop()
+
+	// 5. Build the App
+	router, err := buildApp(cfg, db, wsHub)
+<% } else { %>
+	// 5. Build the App
+	router, err := buildApp(cfg, db)
+<% } %>
+	require.NoError(t, err)
+
+	// 6. Test the /health endpoint
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	req = req.WithContext(ctx)
+
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	require.Equal(t, http.StatusOK, rr.Code)
+
+	// The health check response should have status ok since db and hub are healthy
+	require.Contains(t, rr.Body.String(), `"status":"ok"`)
+}

package/src/generators/go-microservice/files/cmd/worker/cleanup/main.go.template

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"os"
+
+	_ "github.com/lib/pq"
+	"github.com/rs/zerolog/log"
+)
+
+func main() {
+	dbURL := os.Getenv("DATABASE_URL")
+	if dbURL == "" {
+		log.Fatal().Msg("DATABASE_URL environment variable is required")
+	}
+
+	db, err := sql.Open("postgres", dbURL)
+	if err != nil {
+		log.Fatal().Err(err).Msg("Failed to connect to database")
+	}
+	defer db.Close()
+
+	if err := db.Ping(); err != nil {
+		log.Fatal().Err(err).Msg("Failed to ping database")
+	}
+
+	log.Info().Msg("Starting idempotency key cleanup worker...")
+
+	// Delete keys older than 24 hours
+	query := `DELETE FROM idempotency_keys WHERE created_at < NOW() - INTERVAL '24 hours'`
+	res, err := db.ExecContext(context.Background(), query)
+	if err != nil {
+		log.Fatal().Err(err).Msg("Failed to execute cleanup query")
+	}
+
+	rowsAffected, _ := res.RowsAffected()
+	log.Info().Int64("deleted_keys", rowsAffected).Msg("Cleanup complete")
+}