ga-plugins-cli 0.1.0 → 0.1.1

package/plugins/go-scaffolder/commands/scaffold-service.md

@@ -0,0 +1,802 @@
+# Command: scaffold-service
+
+Generate a complete, production-ready thin Go microservice wired to go-ga-lib. The wizard asks exactly what dependencies the service needs and imports ONLY those packages — no unused imports, no dead code.
+
+---
+
+## Step 1: Interactive Wizard
+
+Ask ALL questions in order before writing any files. Collect all answers first, then generate everything at once.
+
+### Q1 — Service name
+
+Ask:
+
+> "Domain / service name? (e.g. booking, payment, notification)"
+
+Record as `<service-name>`. This becomes:
+- The output folder name: `<service-name>-service/`
+- Part of the default module path: `github.com/zokypesch/<service-name>-service`
+- Package names throughout the code
+
+### Q2 — Service type
+
+Ask:
+
+> "Service type?
+> (1) API server — HTTP only, no message consumption
+> (2) Message consumer — consumes messages, no HTTP API (worker process)
+> (3) Both — HTTP API + message consumption"
+
+Record as `<service-type>`. Values: `api`, `consumer`, `both`.
+
+### Q3 — SQL database
+
+Ask:
+
+> "SQL database?
+> (1) MySQL 8.4
+> (2) PostgreSQL 18.4
+> (3) None"
+
+Record as `<sql-choice>`. Values: `mysql`, `postgres`, `none`.
+
+### Q4 — NoSQL stores
+
+Ask:
+
+> "NoSQL store(s)? Select all that apply (comma-separated numbers, e.g. 1,3):
+> (1) Redis
+> (2) Elasticsearch
+> (3) MongoDB
+> (4) Cassandra
+> (5) ClickHouse
+> (6) pgvector
+> (7) Neo4j
+> (8) None"
+
+Record as `<nosql-choices>` (a list). If the user picks 8 or leaves blank, set to empty list.
+
+### Q5 — Message broker (only if `<service-type>` is `consumer` or `both`)
+
+If `<service-type>` is `api`, skip this question and set `<broker>` to `none`.
+
+Otherwise ask:
+
+> "Message broker?
+> (1) Kafka
+> (2) RabbitMQ
+> (3) ActiveMQ
+> (4) NSQ"
+
+Record as `<broker>`. Values: `kafka`, `rabbitmq`, `activemq`, `nsq`.
+
+### Q6 — HTTP port
+
+Ask:
+
+> "HTTP port? (press Enter for default: 8080)"
+
+Record as `<http-port>`. Default: `8080`. Only used if `<service-type>` is `api` or `both`.
+
+### Q7 — Go module path
+
+Ask:
+
+> "Go module path for this service? (press Enter for default: github.com/zokypesch/<service-name>-service)"
+
+Record as `<module-path>`. Default: `github.com/zokypesch/<service-name>-service`.
+
+### Q8 — go-ga-lib version
+
+Ask:
+
+> "go-ga-lib version to pin?
+> Enter a git tag (e.g. v1.0.0) for a production service.
+> Enter 'local' to use a replace directive pointing to the local go-ga-lib clone (D:/project/asyst/go-ga-lib).
+> (default: local)"
+
+Record as `<ga-lib-version>`. Default: `local`.
+
+---
+
+## Step 2: Confirm Before Generating
+
+Print a confirmation summary:
+
+```
+Generating <service-name>-service with:
+  Module:       <module-path>
+  Type:         <service-type>
+  SQL:          <sql-choice>
+  NoSQL:        <nosql-choices or "none">
+  Broker:       <broker or "n/a">
+  Port:         <http-port or "n/a (consumer only)">
+  go-ga-lib:    <ga-lib-version>
+  Output dir:   <service-name>-service/
+
+Proceed? (Y/n)
+```
+
+If the user says n or no, restart from Q1.
+
+---
+
+## Step 3: Generate Files
+
+Generate ALL files listed below. Apply the DEPENDENCY RULES table strictly — if a dependency was not chosen, its import does NOT appear anywhere in the generated code.
+
+### DEPENDENCY RULES TABLE
+
+| Dependency | Chosen when | go-ga-lib subpackage to import | Env vars generated |
+|---|---|---|---|
+| PostgreSQL | `<sql-choice>` == `postgres` | `github.com/zokypesch/go-ga-lib/sql` | DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME, DB_SSLMODE |
+| MySQL | `<sql-choice>` == `mysql` | `github.com/zokypesch/go-ga-lib/sql/mysql` | DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME |
+| Redis | `nosql-choices` contains `1` | `github.com/zokypesch/go-ga-lib/nosql/redis` | REDIS_ADDR, REDIS_PASSWORD, REDIS_DB |
+| Elasticsearch | `nosql-choices` contains `2` | `github.com/zokypesch/go-ga-lib/nosql/elasticsearch` | ES_ADDRS, ES_USERNAME, ES_PASSWORD |
+| MongoDB | `nosql-choices` contains `3` | `github.com/zokypesch/go-ga-lib/nosql/mongo` | MONGO_URI, MONGO_DATABASE |
+| Cassandra | `nosql-choices` contains `4` | `github.com/zokypesch/go-ga-lib/nosql/cassandra` | CASSANDRA_HOSTS, CASSANDRA_KEYSPACE |
+| ClickHouse | `nosql-choices` contains `5` | `github.com/zokypesch/go-ga-lib/nosql/clickhouse` | CLICKHOUSE_ADDR, CLICKHOUSE_DATABASE |
+| pgvector | `nosql-choices` contains `6` | `github.com/zokypesch/go-ga-lib/nosql/pgvector` | PGVECTOR_HOST, PGVECTOR_PORT, PGVECTOR_USER, PGVECTOR_PASS, PGVECTOR_NAME |
+| Neo4j | `nosql-choices` contains `7` | `github.com/zokypesch/go-ga-lib/nosql/neo4j` | NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD |
+| Kafka | `<broker>` == `kafka` | `github.com/zokypesch/go-ga-lib/broker/kafka` | KAFKA_BROKERS, KAFKA_GROUP_ID, KAFKA_TOPIC |
+| RabbitMQ | `<broker>` == `rabbitmq` | `github.com/zokypesch/go-ga-lib/broker/rabbitmq` | RABBITMQ_URL, RABBITMQ_QUEUE |
+| ActiveMQ | `<broker>` == `activemq` | `github.com/zokypesch/go-ga-lib/broker/activemq` | ACTIVEMQ_URL, ACTIVEMQ_QUEUE |
+| NSQ | `<broker>` == `nsq` | `github.com/zokypesch/go-ga-lib/broker/nsq` | NSQ_ADDR, NSQ_TOPIC, NSQ_CHANNEL |
+
+Always import regardless of choices:
+- `github.com/zokypesch/go-ga-lib/config` — config loading
+- `github.com/zokypesch/go-ga-lib/observability` — OTel tracing + Prometheus + Loki
+- `github.com/zokypesch/go-ga-lib/logger` — structured zap logger
+
+Import only if `<service-type>` is `api` or `both`:
+- `github.com/zokypesch/go-ga-lib/httpx` — chi router factory + JSON/error helpers
+- `github.com/zokypesch/go-ga-lib/server` — HTTP server with graceful shutdown
+
+---
+
+### File: `<service-name>-service/go.mod`
+
+```
+module <module-path>
+
+go 1.23
+
+require (
+	github.com/go-chi/chi/v5 v5.2.1
+	github.com/zokypesch/go-ga-lib <version-line>
+	go.uber.org/zap v1.27.0
+	github.com/google/uuid v1.6.0
+	github.com/jmoiron/sqlx v1.4.0
+	github.com/stretchr/testify v1.9.0
+	github.com/caarlos0/env/v11 v11.3.1
+)
+```
+
+`<version-line>` rules:
+- If `<ga-lib-version>` == `local`: write `v0.0.0` AND add the replace directive below the require block:
+  ```
+  replace github.com/zokypesch/go-ga-lib => D:/project/asyst/go-ga-lib
+  ```
+- If `<ga-lib-version>` is a tag (e.g. `v1.0.0`): write that tag as the version, NO replace directive.
+
+Only include driver dependencies that match chosen dependencies:
+- postgres: add `github.com/lib/pq v1.10.9`
+- mysql: add `github.com/go-sql-driver/mysql v1.8.1`
+- mongo: add `go.mongodb.org/mongo-driver v1.15.0`
+- redis: add `github.com/redis/go-redis/v9 v9.5.1`
+- kafka: add `github.com/IBM/sarama v1.43.2`
+- rabbitmq: add `github.com/rabbitmq/amqp091-go v1.10.0`
+- nsq: add `github.com/nsqio/go-nsq v1.1.0`
+
+---
+
+### File: `<service-name>-service/config/config.go`
+
+```go
+package config
+
+import (
+	"fmt"
+	"github.com/caarlos0/env/v11"
+)
+
+// Config holds all configuration for the <service-name> service.
+// All values come from environment variables — no config files at runtime.
+type Config struct {
+	// Application
+	Port            int    `env:"PORT"             envDefault:"<http-port>"`
+	LogLevel        string `env:"LOG_LEVEL"        envDefault:"info"`
+	ServiceName     string `env:"SERVICE_NAME"     envDefault:"<service-name>-service"`
+	ServiceVersion  string `env:"SERVICE_VERSION"  envDefault:"0.1.0"`
+	ShutdownTimeout int    `env:"SHUTDOWN_TIMEOUT" envDefault:"10"` // seconds
+
+	// OpenTelemetry
+	OTLPEndpoint string `env:"OTLP_ENDPOINT" envDefault:"localhost:4317"`
+
+	// [ONLY include the blocks below that match chosen dependencies]
+	// PostgreSQL block — only if sql-choice == postgres
+	DBHost    string `env:"DB_HOST"    required:"true"`
+	DBPort    string `env:"DB_PORT"    envDefault:"5432"`
+	DBUser    string `env:"DB_USER"    required:"true"`
+	DBPass    string `env:"DB_PASS"    required:"true"`
+	DBName    string `env:"DB_NAME"    required:"true"`
+	DBSSLMode string `env:"DB_SSLMODE" envDefault:"disable"`
+
+	// Redis block — only if Redis chosen
+	RedisAddr     string `env:"REDIS_ADDR"     envDefault:"localhost:6379"`
+	RedisPassword string `env:"REDIS_PASSWORD" envDefault:""`
+	RedisDB       int    `env:"REDIS_DB"       envDefault:"0"`
+
+	// [Continue pattern for each chosen dependency per DEPENDENCY RULES TABLE]
+}
+
+// Load parses environment variables into Config.
+// Returns an error if any required variable is missing or invalid.
+func Load() (*Config, error) {
+	cfg := &Config{}
+	if err := env.Parse(cfg); err != nil {
+		return nil, fmt.Errorf("loading config: %w", err)
+	}
+	return cfg, nil
+}
+
+// DSN builds the PostgreSQL connection string. [Only include if postgres chosen]
+// Never log the output of this method.
+func (c *Config) DSN() string {
+	return fmt.Sprintf(
+		"host=%s port=%s dbname=%s user=%s password=%s sslmode=%s",
+		c.DBHost, c.DBPort, c.DBName, c.DBUser, c.DBPass, c.DBSSLMode,
+	)
+}
+
+// String returns a safe representation with secrets redacted.
+func (c *Config) String() string {
+	return fmt.Sprintf(
+		"Config{Port:%d ServiceName:%s ServiceVersion:%s LogLevel:%s}",
+		c.Port, c.ServiceName, c.ServiceVersion, c.LogLevel,
+	)
+}
+```
+
+RULE: Only generate config fields for chosen dependencies. If SQL is None, no DB_ fields. If no NoSQL chosen, no NoSQL fields. If no broker, no broker fields.
+
+---
+
+### File: `<service-name>-service/internal/domain/<service-name>.go`
+
+Generate the domain layer:
+
+```go
+package domain
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// Sentinel errors — map these to HTTP status codes in the handler layer.
+var (
+	ErrNotFound      = errors.New("<service-name> not found")
+	ErrAlreadyExists = errors.New("<service-name> already exists")
+	ErrInvalidInput  = errors.New("invalid input")
+	ErrUnauthorized  = errors.New("unauthorized")
+	ErrForbidden     = errors.New("forbidden")
+)
+
+// <ServiceName> is the core domain entity.
+type <ServiceName> struct {
+	ID        string    `db:"id"         json:"id"`
+	// Add 3-5 realistic fields for the domain (e.g. for booking: CustomerID, FlightID, Status)
+	CreatedAt time.Time `db:"created_at" json:"created_at"`
+	UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
+}
+
+// <ServiceName>Repository defines the data access contract.
+type <ServiceName>Repository interface {
+	Create(ctx context.Context, entity *<ServiceName>) error
+	GetByID(ctx context.Context, id string) (*<ServiceName>, error)
+	Update(ctx context.Context, entity *<ServiceName>) error
+	List(ctx context.Context, limit, offset int) ([]*<ServiceName>, error)
+	Delete(ctx context.Context, id string) error
+}
+
+// <ServiceName>Usecase defines the business logic contract.
+type <ServiceName>Usecase interface {
+	Create(ctx context.Context, input Create<ServiceName>Input) (*<ServiceName>, error)
+	GetByID(ctx context.Context, id string) (*<ServiceName>, error)
+	Update(ctx context.Context, id string, input Update<ServiceName>Input) (*<ServiceName>, error)
+	List(ctx context.Context, limit, offset int) ([]*<ServiceName>, error)
+	Delete(ctx context.Context, id string) error
+}
+
+// Create<ServiceName>Input is the payload for creating a new entity.
+type Create<ServiceName>Input struct {
+	// Fields derived from <service-name> domain
+}
+
+// Update<ServiceName>Input is the payload for updating an existing entity.
+type Update<ServiceName>Input struct {
+	// Fields derived from <service-name> domain (all optional via pointers)
+}
+```
+
+---
+
+### File: `<service-name>-service/internal/repository/<service-name>_<sql-engine>.go`
+
+[Only generate if `<sql-choice>` != `none`]
+
+```go
+package repository
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/jmoiron/sqlx"
+	"<module-path>/internal/domain"
+)
+
+type <sqlEngine><ServiceName>Repo struct {
+	db *sqlx.DB
+}
+
+func New<SQLEngine><ServiceName>Repo(db *sqlx.DB) domain.<ServiceName>Repository {
+	return &<sqlEngine><ServiceName>Repo{db: db}
+}
+
+func (r *<sqlEngine><ServiceName>Repo) Create(ctx context.Context, entity *domain.<ServiceName>) error {
+	query := `INSERT INTO <service-name>s (id, ..., created_at, updated_at)
+	          VALUES (:id, ..., :created_at, :updated_at)`
+	_, err := r.db.NamedExecContext(ctx, query, entity)
+	if err != nil {
+		return fmt.Errorf("repository.Create: %w", err)
+	}
+	return nil
+}
+
+func (r *<sqlEngine><ServiceName>Repo) GetByID(ctx context.Context, id string) (*domain.<ServiceName>, error) {
+	entity := &domain.<ServiceName>{}
+	err := r.db.GetContext(ctx, entity, `SELECT * FROM <service-name>s WHERE id = $1`, id)
+	if err != nil {
+		if err == sql.ErrNoRows {
+			return nil, domain.ErrNotFound
+		}
+		return nil, fmt.Errorf("repository.GetByID: %w", err)
+	}
+	return entity, nil
+}
+
+// [Implement Update, List, Delete following the same pattern]
+```
+
+If `<sql-choice>` is `mysql`, use `?` placeholders. If `postgres`, use `$1`, `$2`, etc.
+
+---
+
+### File: `<service-name>-service/internal/usecase/<service-name>.go`
+
+```go
+package usecase
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+
+	"<module-path>/internal/domain"
+)
+
+type <service-name>Usecase struct {
+	repo   domain.<ServiceName>Repository
+	logger *zap.Logger
+}
+
+func New<ServiceName>Usecase(repo domain.<ServiceName>Repository, logger *zap.Logger) domain.<ServiceName>Usecase {
+	return &<service-name>Usecase{repo: repo, logger: logger}
+}
+
+func (uc *<service-name>Usecase) Create(ctx context.Context, input domain.Create<ServiceName>Input) (*domain.<ServiceName>, error) {
+	// Validate input
+	// [add real validation here]
+
+	entity := &domain.<ServiceName>{
+		ID:        uuid.NewString(),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+		// map input fields
+	}
+
+	if err := uc.repo.Create(ctx, entity); err != nil {
+		return nil, fmt.Errorf("usecase.Create: %w", err)
+	}
+
+	uc.logger.Info("created <service-name>", zap.String("id", entity.ID))
+	return entity, nil
+}
+
+// [Implement GetByID, Update, List, Delete with proper error wrapping and logging]
+```
+
+---
+
+### File: `<service-name>-service/internal/handler/<service-name>.go`
+
+[Only generate if `<service-type>` is `api` or `both`]
+
+```go
+package handler
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+	"go.uber.org/zap"
+
+	"<module-path>/internal/domain"
+)
+
+const maxBodyBytes = 1 << 20 // 1 MB
+
+type <ServiceName>Handler struct {
+	uc     domain.<ServiceName>Usecase
+	logger *zap.Logger
+}
+
+func New<ServiceName>Handler(uc domain.<ServiceName>Usecase, logger *zap.Logger) *<ServiceName>Handler {
+	return &<ServiceName>Handler{uc: uc, logger: logger}
+}
+
+// Routes mounts all <service-name> routes on the provided chi.Router.
+func (h *<ServiceName>Handler) Routes(r chi.Router) {
+	r.Get("/",       h.List)
+	r.Post("/",      h.Create)
+	r.Get("/{id}",   h.GetByID)
+	r.Put("/{id}",   h.Update)
+	r.Delete("/{id}", h.Delete)
+}
+
+func (h *<ServiceName>Handler) Create(w http.ResponseWriter, r *http.Request) {
+	var input domain.Create<ServiceName>Input
+	if err := decodeJSON(r, &input); err != nil {
+		respondErrorStatus(w, http.StatusBadRequest, err.Error(), "BAD_REQUEST")
+		return
+	}
+	result, err := h.uc.Create(r.Context(), input)
+	if err != nil {
+		h.logger.Error("create <service-name>", zap.Error(err),
+			zap.String("request_id", middleware.GetReqID(r.Context())))
+		respondError(w, err)
+		return
+	}
+	respondJSON(w, http.StatusCreated, result)
+}
+
+// [Implement GetByID, Update, List, Delete following the same thin-handler pattern]
+
+// --- helpers ---
+
+func decodeJSON(r *http.Request, dst any) error {
+	r.Body = http.MaxBytesReader(w, r.Body, maxBodyBytes)
+	dec := json.NewDecoder(r.Body)
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(dst); err != nil {
+		if errors.Is(err, io.EOF) {
+			return errors.New("request body must not be empty")
+		}
+		return fmt.Errorf("decoding request: %w", err)
+	}
+	return nil
+}
+
+type errorBody struct {
+	Error string `json:"error"`
+	Code  string `json:"code"`
+}
+
+func respondJSON(w http.ResponseWriter, status int, data any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if data != nil {
+		_ = json.NewEncoder(w).Encode(data)
+	}
+}
+
+func respondError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, domain.ErrNotFound):
+		respondErrorStatus(w, http.StatusNotFound, err.Error(), "NOT_FOUND")
+	case errors.Is(err, domain.ErrAlreadyExists):
+		respondErrorStatus(w, http.StatusConflict, err.Error(), "CONFLICT")
+	case errors.Is(err, domain.ErrInvalidInput):
+		respondErrorStatus(w, http.StatusBadRequest, err.Error(), "BAD_REQUEST")
+	case errors.Is(err, domain.ErrUnauthorized):
+		respondErrorStatus(w, http.StatusUnauthorized, err.Error(), "UNAUTHORIZED")
+	case errors.Is(err, domain.ErrForbidden):
+		respondErrorStatus(w, http.StatusForbidden, err.Error(), "FORBIDDEN")
+	default:
+		respondErrorStatus(w, http.StatusInternalServerError, "internal server error", "INTERNAL")
+	}
+}
+
+func respondErrorStatus(w http.ResponseWriter, status int, message, code string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(errorBody{Error: message, Code: code})
+}
+```
+
+---
+
+### File: `<service-name>-service/internal/consumer/<service-name>_consumer.go`
+
+[Only generate if `<service-type>` is `consumer` or `both`]
+
+Generate a consumer struct that:
+- Imports ONLY the chosen broker subpackage from go-ga-lib
+- Has a `Start(ctx context.Context) error` method
+- Has a `processMessage(ctx context.Context, msg []byte) error` method with example logic
+- Stops cleanly when the context is cancelled
+
+---
+
+### File: `<service-name>-service/cmd/server/main.go`
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+	"go.uber.org/zap"
+
+	"<module-path>/config"
+	"<module-path>/internal/domain"
+	"<module-path>/internal/handler"     // [only if api or both]
+	"<module-path>/internal/repository"  // [only if sql != none]
+	"<module-path>/internal/usecase"
+	// [Add chosen go-ga-lib subpackage imports per DEPENDENCY RULES TABLE]
+)
+
+func main() {
+	// 1. Load config — fail fast if required vars are missing
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("loading config: %v", err)
+	}
+
+	// 2. Initialize logger
+	// [call go-ga-lib/logger.New with cfg.LogLevel, cfg.ServiceName, cfg.ServiceVersion]
+
+	// 3. Initialize observability (OTel tracing + Prometheus + Loki)
+	// [call go-ga-lib/observability.Init with cfg.OTLPEndpoint, cfg.ServiceName, cfg.ServiceVersion]
+	// defer shutdown
+
+	// 4. Initialize chosen dependencies (only include blocks for chosen deps):
+
+	// [SQL block — only if sql != none]
+	// db, err := <go-ga-lib/sql>.Open(cfg.DSN())
+	// if err != nil { logger.Fatal("opening db", zap.Error(err)) }
+	// defer db.Close()
+
+	// [Redis block — only if Redis chosen]
+	// rdb := <go-ga-lib/nosql/redis>.NewClient(...)
+	// defer rdb.Close()
+
+	// [Broker block — only if consumer or both]
+	// brokerClient := <go-ga-lib/broker/<broker>>.NewClient(...)
+	// defer brokerClient.Close()
+
+	// 5. Wire layers
+	// repo := repository.New<SQLEngine><ServiceName>Repo(db)   // [only if sql != none]
+	// uc   := usecase.New<ServiceName>Usecase(repo, logger)
+
+	// 6. Start consumer (only if consumer or both)
+	// consumer := consumer.New<ServiceName>Consumer(brokerClient, uc, logger)
+	// go consumer.Start(ctx)
+
+	// 7. Start HTTP server (only if api or both)
+	r := chi.NewRouter()
+	r.Use(middleware.RequestID)
+	r.Use(middleware.RealIP)
+	r.Use(middleware.Recoverer)
+
+	r.Get("/health", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"status":"ok"}`)
+	})
+	r.Get("/ready", func(w http.ResponseWriter, r *http.Request) {
+		// [ping each dependency; return 503 if any fail]
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"status":"ready"}`)
+	})
+
+	r.Route("/api/v1", func(r chi.Router) {
+		<service-name>Handler := handler.New<ServiceName>Handler(uc, logger)
+		r.Route("/<service-name>s", func(r chi.Router) {
+			<service-name>Handler.Routes(r)
+		})
+	})
+
+	srv := &http.Server{
+		Addr:    fmt.Sprintf(":%d", cfg.Port),
+		Handler: r,
+	}
+
+	// 8. Graceful shutdown
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+	go func() {
+		logger.Info("server starting", zap.Int("port", cfg.Port))
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			logger.Fatal("server failed", zap.Error(err))
+		}
+	}()
+
+	<-quit
+	logger.Info("shutting down")
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(),
+		time.Duration(cfg.ShutdownTimeout)*time.Second)
+	defer cancel()
+
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		logger.Error("shutdown error", zap.Error(err))
+	}
+
+	// [close each initialized dependency in reverse init order]
+	logger.Info("server stopped")
+}
+```
+
+---
+
+### File: `<service-name>-service/Dockerfile`
+
+Multi-stage Dockerfile. Stage 1 builds, stage 2 is distroless minimal runtime.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
+# ---- Stage 1: Build ----
+FROM golang:1.23-alpine AS builder
+
+RUN apk add --no-cache git ca-certificates tzdata
+
+WORKDIR /app
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+    go build -trimpath -ldflags="-s -w" \
+    -o /app/server ./cmd/server
+
+# ---- Stage 2: Runtime ----
+FROM gcr.io/distroless/static:nonroot
+
+COPY --from=builder /app/server /server
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
+
+USER nonroot:nonroot
+
+EXPOSE <http-port>
+
+ENTRYPOINT ["/server"]
+```
+
+---
+
+### File: `<service-name>-service/.env.example`
+
+Generate only the env vars relevant to chosen dependencies. Always include the core app/OTel block.
+
+```bash
+# Copy to .env for local development. Never commit .env.
+
+# --- Application ---
+PORT=<http-port>
+LOG_LEVEL=info               # debug | info | warn | error
+SERVICE_NAME=<service-name>-service
+SERVICE_VERSION=0.1.0
+SHUTDOWN_TIMEOUT=10          # seconds to wait for in-flight requests on SIGTERM
+
+# --- OpenTelemetry (Grafana Tempo) ---
+OTLP_ENDPOINT=localhost:4317
+
+# [Only include sections below for chosen dependencies]
+
+# --- PostgreSQL ---
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=<service-name>_user
+DB_PASS=changeme
+DB_NAME=<service-name>_db
+DB_SSLMODE=disable           # use 'require' in production
+
+# --- Redis ---
+REDIS_ADDR=localhost:6379
+REDIS_PASSWORD=              # leave empty for no-auth local dev
+REDIS_DB=0
+
+# [Continue pattern for each chosen dependency]
+```
+
+---
+
+## Step 4: Post-generation Summary
+
+After writing all files, print:
+
+```
+Generated: <service-name>-service/
+
+  go.mod                                   (module <module-path>)
+  config/config.go                         (env config)
+  internal/domain/<service-name>.go        (interfaces + structs)
+  internal/repository/<service-name>_<db>.go  (if sql chosen)
+  internal/usecase/<service-name>.go       (business logic)
+  internal/handler/<service-name>.go       (HTTP handlers, if api or both)
+  internal/consumer/<service-name>_consumer.go  (if consumer or both)
+  cmd/server/main.go                       (entry point)
+  Dockerfile
+  .env.example
+
+Dependencies wired:
+  SQL:    <sql-choice>
+  NoSQL:  <nosql-choices or "none">
+  Broker: <broker or "n/a">
+
+Next steps:
+  1. Copy .env.example to .env and fill in real values
+  2. Run: go mod tidy
+  3. Run: go build ./...
+  4. See reference-service/ for a complete working exemplar
+
+NOTE: If you used 'local' for go-ga-lib, the go.mod contains a replace directive.
+Switch to a pinned version before committing to the shared repository:
+  1. Remove the replace directive
+  2. Set: require github.com/zokypesch/go-ga-lib v<tag>
+```
+
+---
+
+## Constraints (strictly enforced)
+
+- NEVER import a go-ga-lib subpackage that was not chosen.
+- NEVER add a Config field for an env var that was not chosen.
+- NEVER add a `.env.example` line for an unchosen dependency.
+- NEVER generate a consumer file if `<service-type>` is `api`.
+- NEVER generate an HTTP handler if `<service-type>` is `consumer`.
+- The `replace` directive only appears in `go.mod` when `<ga-lib-version>` == `local`. Production services MUST NOT have a replace directive.
+- All generated Go files must compile (no placeholder syntax errors, no missing imports).
+- Use `context.Context` as the first argument of every repository and usecase method.
+- All repository methods must map `sql.ErrNoRows` to `domain.ErrNotFound`.
+- All usecase methods must wrap errors with `fmt.Errorf("usecase.Method: %w", err)`.
+- Dockerfile stage 2 must use `gcr.io/distroless/static:nonroot` — never `alpine` or `ubuntu` in the runtime stage.