Stage 1: backend foundation (Postgres, sessions, accounts, OTel)

- internal/postgres: pgx-over-database/sql pool (otelsql), embedded goose
  migrations into schema 'backend', committed go-jet code + cmd/jetgen tool.
- internal/account: durable accounts + unified telegram/email identities
  (UUIDv7 keys), find-or-create provisioning with unique-conflict handling.
- internal/session: opaque 256-bit tokens stored as a SHA-256 hash, revoke-only
  (no TTL); write-through cache gating /readyz; store + service.
- internal/telemetry: OTel tracer/meter providers (none/stdout) + request-timing
  middleware; internal/config gains Postgres + OTel env loading.
- internal/server: /api/v1 {public,user,internal,admin} skeleton + X-User-ID
  middleware; /readyz checks DB ping + cache; main wires
  telemetry -> db+migrate -> warm cache -> server.
- Tests: unit + integration (build tag 'integration', testcontainers
  postgres:17) for migrations, accounts, sessions, readyz; new integration.yaml.
- Docs: ARCHITECTURE, TESTING, PLAN refinements, root + backend READMEs.

Session/account REST handlers deferred to Stage 6 (gateway); OTLP + dashboards
to Stage 11.

backend/internal/telemetry/middleware.go

@@ -0,0 +1,74 @@
+package telemetry
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.uber.org/zap"
+)
+
+// tracerName names the instrumentation scope for backend HTTP spans.
+const tracerName = "scrabble/backend/server"
+
+// Middleware returns gin middleware that, for every request, opens a server
+// span, measures server-side latency, and emits a structured access log
+// correlated with the active trace. It uses the globally-registered tracer, so
+// spans are exported only when an exporter is configured, while the timing log
+// is always emitted. Probe paths (/healthz, /readyz) log at debug level to keep
+// the default log clean.
+func Middleware(logger *zap.Logger) gin.HandlerFunc {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+	tracer := otel.Tracer(tracerName)
+
+	return func(c *gin.Context) {
+		start := time.Now()
+		route := c.FullPath()
+		if route == "" {
+			route = c.Request.URL.Path
+		}
+
+		ctx, span := tracer.Start(c.Request.Context(), c.Request.Method+" "+route)
+		c.Request = c.Request.WithContext(ctx)
+
+		c.Next()
+
+		status := c.Writer.Status()
+		elapsed := time.Since(start)
+
+		span.SetAttributes(
+			attribute.String("http.request.method", c.Request.Method),
+			attribute.String("http.route", route),
+			attribute.Int("http.response.status_code", status),
+		)
+		if status >= http.StatusInternalServerError {
+			span.SetStatus(codes.Error, http.StatusText(status))
+		}
+		span.End()
+
+		fields := []zap.Field{
+			zap.String("method", c.Request.Method),
+			zap.String("path", route),
+			zap.Int("status", status),
+			zap.Duration("latency", elapsed),
+		}
+		fields = append(fields, TraceFieldsFromContext(ctx)...)
+
+		if isProbePath(c.Request.URL.Path) {
+			logger.Debug("http request", fields...)
+			return
+		}
+		logger.Info("http request", fields...)
+	}
+}
+
+// isProbePath reports whether path is one of the unauthenticated infrastructure
+// probes, whose access logs are demoted to debug level.
+func isProbePath(path string) bool {
+	return path == "/healthz" || path == "/readyz"
+}

backend/internal/telemetry/telemetry.go

