ga-plugins-cli 0.1.0 → 0.1.2

package/plugins/go-scaffolder/reference-service/.env.example

@@ -0,0 +1,27 @@
+# .env.example — booking-service
+# Copy to .env for local development. Never commit .env.
+# All variables are read once at startup; the process exits with a clear error
+# message if a required variable is absent.
+
+# --- Application ---
+PORT=8080                          # HTTP listener port
+LOG_LEVEL=info                     # debug | info | warn | error
+SERVICE_NAME=booking-service       # used as Prometheus/Loki/Tempo service label
+SERVICE_VERSION=0.1.0              # reported in traces and metrics
+SHUTDOWN_TIMEOUT=10                # seconds to wait for in-flight requests on SIGTERM
+
+# --- OpenTelemetry (Grafana Tempo — gRPC endpoint) ---
+OTLP_ENDPOINT=localhost:4317       # Tempo / OTel Collector gRPC address (no scheme)
+
+# --- PostgreSQL ---
+DB_HOST=localhost                  # required — PostgreSQL 18.4 host
+DB_PORT=5432
+DB_USER=booking_user               # required — DB role for this service
+DB_PASS=changeme                   # required — use a strong random value in production
+DB_NAME=booking_db                 # required — dedicated database for this service
+DB_SSLMODE=disable                 # local dev: disable | production: require
+
+# --- Redis ---
+REDIS_ADDR=localhost:6379          # Redis 7+ address (host:port)
+REDIS_PASSWORD=                    # leave empty for no-auth local dev
+REDIS_DB=0                         # Redis logical database index (0–15)

package/plugins/go-scaffolder/reference-service/Dockerfile

@@ -0,0 +1,55 @@
+# syntax=docker/dockerfile:1
+# Multi-stage build for booking-service.
+# Stage 1 (builder): compiles a fully-static binary.
+# Stage 2 (runtime): distroless/static — no shell, no package manager, minimal attack surface.
+
+# ============================================================
+# Stage 1 — Build
+# ============================================================
+FROM golang:1.23-alpine AS builder
+
+# Install system-level build dependencies.
+RUN apk add --no-cache git ca-certificates tzdata
+
+WORKDIR /app
+
+# Layer caching: download modules before copying source.
+# This layer is only invalidated when go.mod or go.sum change.
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source and build.
+# CGO_ENABLED=0  — fully static binary, no libc dependency
+# -trimpath       — strip local file paths from the binary
+# -ldflags "-s -w" — strip debug info and DWARF, reduces binary size ~30%
+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 the compiled binary from the builder stage.
+COPY --from=builder /app/server /server
+
+# Copy TLS CA certificates (needed for outbound HTTPS to external services).
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+
+# Copy timezone data (needed if time.LoadLocation is used anywhere in the stack).
+COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
+
+# distroless/static:nonroot already sets USER nonroot (uid 65532).
+# Explicitly restating it makes the intent visible in security scanners.
+USER nonroot:nonroot
+
+# Document the port this service listens on.
+# The actual port is controlled by the PORT env var at runtime.
+EXPOSE 8080
+
+ENTRYPOINT ["/server"]

package/plugins/go-scaffolder/reference-service/REFERENCE-SERVICE-NOTICE.md

