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/inttest/main_test.go

@@ -0,0 +1,109 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"net/url"
+	"os"
+	"testing"
+	"time"
+
+	testcontainers "github.com/testcontainers/testcontainers-go"
+	tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
+	"github.com/testcontainers/testcontainers-go/wait"
+
+	"scrabble/backend/internal/postgres"
+)
+
+// testDB is the shared, migrated pool every integration test runs against. It is
+// hydrated once by TestMain.
+var testDB *sql.DB
+
+const (
+	pgImage           = "postgres:17-alpine"
+	pgDatabase        = "scrabble_backend"
+	pgUser            = "scrabble"
+	pgPassword        = "scrabble"
+	pgSchema          = "backend"
+	containerStartup  = 90 * time.Second
+	containerShutdown = 30 * time.Second
+)
+
+// TestMain starts one Postgres container, applies the migrations, and shares the
+// resulting pool with every test. Any setup failure aborts the suite loudly
+// (exit 1) rather than skipping coverage.
+func TestMain(m *testing.M) {
+	code, err := runSuite(m)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "inttest:", err)
+		os.Exit(1)
+	}
+	os.Exit(code)
+}
+
+func runSuite(m *testing.M) (int, error) {
+	ctx := context.Background()
+
+	container, err := tcpostgres.Run(ctx, pgImage,
+		tcpostgres.WithDatabase(pgDatabase),
+		tcpostgres.WithUsername(pgUser),
+		tcpostgres.WithPassword(pgPassword),
+		testcontainers.WithWaitStrategy(
+			wait.ForLog("database system is ready to accept connections").
+				WithOccurrence(2).
+				WithStartupTimeout(containerStartup),
+		),
+	)
+	if err != nil {
+		return 0, fmt.Errorf("start postgres container: %w", err)
+	}
+	defer func() {
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), containerShutdown)
+		defer cancel()
+		if termErr := container.Terminate(shutdownCtx); termErr != nil {
+			fmt.Fprintln(os.Stderr, "inttest: terminate container:", termErr)
+		}
+	}()
+
+	baseDSN, err := container.ConnectionString(ctx, "sslmode=disable")
+	if err != nil {
+		return 0, fmt.Errorf("resolve container dsn: %w", err)
+	}
+	dsn, err := withSearchPath(baseDSN, pgSchema)
+	if err != nil {
+		return 0, err
+	}
+
+	cfg := postgres.DefaultConfig()
+	cfg.DSN = dsn
+	db, err := postgres.Open(ctx, cfg)
+	if err != nil {
+		return 0, fmt.Errorf("open pool: %w", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	if err := postgres.ApplyMigrations(ctx, db); err != nil {
+		return 0, fmt.Errorf("apply migrations: %w", err)
+	}
+
+	testDB = db
+	return m.Run(), nil
+}
+
+// withSearchPath rewrites dsn so every connection pins search_path to schema.
+func withSearchPath(dsn, schema string) (string, error) {
+	u, err := url.Parse(dsn)
+	if err != nil {
+		return "", fmt.Errorf("parse dsn: %w", err)
+	}
+	q := u.Query()
+	q.Set("search_path", schema)
+	if q.Get("sslmode") == "" {
+		q.Set("sslmode", "disable")
+	}
+	u.RawQuery = q.Encode()
+	return u.String(), nil
+}