arcodange/dance-lessons-coach

Fork 0

Files

Gabriel Radureau 3e8c50d80a 📝 docs: comprehensive Swagger documentation skill with hierarchical tagging

2026-04-05 10:37:48 +02:00

28 KiB

Raw Blame History

DanceLessonsCoach - AI Agent Documentation

This file documents the AI agents, tools, and development workflow for the DanceLessonsCoach project.

🎯 Project Overview

DanceLessonsCoach is a Go-based web service with CLI capabilities, featuring:

RESTful JSON API with Chi router
High-performance Zerolog logging
Interface-based architecture
Context-aware services
Comprehensive testing

📋 Development Timeline

Phase 1: Foundation (Completed ✅)

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 (Completed ✅)

Chi router integration
Versioned API endpoints (/api/v1)
Health endpoint (/api/health)
JSON responses with proper headers

Phase 3: Logging & Architecture (Completed ✅)

Zerolog integration with Trace level
Context-aware logging
Interface-based design patterns
Dependency injection

Phase 4: Documentation & Testing (Completed ✅)

Comprehensive AGENTS.md
README.md with usage instructions
Server management guide
API endpoint documentation

Phase 5: Configuration Management (Completed ✅)

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 (Completed ✅)

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 (Completed ✅)

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 (Completed ✅)

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

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

🛠️ Tools & Technologies

Component	Technology	Version
Language	Go	1.26.1
Router	Chi	v5.2.5
Logging	Zerolog	v1.35.0
Configuration	Viper	v1.21.0
Testing	Standard Library	-
Dependency Management	Go Modules	-
Telemetry	OpenTelemetry	v1.43.0
Tracing	Jaeger	Compatible

🗺️ Project Structure

DanceLessonsCoach/
├── adr/                    # Architecture Decision Records
│   ├── README.md           # ADR guidelines and index
│   ├── 0001-go-1.26.1-standard.md
│   ├── 0002-chi-router.md
│   ├── 0003-zerolog-logging.md
│   ├── 0004-interface-based-design.md
│   ├── 0005-graceful-shutdown.md
│   ├── 0006-configuration-management.md
│   ├── 0007-opentelemetry-integration.md
│   ├── 0008-bdd-testing.md
│   └── 0009-hybrid-testing-approach.md
├── cmd/
│   ├── greet/          # CLI application
│   │   └── main.go
│   └── server/         # Web server
│       └── main.go
├── pkg/
│   ├── config/         # Configuration management
│   │   └── config.go    # Viper-based config
│   ├── greet/          # Core domain logic
│   │   ├── api_v1.go    # API handlers
│   │   ├── greet.go     # Service implementation
│   │   └── greet_test.go # Unit tests
│   ├── server/         # HTTP server
│   │   └── server.go
│   └── telemetry/       # OpenTelemetry instrumentation
│       └── telemetry.go
├── go.mod              # Dependencies
├── go.sum              # Dependency checksums
├── config.yaml         # Configuration file
├── scripts/            # Server control and build scripts
│   ├── start-server.sh  # Server lifecycle management
│   ├── build.sh        # Binary compilation
│   └── test-opentelemetry.sh # OpenTelemetry testing
├── README.md           # User documentation
├── AGENTS.md           # This file
└── .gitignore          # Ignore patterns

🚀 Server Management

Using the Server Control Script

A convenient shell script is provided for managing the server lifecycle:

# Navigate to project directory
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach

# Start the server
./scripts/start-server.sh start

# Check server status
./scripts/start-server.sh status

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

# View server logs
./scripts/start-server.sh logs

# Stop the server
./scripts/start-server.sh stop

Server Control Script Commands:

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

If you prefer manual control:

# Navigate to project directory
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach

# Run server in background using control script
./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 Management

The server supports flexible configuration through environment variables with the DLC_ prefix:

Available Configuration Options:

Option	Environment Variable	Default Value	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)

Usage Examples:

# 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
./scripts/start-server.sh start

# Enable JSON logging
export DLC_LOGGING_JSON=true
./scripts/start-server.sh start

# Log to file
export DLC_LOGGING_OUTPUT="server.log"
./scripts/start-server.sh start

# Combined: JSON logging to file
export DLC_LOGGING_JSON=true
export DLC_LOGGING_OUTPUT="server.json.log"
./scripts/start-server.sh start

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:

DLC_CONFIG_FILE="/path/to/config.yaml" go run ./cmd/server