@@ -0,0 +1,204 @@
+// Package telemetry owns the OpenTelemetry runtime for the backend process.
+//
+// New constructs the configured tracer and meter providers, registers them as
+// the OpenTelemetry globals, and exposes Shutdown for orderly exit. The MVP
+// supports the `none` and `stdout` exporters; OTLP export and dashboards arrive
+// in a later stage. The per-request timing middleware lives in middleware.go and
+// uses the registered global tracer, so requests are timed and logged even when
+// the exporter is `none`.
+package telemetry
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/stdout/stdoutmetric"
+	"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
+	"go.opentelemetry.io/otel/metric"
+	"go.opentelemetry.io/otel/propagation"
+	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/zap"
+)
+
+// Exporter selectors supported by the backend.
+const (
+	ExporterNone   = "none"
+	ExporterStdout = "stdout"
+)
+
+// DefaultServiceName labels traces and metrics when BACKEND_SERVICE_NAME is
+// unset.
+const DefaultServiceName = "scrabble-backend"
+
+// Config selects the telemetry providers' service name and exporters.
+type Config struct {
+	// ServiceName is reported as the OpenTelemetry service.name resource.
+	ServiceName string
+	// TracesExporter is one of ExporterNone or ExporterStdout.
+	TracesExporter string
+	// MetricsExporter is one of ExporterNone or ExporterStdout.
+	MetricsExporter string
+}
+
+// DefaultConfig returns the MVP telemetry configuration: named service, no
+// exporters (so no collector is required locally or in CI).
+func DefaultConfig() Config {
+	return Config{
+		ServiceName:     DefaultServiceName,
+		TracesExporter:  ExporterNone,
+		MetricsExporter: ExporterNone,
+	}
+}
+
+// Validate reports whether the configuration selects supported exporters.
+func (c Config) Validate() error {
+	if c.ServiceName == "" {
+		return errors.New("telemetry: ServiceName must not be empty")
+	}
+	if err := validateExporter("traces", c.TracesExporter); err != nil {
+		return err
+	}
+	return validateExporter("metrics", c.MetricsExporter)
+}
+
+func validateExporter(kind, value string) error {
+	switch value {
+	case ExporterNone, ExporterStdout:
+		return nil
+	default:
+		return fmt.Errorf("telemetry: unsupported %s exporter %q", kind, value)
+	}
+}
+
+// Runtime owns the shared OpenTelemetry providers.
+type Runtime struct {
+	tracerProvider *sdktrace.TracerProvider
+	meterProvider  *sdkmetric.MeterProvider
+}
+
+// New constructs the telemetry runtime, registers the global providers and the
+// W3C trace-context/baggage propagators, and returns the Runtime. Callers must
+// invoke Runtime.Shutdown during process exit.
+func New(ctx context.Context, cfg Config) (*Runtime, error) {
+	if err := cfg.Validate(); err != nil {
+		return nil, err
+	}
+
+	res, err := resource.New(ctx, resource.WithAttributes(
+		attribute.String("service.name", cfg.ServiceName),
+	))
+	if err != nil {
+		return nil, fmt.Errorf("telemetry: build resource: %w", err)
+	}
+
+	tracerProvider, err := newTracerProvider(cfg, res)
+	if err != nil {
+		return nil, fmt.Errorf("telemetry: build tracer provider: %w", err)
+	}
+	meterProvider, err := newMeterProvider(cfg, res)
+	if err != nil {
+		_ = tracerProvider.Shutdown(ctx)
+		return nil, fmt.Errorf("telemetry: build meter provider: %w", err)
+	}
+
+	otel.SetTracerProvider(tracerProvider)
+	otel.SetMeterProvider(meterProvider)
+	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{},
+		propagation.Baggage{},
+	))
+
+	return &Runtime{tracerProvider: tracerProvider, meterProvider: meterProvider}, nil
+}
+
+// TracerProvider returns the runtime tracer provider, or the global one when r
+// is not initialised.
+func (r *Runtime) TracerProvider() trace.TracerProvider {
+	if r == nil || r.tracerProvider == nil {
+		return otel.GetTracerProvider()
+	}
+	return r.tracerProvider
+}
+
+// MeterProvider returns the runtime meter provider, or the global one when r is
+// not initialised.
+func (r *Runtime) MeterProvider() metric.MeterProvider {
+	if r == nil || r.meterProvider == nil {
+		return otel.GetMeterProvider()
+	}
+	return r.meterProvider
+}
+
+// Shutdown flushes both providers within ctx.
+func (r *Runtime) Shutdown(ctx context.Context) error {
+	if r == nil {
+		return nil
+	}
+	var err error
+	if r.meterProvider != nil {
+		err = errors.Join(err, r.meterProvider.Shutdown(ctx))
+	}
+	if r.tracerProvider != nil {
+		err = errors.Join(err, r.tracerProvider.Shutdown(ctx))
+	}
+	return err
+}
+
+// TraceFieldsFromContext returns zap fields identifying the active span, or nil
+// when ctx carries no valid span context. Collocated here so callers do not
+// import the OpenTelemetry API directly.
+func TraceFieldsFromContext(ctx context.Context) []zap.Field {
+	if ctx == nil {
+		return nil
+	}
+	sc := trace.SpanContextFromContext(ctx)
+	if !sc.IsValid() {
+		return nil
+	}
+	return []zap.Field{
+		zap.String("otel_trace_id", sc.TraceID().String()),
+		zap.String("otel_span_id", sc.SpanID().String()),
+	}
+}
+
+func newTracerProvider(cfg Config, res *resource.Resource) (*sdktrace.TracerProvider, error) {
+	switch cfg.TracesExporter {
+	case ExporterNone:
+		return sdktrace.NewTracerProvider(sdktrace.WithResource(res)), nil
+	case ExporterStdout:
+		exporter, err := stdouttrace.New()
+		if err != nil {
+			return nil, fmt.Errorf("stdout trace exporter: %w", err)
+		}
+		return sdktrace.NewTracerProvider(
+			sdktrace.WithBatcher(exporter),
+			sdktrace.WithResource(res),
+		), nil
+	default:
+		return nil, fmt.Errorf("unsupported traces exporter %q", cfg.TracesExporter)
+	}
+}
+
+func newMeterProvider(cfg Config, res *resource.Resource) (*sdkmetric.MeterProvider, error) {
+	switch cfg.MetricsExporter {
+	case ExporterNone:
+		return sdkmetric.NewMeterProvider(sdkmetric.WithResource(res)), nil
+	case ExporterStdout:
+		exporter, err := stdoutmetric.New()
+		if err != nil {
+			return nil, fmt.Errorf("stdout metric exporter: %w", err)
+		}
+		return sdkmetric.NewMeterProvider(
+			sdkmetric.WithResource(res),
+			sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
+		), nil
+	default:
+		return nil, fmt.Errorf("unsupported metrics exporter %q", cfg.MetricsExporter)
+	}
+}

