arcodange/dance-lessons-coach
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

📝 docs: cherry-pick 6 focused guides from PR #17 (CLI, CODE_EXAMPLES, HISTORY, OBSERVABILITY, ROADMAP, TROUBLESHOOTING)

Browse Source
This commit is contained in:
Gabriel Radureau
2026-05-06 06:37:07 +02:00
parent da51883c88
commit 93d637d93e
6 changed files with 634 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
documentation/CLI.md Normal file
View File

@@ -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
```

59
documentation/CODE_EXAMPLES.md Normal file
View File

@@ -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".

83
documentation/HISTORY.md Normal file
View File

@@ -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/).

94
documentation/OBSERVABILITY.md Normal file
View File

@@ -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).

40
documentation/ROADMAP.md Normal file
View File

@@ -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/<NNNN>-<slug>.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)

107
documentation/TROUBLESHOOTING.md Normal file
View File

@@ -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)