@@ -0,0 +1,104 @@
+# Reference Service Notice
+
+## What this is
+
+`reference-service/` is the **canonical exemplar** for all Go services generated by the `go-scaffolder` plugin at Garuda Airlines. It demonstrates every architectural pattern the team has agreed on:
+
+- Clean layered architecture: `domain` → `repository` → `usecase` → `handler`
+- chi router with the standard middleware stack
+- PostgreSQL via sqlx with correct error mapping (`sql.ErrNoRows` → `domain.ErrBookingNotFound`)
+- Redis client with connection pooling and startup ping
+- Graceful shutdown handling `SIGINT` and `SIGTERM`
+- Structured logging (zap) with secrets redacted
+- Table-driven tests with a hand-rolled mock (no code generation dependency)
+- Multi-stage Dockerfile targeting `gcr.io/distroless/static:nonroot`
+- All configuration from environment variables via `caarlos0/env`
+
+---
+
+## WARNING: LOCAL DEV ONLY — replace directive in go.mod
+
+This service's `go.mod` contains:
+
+```
+replace github.com/zokypesch/go-ga-lib => D:/project/asyst/go-ga-lib
+```
+
+**This is a local development override.** It makes Go resolve `go-ga-lib` from the local filesystem instead of the module proxy. This line must **never** appear in a service that is deployed to any shared environment (staging, production, or CI).
+
+---
+
+## How to switch to production mode
+
+1. Remove the `replace` directive from `go.mod`.
+2. Update the `require` line to pin the correct release tag:
+   ```
+   require github.com/zokypesch/go-ga-lib v1.2.3
+   ```
+3. Run `go mod tidy` to fetch the pinned version from the module proxy and update `go.sum`.
+4. Commit both `go.mod` and `go.sum`.
+
+The generated `scaffold-service` command handles this automatically when you answer `v1.x.y` (instead of `local`) to the go-ga-lib version question.
+
+---
+
+## How to tag and publish go-ga-lib
+
+After merging changes to the `go-ga-lib` repository:
+
+```bash
+# From the go-ga-lib repository root:
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+Semantic versioning rules:
+- `v0.x.y` — pre-stable; breaking changes permitted between minor versions
+- `v1.x.y` and beyond — stable API; breaking changes require a major version bump
+- Never delete or reuse a tag that has been consumed by a published service
+
+---
+
+## Review checklist — before using as the canonical exemplar
+
+The team must verify each item below before declaring this reference service valid for the full 30-service generation run.
+
+### Architecture
+- [ ] The `domain` package contains only interfaces, structs, and sentinel errors — no imports of `database/sql`, `net/http`, or any infrastructure package
+- [ ] Handler methods contain no business logic; they decode, call usecase, encode
+- [ ] Usecase methods wrap all repository errors with `fmt.Errorf("usecase.Method: %w", err)`
+- [ ] Repository methods map `sql.ErrNoRows` to `domain.ErrBookingNotFound` (not `domain.ErrNotFound`)
+- [ ] No `os.Getenv` calls outside of `config/config.go`
+
+### Compilation
+- [ ] `go build ./...` passes with no errors
+- [ ] `go vet ./...` passes with no warnings
+- [ ] `go test ./...` passes with no failures
+
+### Test quality
+- [ ] `booking_test.go` verifies HTTP status codes, not just 2xx
+- [ ] The error body `code` field is verified in every error test case
+- [ ] Internal errors do not leak infrastructure details to the response body (covered by `TestBookingHandler_InternalError_HidesDetails`)
+- [ ] No test imports a real database or Redis — mocks only
+
+### Security
+- [ ] `DBPass` and `RedisPassword` are absent from the `Config.String()` output
+- [ ] The `DSN()` method return value is never passed to a logger
+- [ ] `.env` is in `.gitignore` (or a root `.gitignore` covers it)
+- [ ] Dockerfile runtime stage uses `distroless/static:nonroot` (not `alpine`, not `ubuntu`)
+- [ ] `USER nonroot:nonroot` is present in the Dockerfile runtime stage
+
+### Observability hooks
+- [ ] The `OTLP_ENDPOINT` env var is present in `.env.example` with a descriptive comment
+- [ ] The `go-ga-lib/observability.Init(...)` call site is present in `main.go` (even if commented out pending local go-ga-lib availability)
+- [ ] `/health` and `/ready` endpoints are registered outside the `/api/v1` auth group
+
+### Local dev ergonomics
+- [ ] `go mod tidy` succeeds with the `replace` directive active
+- [ ] The service starts successfully after `cp .env.example .env` + filling real local credentials
+- [ ] `/health` returns `{"status":"ok"}` immediately after startup
+- [ ] `/ready` returns `{"status":"ready"}` after both postgres and redis are accepting connections
+
+### go-ga-lib compatibility
+- [ ] Every import path from `go-ga-lib` matches the actual directory structure in `D:/project/asyst/go-ga-lib`
+- [ ] No go-ga-lib subpackage is imported that does not exist in the library (causes build failure for all 30 services)

package/plugins/go-scaffolder/reference-service/cmd/server/main.go

@@ -0,0 +1,266 @@
+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"
+	"github.com/jmoiron/sqlx"
+	_ "github.com/lib/pq" // PostgreSQL driver — imported for side effects only
+	goredis "github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+
+	"github.com/zokypesch/booking-service/config"
+	"github.com/zokypesch/booking-service/internal/handler"
+	"github.com/zokypesch/booking-service/internal/repository"
+	"github.com/zokypesch/booking-service/internal/usecase"
+)
+
+func main() {
+	// -------------------------------------------------------------------------
+	// 1. Config — fail fast before any other initialisation
+	// -------------------------------------------------------------------------
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("FATAL: loading config: %v", err)
+	}
+
+	// -------------------------------------------------------------------------
+	// 2. Logger (zap)
+	// -------------------------------------------------------------------------
+	logger, err := buildLogger(cfg.LogLevel)
+	if err != nil {
+		log.Fatalf("FATAL: building logger: %v", err)
+	}
+	defer func() { _ = logger.Sync() }()
+
+	logger.Info("service starting", zap.String("config", cfg.String()))
+
+	// -------------------------------------------------------------------------
+	// 3. Observability — OpenTelemetry (Grafana Tempo + Prometheus + Loki)
+	//
+	// Replace the block below with the actual go-ga-lib/observability.Init call
+	// once the library is available locally:
+	//
+	//   shutdown, err := observability.Init(ctx, observability.Config{
+	//       OTLPEndpoint:   cfg.OTLPEndpoint,
+	//       ServiceName:    cfg.ServiceName,
+	//       ServiceVersion: cfg.ServiceVersion,
+	//   })
+	//   if err != nil {
+	//       logger.Fatal("initialising observability", zap.Error(err))
+	//   }
+	//   defer shutdown()
+	// -------------------------------------------------------------------------
+	logger.Info("observability: OTel endpoint configured",
+		zap.String("otlp_endpoint", cfg.OTLPEndpoint),
+	)
+
+	// -------------------------------------------------------------------------
+	// 4. PostgreSQL
+	// -------------------------------------------------------------------------
+	db, err := openPostgres(cfg)
+	if err != nil {
+		logger.Fatal("opening postgres", zap.Error(err))
+	}
+	defer func() {
+		if err := db.Close(); err != nil {
+			logger.Error("closing postgres", zap.Error(err))
+		}
+	}()
+	logger.Info("postgres connected", zap.String("db_host", cfg.DBHost), zap.String("db_name", cfg.DBName))
+
+	// -------------------------------------------------------------------------
+	// 5. Redis
+	// -------------------------------------------------------------------------
+	rdb := openRedis(cfg)
+	defer func() {
+		if err := rdb.Close(); err != nil {
+			logger.Error("closing redis", zap.Error(err))
+		}
+	}()
+
+	// Verify Redis is reachable at startup.
+	pingCtx, pingCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer pingCancel()
+	if err := rdb.Ping(pingCtx).Err(); err != nil {
+		logger.Fatal("redis unreachable", zap.Error(err))
+	}
+	logger.Info("redis connected", zap.String("addr", cfg.RedisAddr))
+
+	// -------------------------------------------------------------------------
+	// 6. Wire application layers
+	// -------------------------------------------------------------------------
+	bookingRepo := repository.NewPostgresBookingRepo(db)
+	bookingUC := usecase.NewBookingUsecase(bookingRepo, logger)
+	bookingHandler := handler.NewBookingHandler(bookingUC, logger)
+
+	// -------------------------------------------------------------------------
+	// 7. HTTP router
+	// -------------------------------------------------------------------------
+	r := chi.NewRouter()
+
+	// Global middleware — ORDER MATTERS.
+	r.Use(middleware.RequestID)  // must be first — all other middleware can read request IDs
+	r.Use(middleware.RealIP)
+	r.Use(middleware.Recoverer) // catches panics, returns 500
+	r.Use(middleware.Compress(5))
+
+	// Infrastructure endpoints — outside auth, outside /api/v1
+	r.Get("/health", healthHandler(db))
+	r.Get("/ready", readyHandler(db, rdb))
+	// r.Handle("/metrics", promhttp.Handler()) // uncomment when go-ga-lib/observability wires prometheus
+
+	// Business routes
+	r.Route("/api/v1", func(r chi.Router) {
+		r.Route("/bookings", bookingHandler.Routes)
+	})
+
+	// -------------------------------------------------------------------------
+	// 8. HTTP server with graceful shutdown
+	// -------------------------------------------------------------------------
+	srv := &http.Server{
+		Addr:         fmt.Sprintf(":%d", cfg.Port),
+		Handler:      r,
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 30 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	// Start server in background goroutine.
+	serverErr := make(chan error, 1)
+	go func() {
+		logger.Info("HTTP server listening", zap.Int("port", cfg.Port))
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			serverErr <- err
+		}
+	}()
+
+	// Block until OS signal or server error.
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case sig := <-quit:
+		logger.Info("shutdown signal received", zap.String("signal", sig.String()))
+	case err := <-serverErr:
+		logger.Error("server error", zap.Error(err))
+	}
+
+	// Graceful shutdown: give in-flight requests time to complete.
+	shutdownCtx, shutdownCancel := context.WithTimeout(
+		context.Background(),
+		time.Duration(cfg.ShutdownTimeout)*time.Second,
+	)
+	defer shutdownCancel()
+
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		logger.Error("graceful shutdown error", zap.Error(err))
+	}
+
+	// Remaining resources are closed by deferred calls above (DB, Redis, logger).
+	logger.Info("service stopped cleanly")
+}
+
+// -------------------------------------------------------------------------
+// Infrastructure helpers
+// -------------------------------------------------------------------------
+
+// openPostgres opens a connection pool to PostgreSQL and verifies connectivity.
+func openPostgres(cfg *config.Config) (*sqlx.DB, error) {
+	db, err := sqlx.Open("postgres", cfg.DSN())
+	if err != nil {
+		return nil, fmt.Errorf("opening postgres connection pool: %w", err)
+	}
+
+	db.SetMaxOpenConns(25)
+	db.SetMaxIdleConns(5)
+	db.SetConnMaxLifetime(5 * time.Minute)
+	db.SetConnMaxIdleTime(1 * time.Minute)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := db.PingContext(ctx); err != nil {
+		_ = db.Close()
+		return nil, fmt.Errorf("pinging postgres: %w", err)
+	}
+
+	return db, nil
+}
+
+// openRedis constructs a Redis client from config. Connectivity is verified by the caller.
+func openRedis(cfg *config.Config) *goredis.Client {
+	return goredis.NewClient(&goredis.Options{
+		Addr:         cfg.RedisAddr,
+		Password:     cfg.RedisPassword,
+		DB:           cfg.RedisDB,
+		DialTimeout:  5 * time.Second,
+		ReadTimeout:  3 * time.Second,
+		WriteTimeout: 3 * time.Second,
+		PoolSize:     10,
+		MinIdleConns: 2,
+	})
+}
+
+// healthHandler is the Kubernetes liveness probe.
+// Returns 200 as long as the process is running — no dependency checks.
+func healthHandler(_ *sqlx.DB) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"status":"ok"}`)
+	}
+}
+
+// readyHandler is the Kubernetes readiness probe.
+// Returns 503 if PostgreSQL or Redis is unreachable.
+func readyHandler(db *sqlx.DB, rdb *goredis.Client) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+		defer cancel()
+
+		if err := db.PingContext(ctx); err != nil {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusServiceUnavailable)
+			fmt.Fprint(w, `{"status":"not ready","reason":"postgres unreachable"}`)
+			return
+		}
+		if err := rdb.Ping(ctx).Err(); err != nil {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusServiceUnavailable)
+			fmt.Fprint(w, `{"status":"not ready","reason":"redis unreachable"}`)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"status":"ready"}`)
+	}
+}
+
+// buildLogger constructs a production-grade zap logger with the requested level.
+func buildLogger(level string) (*zap.Logger, error) {
+	var zapLevel zapcore.Level
+	if err := zapLevel.UnmarshalText([]byte(level)); err != nil {
+		zapLevel = zapcore.InfoLevel
+	}
+
+	cfg := zap.NewProductionConfig()
+	cfg.Level = zap.NewAtomicLevelAt(zapLevel)
+	cfg.EncoderConfig.TimeKey = "ts"
+	cfg.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
+
+	logger, err := cfg.Build()
+	if err != nil {
+		return nil, fmt.Errorf("building zap logger: %w", err)
+	}
+	return logger, nil
+}

package/plugins/go-scaffolder/reference-service/config/config.go

@@ -0,0 +1,67 @@
+package config
+
+import (
+	"fmt"
+
+	"github.com/caarlos0/env/v11"
+)
+
+// Config holds all configuration for the booking service.
+// All values are sourced from environment variables — no YAML or TOML files at runtime.
+// Required fields cause Load() to return an error when the variable is unset.
+// Fields with envDefault use that value when the variable is absent.
+type Config struct {
+	// --- Application ---
+	Port            int    `env:"PORT"             envDefault:"8080"`
+	LogLevel        string `env:"LOG_LEVEL"        envDefault:"info"`
+	ServiceName     string `env:"SERVICE_NAME"     envDefault:"booking-service"`
+	ServiceVersion  string `env:"SERVICE_VERSION"  envDefault:"0.1.0"`
+	ShutdownTimeout int    `env:"SHUTDOWN_TIMEOUT" envDefault:"10"` // seconds
+
+	// --- OpenTelemetry (Grafana Tempo gRPC endpoint) ---
+	OTLPEndpoint string `env:"OTLP_ENDPOINT" envDefault:"localhost:4317"`
+
+	// --- PostgreSQL ---
+	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"` // set to 'require' in production
+
+	// --- Redis ---
+	RedisAddr     string `env:"REDIS_ADDR"     envDefault:"localhost:6379"`
+	RedisPassword string `env:"REDIS_PASSWORD" envDefault:""`
+	RedisDB       int    `env:"REDIS_DB"       envDefault:"0"`
+}
+
+// Load parses all environment variables into a Config struct.
+// Returns an error immediately if any required variable is missing or cannot be
+// converted to the declared Go type.
+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 a PostgreSQL connection string from the individual DB fields.
+// NEVER log the return value of this method — it contains the database password.
+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 human-readable summary of the config with all secrets redacted.
+// Safe to pass to a logger.
+func (c *Config) String() string {
+	return fmt.Sprintf(
+		"Config{Port:%d ServiceName:%s ServiceVersion:%s LogLevel:%s DBHost:%s DBName:%s RedisAddr:%s}",
+		c.Port, c.ServiceName, c.ServiceVersion, c.LogLevel,
+		c.DBHost, c.DBName, c.RedisAddr,
+		// DBPass and RedisPassword are intentionally omitted
+	)
+}

