dance-lessons-coach/AGENTS.md

dance-lessons-coach — Agent Documentation

AI agent reference for developing, testing, and operating the dance-lessons-coach service.

Tech Stack

Component	Technology	Version
Language	Go	1.26.1
Router	Chi	v5.2.5
Logging	Zerolog	v1.35.0
Configuration	Viper	v1.21.0
Telemetry	OpenTelemetry	v1.43.0
Database	PostgreSQL + GORM	(optional, for user persistence)
Auth	JWT + bcrypt	with rotating secrets
Email	SMTP (Mailpit dev)	for magic-link delivery

Project Structure

dance-lessons-coach/
├── adr/                    # Architecture Decision Records
├── cmd/
│   ├── greet/              # CLI application
│   └── server/             # Web server entry point
├── pkg/
│   ├── auth/               # Auth context keys, OIDC client, helpers
│   ├── config/             # Viper-based configuration
│   ├── email/              # SMTP sender abstraction
│   ├── greet/              # Core domain logic + API handlers
│   ├── server/             # HTTP server, routing, graceful shutdown
│   ├── telemetry/          # OpenTelemetry instrumentation
│   ├── user/               # User domain (auth, JWT, repository)
│   ├── user/api/           # Auth + admin HTTP handlers
│   └── validation/         # Request validation
├── scripts/                # Server lifecycle, build, test scripts
├── config.yaml             # Configuration file
└── config.example.yaml     # Configuration template

Server Management

# Start / stop / restart
./scripts/start-server.sh start
./scripts/start-server.sh stop
./scripts/start-server.sh restart

# Status and logs
./scripts/start-server.sh status
./scripts/start-server.sh logs

# Test all API endpoints
./scripts/start-server.sh test

Configuration

All settings can be provided via config.yaml or environment variables (DLC_ prefix).

Option	Env var	Default	Description
Host	DLC_SERVER_HOST	0.0.0.0	Bind address
Port	DLC_SERVER_PORT	8080	Listening port
Shutdown timeout	DLC_SHUTDOWN_TIMEOUT	30s	Graceful shutdown window
JSON logging	DLC_LOGGING_JSON	false	Structured JSON output
Log output	DLC_LOGGING_OUTPUT	""	File path (empty = stderr)
API v2	DLC_API_V2_ENABLED	false	Enable /api/v2 routes
Config file	DLC_CONFIG_FILE	./config.yaml	Override config path

Minimal config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
shutdown:
  timeout: 30s
logging:
  json: false

Priority: env var > config file > default.

API Endpoints

Method	Path	Description
GET	/api/health	Liveness — always {"status":"healthy"}
GET	/api/healthz	Alternative liveness probe (k8s convention)
GET	/api/ready	Readiness — 200 when ready, 503 during shutdown
GET	/api/info	Composite info endpoint (cf. ADR-0026)
GET	/api/version	Version info (?format=plain|full|json)
GET	/api/v1/greet/	Default greeting
GET	/api/v1/greet/{name}	Personalized greeting
POST	/api/v1/auth/login	Username + password login (JWT)
POST	/api/v1/auth/register	Account creation
POST	/api/v1/auth/validate	JWT validation
POST	/api/v1/auth/password-reset/request	Request a password reset
POST	/api/v1/auth/password-reset/complete	Complete a password reset
POST	/api/v1/auth/magic-link/request	Passwordless : request a magic link by email
GET	/api/v1/auth/magic-link/consume	Passwordless : consume a magic-link token
GET	/api/v1/auth/oidc/{provider}/start	OIDC : begin authorization (PKCE)
GET	/api/v1/auth/oidc/{provider}/callback	OIDC : authorization code → JWT
GET	/api/v1/admin/jwt/secrets	Admin : list JWT signing secrets
POST	/api/v1/admin/jwt/secrets	Admin : add a JWT signing secret
POST	/api/v1/admin/jwt/secrets/rotate	Admin : rotate the active JWT secret
POST	/api/v2/greet	V2 greeting with validation (feature-flagged)
POST	/api/admin/cache/flush	Admin : flush in-memory caches
GET	/swagger/	Swagger UI
GET	/swagger/doc.json	OpenAPI spec (source of truth)

curl http://localhost:8080/api/health
curl http://localhost:8080/api/v1/greet/Alice

# See `/swagger/` for the full interactive list of endpoints.
# The OpenAPI spec at `/swagger/doc.json` is the source of truth.

Testing

# Unit + integration tests
go test ./...
go test -v ./...

# Graceful shutdown + JSON logging validation
./scripts/test-graceful-shutdown.sh

# OpenTelemetry end-to-end
./scripts/test-opentelemetry.sh

Note: Do not call go generate unless editing API endpoint annotations. When needed: go generate ./pkg/server/

Build

./scripts/build.sh
# Produces: ./bin/server  ./bin/greet
./bin/server --version

Build injects version, commit, and date via -ldflags.

Graceful Shutdown

On SIGTERM / SIGINT:

1. Readiness context is cancelled → /api/ready returns 503.
2. 1-second propagation window (load balancer drains).
3. srv.Shutdown() waits up to shutdown.timeout for active requests.
4. Process exits cleanly.

Health endpoint stays 200 throughout; readiness endpoint goes 503 immediately on signal.

OpenTelemetry / Jaeger

Enable in config or via env:

export DLC_TELEMETRY_ENABLED=true
export DLC_TELEMETRY_OTLP_ENDPOINT="localhost:4317"

Quick Jaeger setup:

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 -p 4317:4317 \
  jaegertracing/all-in-one:latest

Architecture Decision Records

The full index is at adr/README.md — 30 ADRs covering Go version, Chi router, Zerolog, OpenTelemetry, BDD testing, JWT auth, PostgreSQL, OIDC migration, email infrastructure, etc.

Add a new ADR : copy an existing file in adr/, edit it, update adr/README.md.

Commit Conventions

Conventional Commits with optional gitmoji:

Emoji	Type	When
✨	feat	New feature
🐛	fix	Bug fix
📝	docs	Documentation
🎨	style	Formatting only
♻️	refactor	Structural change
🚀	perf	Performance
🔒	security	Security fix
📦	chore	Dependencies / build
🧪	test	Tests
🤖	ci	CI/CD
🔥	remove	Delete code/files

Examples:

feat: add JWT authentication middleware
fix: ensure first log line is JSON when json logging is enabled
docs: rewrite AGENTS.md for clarity