Example config.yaml:

server:
  host: "0.0.0.0"
  port: 8080

shutdown:
  timeout: 30s

logging:
  json: false

Configuration Loading:

File-based configuration takes highest precedence
Environment variables override defaults but are overridden by config file
Default values are used when no other configuration is provided
All configuration is validated on startup
Invalid configurations cause server startup failure
Configuration values and source are logged at startup

Verification:

# Test with custom configuration
DLC_SERVER_PORT=9090 DLC_SERVER_HOST="127.0.0.1" ./scripts/start-server.sh start

# Verify it's running on the custom port
curl http://127.0.0.1:9090/api/health
# Expected: {"status":"healthy"}

Checking Server Status

# 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} with 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:

# Send SIGTERM for graceful shutdown
kill -TERM $(lsof -ti :8080)

# Or send SIGINT (Ctrl+C equivalent)
pkill -INT -f "go run"

Graceful shutdown process:

Server receives termination signal
Logs shutdown message
Stops accepting new connections
Waits up to 30 seconds for active requests to complete
Closes all connections cleanly
Exits with proper cleanup

For force stop (if graceful shutdown hangs):

kill -9 $(lsof -ti :8080)

Verification:

curl -s http://localhost:8080/api/health
# Should return connection refused

🌐 API Endpoints

Base URL

http://localhost:8080

OpenAPI Documentation

Swagger UI: http://localhost:8080/swagger/ OpenAPI Spec: http://localhost:8080/swagger/doc.json

The API provides interactive documentation using Swagger UI with complete OpenAPI 2.0 specification. All endpoints, request/response models, and validation rules are documented using a hierarchical tagging system.

Features:

Interactive API exploration with hierarchical organization
Try-it-out functionality for all endpoints
Model schemas with examples
Response examples with validation rules
Hierarchical tag structure for better navigation

Generation: Documentation is auto-generated from code annotations using swaggo/swag with the command:

go generate ./pkg/server/

Tag Organization:

API/v1/Greeting - Version 1 greeting endpoints
API/v2/Greeting - Version 2 greeting endpoints
System/Health - Health and readiness endpoints

Hierarchical Benefits:

Clear separation between API domains (API vs System)
Version organization within each domain
Natural hierarchy in Swagger UI
Scalable for future API growth

# Generate documentation
go generate ./pkg/server/

Embedded Documentation: The OpenAPI spec is embedded in the binary using Go's //go:embed directive for single-binary deployment.

Health Check

GET /api/health

Response:

{"status":"healthy"}

Readiness Check

GET /api/ready

Responses:

Normal operation: {"ready":true} (HTTP 200)
During shutdown: {"ready":false} (HTTP 503 Service Unavailable)

Purpose: Indicates whether the server is ready to accept new requests. Returns false during graceful shutdown to allow existing requests to complete while preventing new ones.

Greet Service

GET /api/v1/greet/
GET /api/v1/greet/{name}

Examples:

# Default greeting
curl http://localhost:8080/api/v1/greet/
# Response: {"message":"Hello world!"}

# Personalized greeting
curl http://localhost:8080/api/v1/greet/John
# Response: {"message":"Hello John!"}

# Another example
curl http://localhost:8080/api/v1/greet/Alice
# Response: {"message":"Hello Alice!"}

Greet Service v2 (Feature Flag Enabled)

POST /api/v2/greet

Request Body:

{
  "name": "John"
}

Examples:

# Valid request
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{"name":"John"}'
# Response: {"message":"Hello my friend John!"}

# Empty name (valid, returns default)
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{"name":""}'
# Response: {"message":"Hello my friend!"}

# Missing name field (valid, returns default)
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{}'
# Response: {"message":"Hello my friend!"}

# Name too long (validation error)
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{"name":"ThisNameIsWayTooLongAndShouldFailValidationBecauseItExceedsTheMaximumAllowedLengthOf100Characters!!!!"}'
# Response: {"error":"validation_failed","message":"Invalid request data","details":[{"message":"Name failed validation for 'max' (parameter: 100)"}]}'

Validation Rules:

name: Maximum length 100 characters (optional field)

Feature Flag: Enable with DLC_API_V2_ENABLED=true or in config file with api.v2_enabled: true

🔗 OpenTelemetry & Jaeger Integration

The application supports OpenTelemetry for distributed tracing with Jaeger compatibility.

Configuration

