From 1aef1364369e660dd266920ca20ae7a3ec276baa Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Wed, 6 May 2026 06:37:17 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20cherry-pick=206=20focuse?= =?UTF-8?q?d=20guides=20from=20PR=20#17=20(option=20c)=20(#87)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gabriel Radureau Co-committed-by: Gabriel Radureau --- documentation/CLI.md | 251 +++++++++++++++++++++++++++++++ documentation/CODE_EXAMPLES.md | 59 ++++++++ documentation/HISTORY.md | 83 ++++++++++ documentation/OBSERVABILITY.md | 94 ++++++++++++ documentation/ROADMAP.md | 40 +++++ documentation/TROUBLESHOOTING.md | 107 +++++++++++++ 6 files changed, 634 insertions(+) create mode 100644 documentation/CLI.md create mode 100644 documentation/CODE_EXAMPLES.md create mode 100644 documentation/HISTORY.md create mode 100644 documentation/OBSERVABILITY.md create mode 100644 documentation/ROADMAP.md create mode 100644 documentation/TROUBLESHOOTING.md diff --git a/documentation/CLI.md b/documentation/CLI.md new file mode 100644 index 0000000..9415ded --- /dev/null +++ b/documentation/CLI.md @@ -0,0 +1,251 @@ +# CLI Management Guide + +Complete reference for the `dance-lessons-coach` CLI, server lifecycle, and configuration. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe. + +## Cobra CLI (Recommended) + +`dance-lessons-coach` includes a modern CLI built with Cobra: + +```bash +# Show help and available commands +./bin/dance-lessons-coach --help + +# Show version information +./bin/dance-lessons-coach version + +# Greet someone by name +./bin/dance-lessons-coach greet John + +# Start the server +./bin/dance-lessons-coach server +``` + +**Available Commands:** + +- `version` — Print version information +- `server` — Start the dance-lessons-coach server +- `greet [name]` — Greet someone by name +- `help` — Built-in help system +- `completion` — Generate shell completion scripts + +**Server Command Flags:** + +- `--config` — Config file path +- `--env` — Environment (`dev`, `staging`, `prod`) +- `--debug` — Enable debug logging + +## Version Information + +The server provides runtime version information: + +```bash +# Check version using new CLI +./bin/dance-lessons-coach version + +# Check version using server binary +./bin/server --version + +# Output: +dance-lessons-coach Version Information: + Version: 1.0.0 + Commit: abc1234 + Built: 2026-04-05T10:00:00+0000 + Go: go1.26.1 +``` + +For full version management workflow (bump, release, build with version), see [`version-management-guide.md`](version-management-guide.md). + +## Server Control Script + +A shell script manages the server lifecycle: + +```bash +cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach + +./scripts/start-server.sh start # Start the server +./scripts/start-server.sh status # Check server status +./scripts/start-server.sh test # Test API endpoints +./scripts/start-server.sh logs # View server logs +./scripts/start-server.sh stop # Stop the server +./scripts/start-server.sh restart # Restart +``` + +**Available subcommands:** + +- `start` — Start the server in background with proper logging +- `stop` — Stop the server gracefully +- `restart` — Restart the server +- `status` — Check if server is running +- `logs` — Show recent server logs +- `test` — Test all API endpoints + +## Manual Server Management + +For direct control: + +```bash +cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach +./scripts/start-server.sh start +``` + +**Expected output:** + +``` +Server running on :8080 +[INF] Starting HTTP server on :8080 +[TRC] Registering greet routes +[TRC] Greet routes registered +``` + +**Features:** + +- Context-aware server initialization +- Graceful shutdown handling +- Signal-based termination (`SIGINT`, `SIGTERM`) +- 30-second shutdown timeout +- Proper resource cleanup + +## Configuration + +Configuration via environment variables with `DLC_` prefix: + +| Option | Environment Variable | Default | Description | +|---|---|---|---| +| Host | `DLC_SERVER_HOST` | `0.0.0.0` | Server bind address | +| Port | `DLC_SERVER_PORT` | `8080` | Server listening port | +| Shutdown Timeout | `DLC_SHUTDOWN_TIMEOUT` | `30s` | Graceful shutdown timeout | +| JSON Logging | `DLC_LOGGING_JSON` | `false` | Enable JSON format logging | +| Log Output | `DLC_LOGGING_OUTPUT` | `""` | Log output file path (empty for stderr) | + +**Examples:** + +```bash +# Custom port +export DLC_SERVER_PORT=9090 +./scripts/start-server.sh start + +# Custom host and port +export DLC_SERVER_HOST="127.0.0.1" +export DLC_SERVER_PORT=8081 +./scripts/start-server.sh start + +# Custom shutdown timeout +export DLC_SHUTDOWN_TIMEOUT=45s + +# Enable JSON logging +export DLC_LOGGING_JSON=true + +# Log to file +export DLC_LOGGING_OUTPUT="server.log" + +# Combined: JSON logging to file +export DLC_LOGGING_JSON=true +export DLC_LOGGING_OUTPUT="server.json.log" +``` + +**Configuration File Support:** + +A `config.example.yaml` file is provided as a template. By default, the application looks for `config.yaml` in the current working directory. + +To specify a custom config file path, set the `DLC_CONFIG_FILE` environment variable: + +```bash +DLC_CONFIG_FILE="/path/to/config.yaml" go run ./cmd/server +``` + +Example `config.yaml`: + +```yaml +server: + host: "0.0.0.0" + port: 8080 + +shutdown: + timeout: 30s + +logging: + json: false +``` + +**Configuration Loading Precedence:** + +1. **File-based configuration** (highest precedence) +2. **Environment variables** (override defaults, overridden by config file) +3. **Default values** (fallback) + +All configuration is validated on startup. Invalid configurations cause server startup failure. Configuration values and source are logged at startup. + +**Verification:** + +```bash +DLC_SERVER_PORT=9090 DLC_SERVER_HOST="127.0.0.1" ./scripts/start-server.sh start + +curl http://127.0.0.1:9090/api/health +# Expected: {"status":"healthy"} +``` + +## Server Status + +```bash +# Check health endpoint +curl -s http://localhost:8080/api/health + +# Check readiness endpoint +curl -s http://localhost:8080/api/ready +``` + +**Expected responses:** + +- Health: `{"status":"healthy"}` +- Readiness (normal): `{"ready":true}` +- Readiness (during shutdown): `{"ready":false}` (HTTP 503) + +**Endpoint Differences:** + +- **Health endpoint** (`/api/health`): Indicates if the application is running and functional +- **Readiness endpoint** (`/api/ready`): Indicates if the application is ready to accept traffic + +**Use Cases:** + +- **Health**: Used by load balancers to check if the app is alive +- **Readiness**: Used by Kubernetes / service meshes to determine if the app can accept new requests + +**During Graceful Shutdown:** + +- Health endpoint continues to return `{"status":"healthy"}` +- Readiness endpoint returns `{"ready":false}` with HTTP 503 Service Unavailable +- This allows existing requests to complete while preventing new requests + +## Stopping the Server + +To stop the server gracefully: + +```bash +# Send SIGTERM for graceful shutdown +kill -TERM $(lsof -ti :8080) + +# Or send SIGINT (Ctrl+C equivalent) +pkill -INT -f "go run" +``` + +**Graceful shutdown process:** + +1. Server receives termination signal +2. Logs shutdown message +3. Stops accepting new connections +4. Waits up to 30 seconds for active requests to complete +5. Closes all connections cleanly +6. Exits with proper cleanup + +For force stop (if graceful shutdown hangs): + +```bash +kill -9 $(lsof -ti :8080) +``` + +**Verification:** + +```bash +curl -s http://localhost:8080/api/health +# Should return connection refused +``` diff --git a/documentation/CODE_EXAMPLES.md b/documentation/CODE_EXAMPLES.md new file mode 100644 index 0000000..16aadfb --- /dev/null +++ b/documentation/CODE_EXAMPLES.md @@ -0,0 +1,59 @@ +# Code Examples + +Snippets and patterns used across the `dance-lessons-coach` codebase. Extracted from the original `AGENTS.md` (Tâche 6 restructure). + +## Adding a New API Endpoint + +```go +// 1. Add to interface +func (h *apiV1GreetHandler) RegisterRoutes(router chi.Router) { + router.Get("/", h.handleGreetQuery) + router.Get("/{name}", h.handleGreetPath) + router.Post("/custom", h.handleCustomGreet) // New endpoint +} + +// 2. Implement handler +func (h *apiV1GreetHandler) handleCustomGreet(w http.ResponseWriter, r *http.Request) { + // Parse request + // Call service + // Return JSON response +} +``` + +## Logging with Zerolog + +```go +// Trace level logging +log.Trace().Ctx(ctx).Str("key", "value").Msg("message") + +// Info level +log.Info().Msg("Important event") + +// Error level +log.Error().Err(err).Msg("Error occurred") +``` + +For the full logging strategy (when to use Trace vs Info, performance considerations), see [ADR-0003 — Zerolog Logging](../adr/0003-zerolog-logging.md). + +## Using `context.Context` + +```go +// Pass context through calls +func handler(w http.ResponseWriter, r *http.Request) { + result := service.Greet(r.Context(), "John") + // ... +} + +// Create context with values +ctx := context.WithValue(r.Context(), "key", "value") + +// Create context with timeout +ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second) +defer cancel() +``` + +For the rationale behind context-aware services, see [ADR-0004 — Interface-Based Design](../adr/0004-interface-based-design.md). + +## Best Practices Reminders + +For higher-level guidance on code organization, error handling, performance, and testing, see [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md#best-practices) section "Best Practices". diff --git a/documentation/HISTORY.md b/documentation/HISTORY.md new file mode 100644 index 0000000..9b45655 --- /dev/null +++ b/documentation/HISTORY.md @@ -0,0 +1,83 @@ +# Development History + +This document records the historical development phases of `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe (128k context). + +All phases below are **completed** ✅. They are kept here for traceability and onboarding context — refer to ADRs (`adr/`) for the technical decisions behind each phase. + +## Phase 1: Foundation + +- Go 1.26.1 environment setup +- Project structure with `cmd/` and `pkg/` directories +- Core Greet service implementation +- CLI interface +- Unit tests + +## Phase 2: Web API + +- Chi router integration +- Versioned API endpoints (`/api/v1`) +- Health endpoint (`/api/health`) +- JSON responses with proper headers + +## Phase 3: Logging & Architecture + +- Zerolog integration with Trace level +- Context-aware logging +- Interface-based design patterns +- Dependency injection + +## Phase 4: Documentation & Testing + +- Comprehensive `AGENTS.md` +- `README.md` with usage instructions +- Server management guide +- API endpoint documentation + +## Phase 5: Configuration Management + +- Viper integration for configuration +- Environment variable support with `DLC_` prefix +- Customizable server host/port +- Configurable shutdown timeout +- Configuration validation and logging +- Example configuration file + +## Phase 6: Graceful Shutdown + +- Context-aware server initialization +- Signal-based termination (`SIGINT`, `SIGTERM`) +- Configurable shutdown timeout +- Readiness endpoint for Kubernetes/service mesh integration +- Proper resource cleanup during shutdown +- Health endpoint remains healthy during graceful shutdown + +## Phase 7: OpenTelemetry Integration + +- OpenTelemetry Go libraries integration +- Jaeger compatibility for distributed tracing +- Middleware-only approach using `otelhttp.NewHandler` +- Configurable sampling strategies +- Graceful shutdown of tracer provider +- OTLP exporter with gRPC support + +## Phase 8: Build System & Documentation + +- Build script for binary compilation +- Binary output to `bin/` directory +- Comprehensive commit conventions with gitmoji reference +- Updated documentation with Jaeger integration guide +- Cleaned up configuration files +- Enhanced logging configuration with file output support + +## Phase 9: Final Refinements + +- Removed unnecessary `time.Sleep` for log flushing +- Changed server operational logs from Info to Trace level +- Moved all logging setup logic to config package +- Simplified server entrypoint to 27 lines +- Verified all functionality with comprehensive testing +- Updated documentation to reflect final architecture + +## Beyond Phase 9 + +Subsequent work (CI/CD, BDD scenarios, ADR audit, JWT, config hot-reloading) is tracked in the [Changelog](../CHANGELOG.md) and the corresponding [ADRs](../adr/). diff --git a/documentation/OBSERVABILITY.md b/documentation/OBSERVABILITY.md new file mode 100644 index 0000000..4c19a9e --- /dev/null +++ b/documentation/OBSERVABILITY.md @@ -0,0 +1,94 @@ +# Observability — OpenTelemetry & Jaeger Integration + +Tracing setup for `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe. + +The application supports OpenTelemetry for distributed tracing with Jaeger compatibility. + +## Configuration + +Enable OpenTelemetry in your `config.yaml`: + +```yaml +telemetry: + enabled: true + otlp_endpoint: "localhost:4317" + service_name: "dance-lessons-coach" + insecure: true + sampler: + type: "parentbased_always_on" + ratio: 1.0 +``` + +Or via environment variables: + +```bash +export DLC_TELEMETRY_ENABLED=true +export DLC_TELEMETRY_OTLP_ENDPOINT="localhost:4317" +export DLC_TELEMETRY_SERVICE_NAME="dance-lessons-coach" +export DLC_TELEMETRY_INSECURE=true +export DLC_TELEMETRY_SAMPLER_TYPE="parentbased_always_on" +export DLC_TELEMETRY_SAMPLER_RATIO=1.0 +``` + +## Testing with Jaeger + +**1. Start Jaeger in Docker:** + +```bash +docker run -d --name jaeger \ + -e COLLECTOR_OTLP_ENABLED=true \ + -p 16686:16686 \ + -p 4317:4317 \ + jaegertracing/all-in-one:latest +``` + +**2. Start the server with OpenTelemetry enabled:** + +```bash +# Using config file +./scripts/start-server.sh start + +# Or with environment variables +DLC_TELEMETRY_ENABLED=true ./scripts/start-server.sh start +``` + +**3. Make API requests:** + +```bash +curl http://localhost:8080/api/v1/greet/John +``` + +**4. View traces in Jaeger UI:** + +Open http://localhost:16686 and select the `dance-lessons-coach` service. + +## Sampler Types + +| Sampler | Behavior | +|---|---| +| `always_on` | Sample all traces | +| `always_off` | Sample no traces | +| `traceidratio` | Sample based on trace ID ratio | +| `parentbased_always_on` | Sample based on parent span (always on) | +| `parentbased_always_off` | Sample based on parent span (always off) | +| `parentbased_traceidratio` | Sample based on parent span with ratio | + +## Testing Script + +A convenience script is provided: + +```bash +./scripts/test-opentelemetry.sh +``` + +This script: + +1. Starts Jaeger container +2. Starts the server with OpenTelemetry +3. Makes test API calls +4. Shows Jaeger UI URL +5. Cleans up on exit + +## ADR Reference + +See [ADR-0007 — OpenTelemetry Integration](../adr/0007-opentelemetry-integration.md) for the full architectural decision and rationale (middleware-only approach, sampling strategy, OTLP/gRPC choice). diff --git a/documentation/ROADMAP.md b/documentation/ROADMAP.md new file mode 100644 index 0000000..630cd4d --- /dev/null +++ b/documentation/ROADMAP.md @@ -0,0 +1,40 @@ +# Roadmap & Future Enhancements + +Tracking pending features and architectural improvements. Extracted from the original `AGENTS.md` (Tâche 6 restructure). Status updated continuously — items move to "Completed Features" section once shipped. + +## Potential Features + +- [ ] Database integration +- [ ] Authentication / Authorization +- [ ] Rate limiting +- [ ] Metrics and monitoring +- [ ] Docker containerization +- ✅ CI/CD pipeline ([ADR-0016](../adr/0016-ci-cd-pipeline-design.md), [ADR-0017](../adr/0017-trunk-based-development-workflow.md)) +- [ ] Configuration hot reload +- [ ] Circuit breakers + +## Architectural Improvements + +- [ ] Request validation middleware +- ✅ OpenAPI / Swagger documentation with embedded spec +- [ ] Enhanced OpenTelemetry instrumentation +- [ ] Metrics collection and visualization +- [ ] Health check improvements +- [ ] Configuration validation enhancements + +## Completed Features + +- ✅ Graceful shutdown with readiness endpoint +- ✅ OpenTelemetry integration with Jaeger support +- ✅ Configuration management with Viper +- ✅ Comprehensive logging with Zerolog +- ✅ Build system with binary output +- ✅ Complete documentation with commit conventions +- ✅ Version management with runtime info + +## How to Propose a New Feature + +1. Open a Gitea issue describing the use case and acceptance criteria +2. If the feature implies an architectural decision, draft an ADR (`adr/-.md`) following the template +3. Reference the ADR + issue in any PR introducing the feature +4. Update this roadmap (move from "Potential" to "Completed" when shipped) diff --git a/documentation/TROUBLESHOOTING.md b/documentation/TROUBLESHOOTING.md new file mode 100644 index 0000000..4e0c122 --- /dev/null +++ b/documentation/TROUBLESHOOTING.md @@ -0,0 +1,107 @@ +# Troubleshooting + +Common issues and their resolution. Extracted from the original `AGENTS.md` and merged with relevant sections from `AGENT_USAGE_GUIDE.md` and `BDD_GUIDE.md`. Refer back to those guides for context-specific troubleshooting (agent workflows, BDD test failures). + +## Port Already in Use + +```bash +# Find and kill process using port 8080 +kill -TERM $(lsof -ti :8080) + +# Force kill if graceful does not work +kill -9 $(lsof -ti :8080) +``` + +## Server Not Responding + +```bash +# Check if running +curl -s http://localhost:8080/api/health + +# Restart server using control script +./scripts/start-server.sh restart + +# View recent logs +./scripts/start-server.sh logs +``` + +If health endpoint returns connection refused, the server may have crashed. Check logs in `./scripts/start-server.sh logs` for stack traces. + +## Dependency Issues + +```bash +# Clean and rebuild +go mod tidy +go build ./... + +# If dependency version conflicts persist +go mod download +go mod verify +``` + +## Tests Failing + +### Unit tests + +```bash +# Run with verbose output +go test -v ./... + +# Check specific test +go test ./pkg/greet/ -run TestName +``` + +### BDD tests + +See [`BDD_GUIDE.md`](BDD_GUIDE.md) for the full BDD troubleshooting workflow (Godog setup, scenario isolation, step matching). Common BDD issues: + +- **Step not found** → check `pkg/bdd/steps/` for the step definition file +- **Scenario state leaking** → review [ADR-0025](../adr/0025-bdd-scenario-isolation-strategies.md) for the isolation pattern +- **Database not reset** → ensure the test fixtures cleanup runs (BDD scenario After hooks) + +## Configuration Not Loading + +The application logs the configuration source at startup. Check logs for: + +``` +[INF] Configuration loaded from: file:config.yaml +# or +[INF] Configuration loaded from: env +# or +[INF] Configuration loaded from: defaults +``` + +If config is not loading as expected: + +1. Verify file exists and is readable: `ls -la config.yaml` +2. Verify env vars are exported: `env | grep DLC_` +3. Check for typos in keys (case-sensitive) +4. Review [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md) section "Configuration troubleshooting" + +## OpenTelemetry Not Tracing + +1. Verify Jaeger is running: `docker ps | grep jaeger` +2. Check `DLC_TELEMETRY_ENABLED=true` in environment or `telemetry.enabled: true` in config +3. Verify OTLP endpoint reachable: `nc -zv localhost 4317` +4. Check sampler is not `always_off` +5. See [`OBSERVABILITY.md`](OBSERVABILITY.md) for full setup + +## Build Failures + +```bash +# Clear caches +go clean -cache -modcache +go mod download + +# Rebuild +go build ./... +``` + +If errors persist, see [`local-ci-cd-testing.md`](local-ci-cd-testing.md) for the CI/CD pipeline that mirrors the production build. + +## Where to Look Next + +- **Agent-specific issues** (vibe, mistral, programmer agent) → [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md) +- **BDD-specific issues** → [`BDD_GUIDE.md`](BDD_GUIDE.md) +- **Version/release issues** → [`version-management-guide.md`](version-management-guide.md) +- **CI/CD issues** → [`local-ci-cd-testing.md`](local-ci-cd-testing.md)