backend/internal/telemetry/telemetry_test.go

@@ -0,0 +1,82 @@
+package telemetry
+
+import (
+	"context"
+	"testing"
+)
+
+// TestConfigValidate covers the supported and rejected exporter selections.
+func TestConfigValidate(t *testing.T) {
+	if err := DefaultConfig().Validate(); err != nil {
+		t.Fatalf("default config must be valid: %v", err)
+	}
+
+	otlp := DefaultConfig()
+	otlp.TracesExporter = "otlp"
+	if err := otlp.Validate(); err == nil {
+		t.Error("otlp exporter must be rejected in the MVP set")
+	}
+
+	noName := DefaultConfig()
+	noName.ServiceName = ""
+	if err := noName.Validate(); err == nil {
+		t.Error("empty service name must be rejected")
+	}
+}
+
+// TestNewNoneAndShutdown builds the providers with the none exporter and shuts
+// them down.
+func TestNewNoneAndShutdown(t *testing.T) {
+	rt, err := New(context.Background(), DefaultConfig())
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	if rt.TracerProvider() == nil {
+		t.Error("TracerProvider must not be nil")
+	}
+	if rt.MeterProvider() == nil {
+		t.Error("MeterProvider must not be nil")
+	}
+	if err := rt.Shutdown(context.Background()); err != nil {
+		t.Errorf("Shutdown: %v", err)
+	}
+}
+
+// TestNewStdoutTraces builds the providers with the stdout trace exporter; no
+// spans are recorded, so shutdown flushes nothing to stdout.
+func TestNewStdoutTraces(t *testing.T) {
+	cfg := DefaultConfig()
+	cfg.TracesExporter = ExporterStdout
+	rt, err := New(context.Background(), cfg)
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	if err := rt.Shutdown(context.Background()); err != nil {
+		t.Errorf("Shutdown: %v", err)
+	}
+}
+
+// TestTraceFieldsFromContextEmpty returns no fields without an active span.
+func TestTraceFieldsFromContextEmpty(t *testing.T) {
+	if TraceFieldsFromContext(context.Background()) != nil {
+		t.Error("expected nil fields without an active span")
+	}
+	var nilCtx context.Context
+	if TraceFieldsFromContext(nilCtx) != nil {
+		t.Error("expected nil fields for a nil context")
+	}
+}
+
+// TestNilRuntime checks the nil-receiver fallbacks used before initialisation.
+func TestNilRuntime(t *testing.T) {
+	var rt *Runtime
+	if rt.TracerProvider() == nil {
+		t.Error("nil runtime must fall back to the global tracer provider")
+	}
+	if rt.MeterProvider() == nil {
+		t.Error("nil runtime must fall back to the global meter provider")
+	}
+	if err := rt.Shutdown(context.Background()); err != nil {
+		t.Errorf("nil runtime Shutdown: %v", err)
+	}
+}