Enable OpenTelemetry in your config.yaml:

telemetry:
  enabled: true
  otlp_endpoint: "localhost:4317"
  service_name: "DanceLessonsCoach"
  insecure: true
  sampler:
    type: "parentbased_always_on"
    ratio: 1.0

Or via environment variables:

export DLC_TELEMETRY_ENABLED=true
export DLC_TELEMETRY_OTLP_ENDPOINT="localhost:4317"
export DLC_TELEMETRY_SERVICE_NAME="DanceLessonsCoach"
export DLC_TELEMETRY_INSECURE=true
export DLC_TELEMETRY_SAMPLER_TYPE="parentbased_always_on"
export DLC_TELEMETRY_SAMPLER_RATIO=1.0

Testing with Jaeger

Start Jaeger in Docker:

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

Start the server with OpenTelemetry enabled:

# Using config file
./scripts/start-server.sh start

# Or with environment variables
DLC_TELEMETRY_ENABLED=true ./scripts/start-server.sh start

Make API requests:

curl http://localhost:8080/api/v1/greet/John

View traces in Jaeger UI: Open http://localhost:16686 and select the "DanceLessonsCoach" service.

Sampler Types

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

Use the provided test script:

./scripts/test-opentelemetry.sh

This script:

Starts Jaeger container
Starts the server with OpenTelemetry
Makes test API calls
Shows Jaeger UI URL
Cleans up on exit

🔧 Development Workflow

1. Check Server Status

curl -s http://localhost:8080/api/health

2. Start Development Server

cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
./scripts/start-server.sh start

3. Test API Endpoints

# Test all endpoints as shown above
curl http://localhost:8080/api/v1/greet/YourName

4. Run Tests

# Run all tests
go test ./...

# Run specific package
go test ./pkg/greet/

5. Build Binaries

The project uses a build script to compile binaries into the bin/ directory:

# Build both server and greet binaries
./scripts/build.sh

# This creates:
# - ./bin/server - The web server binary
# - ./bin/greet  - The CLI greeting tool

Binary Usage:

# Run the server
./bin/server

# Use the greet CLI
./bin/greet          # Output: Hello world!
./bin/greet John     # Output: Hello John!

The bin/ directory is gitignored to prevent binary files from being committed to the repository.

6. Make Changes

Edit source files in pkg/ or cmd/
Follow existing patterns and interfaces
Add tests for new functionality

7. Stop and Restart

./scripts/start-server.sh restart

🧪 Testing

Unit Tests

# Run all tests
go test ./...

# Run with verbose output
go test -v ./...

# Run specific test
go test ./pkg/greet/ -run TestService_Greet

CLI Testing

# Default greeting
go run ./cmd/greet
# Output: Hello world!

# Personalized greeting
go run ./cmd/greet John
# Output: Hello John!

API Testing

# Health check
curl http://localhost:8080/api/health

# Greet endpoints
curl http://localhost:8080/api/v1/greet/John
curl http://localhost:8080/api/v1/greet/

📝 Architecture Decisions

Interface-Based Design

type Greeter interface {
    Greet(ctx context.Context, name string) string
}

Benefits:

Easy mocking for tests
Dependency injection
Multiple implementations
Clear contracts

Context-Aware Services

func (s *Service) Greet(ctx context.Context, name string) string {
    log.Trace().Ctx(ctx).Str("name", name).Msg("Greet function called")
    // ...
}

Benefits:

Request tracing
Cancellation support
Deadline propagation
Metadata passing

Server Context Management

// Root context with cancellation
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Server context with graceful shutdown
serverCtx, serverStop := context.WithCancel(ctx)

// HTTP server with context-aware shutdown
srv := &http.Server{
	Addr:    ":8080",
	Handler: server.Router(),
}

// Graceful shutdown with timeout
shutdownCtx, shutdownCancel := context.WithTimeout(
	context.Background(), 
	30*time.Second
)
defer shutdownCancel()

if err := srv.Shutdown(shutdownCtx); err != nil {
	log.Error().Err(err).Msg("Server shutdown failed")
}

Benefits:

Graceful shutdown handling
Signal-based termination (SIGINT, SIGTERM)
30-second timeout for active connections
Proper resource cleanup
Context propagation throughout server lifecycle

Zerolog Logging

zerolog.SetGlobalLevel(zerolog.TraceLevel)
log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})

Benefits:

High performance
Structured logging
Trace level detail
Color output

Versioned API