package/plugins/go-scaffolder/reference-service/go.mod

@@ -0,0 +1,17 @@
+module github.com/zokypesch/booking-service
+
+go 1.23
+
+require (
+	github.com/go-chi/chi/v5 v5.2.1
+	github.com/google/uuid v1.6.0
+	github.com/jmoiron/sqlx v1.4.0
+	github.com/lib/pq v1.10.9
+	github.com/redis/go-redis/v9 v9.5.1
+	github.com/stretchr/testify v1.9.0
+	github.com/caarlos0/env/v11 v11.3.1
+	github.com/zokypesch/go-ga-lib v0.0.0
+	go.uber.org/zap v1.27.0
+)
+
+replace github.com/zokypesch/go-ga-lib => D:/project/asyst/go-ga-lib

package/plugins/go-scaffolder/reference-service/internal/domain/booking.go

@@ -0,0 +1,118 @@
+package domain
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// Sentinel errors — map these to HTTP status codes in the handler layer.
+// Use errors.Is to check; never compare error strings.
+var (
+	ErrBookingNotFound  = errors.New("booking not found")
+	ErrInvalidStatus    = errors.New("invalid status transition")
+	ErrAlreadyExists    = errors.New("booking already exists")
+	ErrInvalidInput     = errors.New("invalid input")
+	ErrUnauthorized     = errors.New("unauthorized")
+	ErrForbidden        = errors.New("forbidden")
+)
+
+// Status represents the lifecycle state of a booking.
+type Status string
+
+const (
+	StatusPending   Status = "PENDING"
+	StatusConfirmed Status = "CONFIRMED"
+	StatusCancelled Status = "CANCELLED"
+)
+
+// validTransitions defines which status transitions are allowed.
+// A transition not present in this map is invalid.
+var validTransitions = map[Status][]Status{
+	StatusPending:   {StatusConfirmed, StatusCancelled},
+	StatusConfirmed: {StatusCancelled},
+	StatusCancelled: {}, // terminal state
+}
+
+// CanTransitionTo reports whether transitioning from the current status to next is allowed.
+func (s Status) CanTransitionTo(next Status) bool {
+	allowed, ok := validTransitions[s]
+	if !ok {
+		return false
+	}
+	for _, a := range allowed {
+		if a == next {
+			return true
+		}
+	}
+	return false
+}
+
+// Booking is the core domain entity for a flight booking.
+type Booking struct {
+	ID         string    `db:"id"          json:"id"`
+	CustomerID string    `db:"customer_id" json:"customer_id"`
+	FlightID   string    `db:"flight_id"   json:"flight_id"`
+	Status     Status    `db:"status"      json:"status"`
+	SeatCount  int       `db:"seat_count"  json:"seat_count"`
+	TotalPrice float64   `db:"total_price" json:"total_price"`
+	CreatedAt  time.Time `db:"created_at"  json:"created_at"`
+	UpdatedAt  time.Time `db:"updated_at"  json:"updated_at"`
+}
+
+// BookingRepository defines the data access contract for bookings.
+// Implementations must be safe for concurrent use.
+type BookingRepository interface {
+	// Create persists a new booking. entity.ID must be pre-populated by the caller.
+	Create(ctx context.Context, booking *Booking) error
+
+	// GetByID retrieves a booking by its unique ID.
+	// Returns ErrBookingNotFound when no row matches.
+	GetByID(ctx context.Context, id string) (*Booking, error)
+
+	// Update replaces all mutable fields of an existing booking.
+	// Returns ErrBookingNotFound when no row matches.
+	Update(ctx context.Context, booking *Booking) error
+
+	// List returns a paginated slice of bookings ordered by created_at DESC.
+	List(ctx context.Context, limit, offset int) ([]*Booking, error)
+
+	// Delete permanently removes a booking record.
+	// Returns ErrBookingNotFound when no row matches.
+	Delete(ctx context.Context, id string) error
+}
+
+// BookingUsecase defines the business logic contract for bookings.
+// All methods must propagate context for deadline and cancellation support.
+type BookingUsecase interface {
+	// CreateBooking validates the input and creates a new PENDING booking.
+	CreateBooking(ctx context.Context, input CreateBookingInput) (*Booking, error)
+
+	// GetBooking retrieves a single booking by ID.
+	GetBooking(ctx context.Context, id string) (*Booking, error)
+
+	// UpdateBooking applies a partial update to a booking's mutable fields.
+	UpdateBooking(ctx context.Context, id string, input UpdateBookingInput) (*Booking, error)
+
+	// ListBookings returns a paginated list of all bookings.
+	ListBookings(ctx context.Context, limit, offset int) ([]*Booking, error)
+
+	// CancelBooking transitions a booking to CANCELLED status.
+	// Returns ErrInvalidStatus if the booking is already in a terminal state.
+	CancelBooking(ctx context.Context, id string) (*Booking, error)
+}
+
+// CreateBookingInput is the payload for creating a new booking.
+type CreateBookingInput struct {
+	CustomerID string  `json:"customer_id"`
+	FlightID   string  `json:"flight_id"`
+	SeatCount  int     `json:"seat_count"`
+	TotalPrice float64 `json:"total_price"`
+}
+
+// UpdateBookingInput is the payload for updating an existing booking.
+// Pointer fields allow partial updates — nil means "leave unchanged".
+type UpdateBookingInput struct {
+	SeatCount  *int     `json:"seat_count,omitempty"`
+	TotalPrice *float64 `json:"total_price,omitempty"`
+}