router.Route("/api/v1", func(r chi.Router) {
    // v1 endpoints
})

Benefits:

Backward compatibility
Clear versioning
Easy migration
Parallel versions

🔍 Troubleshooting

Port Already in Use

# Find and kill process using port 8080
kill -TERM $(lsof -ti :8080)

Server Not Responding

# Check if running
curl -s http://localhost:8080/api/health

# Restart server using control script
./scripts/start-server.sh restart

Dependency Issues

# Clean and rebuild
go mod tidy
go build ./...

Tests Failing

# Run with verbose output
go test -v ./...

# Check specific test
go test ./pkg/greet/ -run TestName

📚 Code Examples

Adding New API Endpoint

// 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
}

Adding Logging

// 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")

Using Context

// 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()

🎓 Best Practices

Code Organization

Keep handlers thin, move logic to services
Use interfaces for dependencies
Separate route registration from handlers
Group related functionality

Error Handling

Return proper HTTP status codes
Log errors with context
Don't expose internal errors to clients
Use structured error responses

Performance

Use Zerolog's Trace level sparingly in production
Avoid allocations in hot paths
Use context timeouts for external calls
Batch database operations

Testing

Test interfaces, not implementations
Use table-driven tests
Test error cases
Mock dependencies

📈 Future Enhancements

Potential Features

Database integration
Authentication/Authorization
Rate limiting
Metrics and monitoring
Docker containerization
CI/CD pipeline
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

📝 Architecture Decision Records

The project maintains comprehensive Architecture Decision Records (ADRs) that document all major architectural choices. See the adr/ directory for complete documentation.

Key Decisions:

Language: Go 1.26.1 (ADR-0001)
Routing: Chi router (ADR-0002)
Logging: Zerolog (ADR-0003)
Design: Interface-based (ADR-0004)
Shutdown: Graceful with readiness (ADR-0005)
Config: Viper (ADR-0006)
Observability: OpenTelemetry (ADR-0007)
Testing: BDD with Godog (ADR-0008)
Strategy: Hybrid testing (ADR-0009)

Adding New ADRs:

# 1. Copy template
cp adr/0001-go-1.26.1-standard.md adr/0010-new-decision.md

# 2. Edit the new ADR
# 3. Update adr/README.md
# 4. Reference in documentation

📝 Changelog

2026-04-05 - Architecture Documentation

✅ Added comprehensive ADR directory with 9 decision records
✅ Enhanced Zerolog vs Zap analysis in logging ADR
✅ Updated README.md and AGENTS.md with ADR references
✅ Documented hybrid testing approach
✅ Added BDD testing decision record

2026-04-04 - Observability & Testing

✅ OpenTelemetry integration with Jaeger
✅ Middleware-only tracing approach
✅ Comprehensive telemetry configuration
✅ BDD testing framework setup
✅ Hybrid testing strategy documentation

2026-04-03 - Production Readiness

✅ Graceful shutdown with readiness endpoints
✅ Configuration management with Viper
✅ JSON logging configuration
✅ File output logging support
✅ Comprehensive error handling

2026-04-02 - Web API Foundation

✅ Chi router integration
✅ Versioned API endpoints (/api/v1)
✅ Health and readiness endpoints
✅ JSON responses with proper headers
✅ Interface-based design patterns

2026-04-01 - Project Foundation

✅ Go 1.26.1 environment setup
✅ Project structure with cmd/ and pkg/
✅ Core Greet service implementation
✅ CLI interface
✅ Unit tests with table-driven approach

🤖 AI Agent Information

Agent: Mistral Vibe CLI Agent Version: devstral-2 Role: Development Assistant Capabilities:

Code generation and refactoring
Test creation
Documentation
Architecture guidance
Best practices enforcement

📋 Quick Reference

Common Commands

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

# Test API
curl http://localhost:8080/api/v1/greet/John

# Run tests
go test ./...

# Stop server
pkill -f "go"

# CLI usage
go run ./cmd/greet John

Project Structure

cmd/        # Entry points
pkg/        # Core logic
  greet/    # Domain services
  server/   # HTTP server
go.mod      # Dependencies
README.md   # User docs
AGENTS.md   # This file

Key Interfaces

type Greeter interface {
    Greet(ctx context.Context, name string) string
}

type ApiV1Greet interface {
    RegisterRoutes(router chi.Router)
}

📝 Commit Conventions

Follow Conventional Commits for clear communication:

Core Types:

feat: New user-facing feature
fix: Bug fix for users
docs: Documentation changes
style: Code formatting (no functional change)
refactor: Code structure changes
perf: Performance improvements
test: Test additions/corrections
chore: Build process, dependencies, maintenance

Examples:

# New feature
git commit -m "feat: add user authentication"

# Bug fix
git commit -m "fix: prevent race condition in cache"

# Documentation
git commit -m "docs: add API endpoint documentation"

# Maintenance
git commit -m "chore: update dependencies"

# Refactoring
git commit -m "refactor: extract user service from controller"

Optional Emoji Support:

Use gitmoji for visual commit messages
Example: git commit -m "✨ feat: add new API endpoint"

Common Gitmoji Reference:

Emoji	Code	Type	Description
✨	`:sparkles:`	feat	New feature
🐛	`:bug:`	fix	Bug fix
📝	`:memo:`	docs	Documentation
🎨	`:art:`	style	Code formatting
🔧	`:wrench:`	chore	Build/config changes
♻️	`:recycle:`	refactor	Code refactoring
🚀	`:rocket:`	perf	Performance improvements
🔒	`:lock:`	security	Security fixes
📦	`:package:`	dependencies	Dependency changes
🔥	`:fire:`	remove	Remove code/files
🐧	`:penguin:`	linux	Linux-specific changes
🍎	`:apple:`	macos	macOS-specific changes
🪟	`:window:`	windows	Windows-specific changes
🤖	`:robot:`	ci	CI/CD changes
🧪	`:test_tube:`	test	Tests
📈	`:chart_with_upwards_trend:`	analytics	Analytics/SEO
🌐	`:globe_with_meridians:`	i18n	Internationalization
⚡	`:zap:`	performance	Performance improvements

Benefits:

Clear communication of change types
Better git history readability
Tool compatibility (changelog generators, etc.)
Consistent project history
Visual scanning of commit history

📞 Support

For issues or questions:

Check this documentation
Review test cases
Examine existing implementations
Consult Go and Chi documentation
Ask the AI agent for guidance

This documentation provides a complete guide to developing, testing, and maintaining the DanceLessonsCoach project using the established patterns and best practices.

28 KiB Raw Blame History

DanceLessonsCoach - AI Agent Documentation

🎯 Project Overview

📋 Development Timeline

Phase 1: Foundation (Completed ✅)

Phase 2: Web API (Completed ✅)

Phase 3: Logging & Architecture (Completed ✅)

Phase 4: Documentation & Testing (Completed ✅)

Phase 5: Configuration Management (Completed ✅)

Phase 6: Graceful Shutdown (Completed ✅)

Phase 7: OpenTelemetry Integration (Completed ✅)

Phase 8: Build System & Documentation (Completed ✅)

Phase 9: Final Refinements (Completed ✅)

🛠️ Tools & Technologies

🗺️ Project Structure

🚀 Server Management

Using the Server Control Script

Manual Server Management

Configuration Management

Checking Server Status

Stopping the Server

🌐 API Endpoints

Base URL

OpenAPI Documentation

Health Check

Health Check

Readiness Check

Greet Service

Greet Service v2 (Feature Flag Enabled)

🔗 OpenTelemetry & Jaeger Integration

Configuration

Testing with Jaeger

Sampler Types

Testing Script

🔧 Development Workflow

1. Check Server Status

2. Start Development Server

3. Test API Endpoints

4. Run Tests

5. Build Binaries

6. Make Changes

7. Stop and Restart

🧪 Testing

Unit Tests

CLI Testing

API Testing

📝 Architecture Decisions

Interface-Based Design

Context-Aware Services

Server Context Management

Zerolog Logging

Versioned API

🔍 Troubleshooting

Port Already in Use

Server Not Responding

Dependency Issues

Tests Failing

📚 Code Examples

Adding New API Endpoint

Adding Logging

Using Context

🎓 Best Practices

Code Organization

Error Handling

Performance

Testing

📈 Future Enhancements

Potential Features

Architectural Improvements

Completed Features

📝 Architecture Decision Records

📝 Changelog

2026-04-05 - Architecture Documentation

2026-04-04 - Observability & Testing

2026-04-03 - Production Readiness

2026-04-02 - Web API Foundation

2026-04-01 - Project Foundation

🤖 AI Agent Information

📋 Quick Reference

Common Commands

28 KiB

Raw Blame History