Files

Gabriel Radureau 95596b5e12 📝 docs: consolidate documentation and add comprehensive ADRs\n\n## Summary\nMajor documentation restructuring to improve clarity, reduce redundancy,

and preserve complete architectural context for AI/developer reference.\n\n## Changes\n\n### Documentation Consolidation 🗂️\n- Simplified README.md by ~100 lines (25% reduction)\n- Removed redundant sections (project structure, configuration, API docs)\n- Added strategic cross-references between README.md and AGENTS.md\n- README.md now focused on user onboarding and basic usage\n- AGENTS.md maintained as complete technical reference\n\n### Architecture Decision Records ✅\n- Added comprehensive ADR directory with 9 decision records:\n  * 0001-go-1.26.1-standard.md\n  * 0002-chi-router.md\n  * 0003-zerolog-logging.md (enhanced with Zap analysis)\n  * 0004-interface-based-design.md\n  * 0005-graceful-shutdown.md\n  * 0006-configuration-management.md\n  * 0007-opentelemetry-integration.md\n  * 0008-bdd-testing.md\n  * 0009-hybrid-testing-approach.md\n- Added adr/README.md with guidelines and template\n- Enhanced Zerolog ADR with detailed performance benchmarking vs Zap\n\n### Content Organization 📝\n- README.md: User-focused guide with quick start and basic examples\n- AGENTS.md: Developer/AI-focused complete technical reference\n- ADR directory: Architectural decision history and rationale\n\n## Impact\n- ✅ Better user onboarding experience\n- ✅ Preserved complete technical context for AI agents\n- ✅ Reduced maintenance burden through consolidation\n- ✅ Improved discoverability of advanced documentation\n- ✅ Established ADR process for future decisions\n\n## Related\n- Resolves documentation redundancy issues\n- Prepares for BDD implementation with clear context\n- Supports future Swagger integration decisions\n- Maintains project history for new contributors\n\nGenerated by Mistral Vibe.\nCo-Authored-By: Mistral Vibe <vibe@mistral.ai>

2026-04-04 15:48:27 +02:00

3.0 KiB

Raw Blame History

DanceLessonsCoach

A Go project demonstrating idiomatic package structure, CLI implementation, and JSON API with Chi router.

Features

Greet function with default behavior
Command-line interface
JSON API with versioned endpoints
Chi router integration
Zerolog for high-performance logging
Viper for configuration management
Graceful shutdown with context
Readiness endpoint for Kubernetes/service mesh integration
OpenTelemetry integration with Jaeger support
Unit tests
Go 1.26.1 compatible

Installation

# Clone the repository
git clone https://github.com/yourusername/DanceLessonsCoach.git
cd DanceLessonsCoach

# Build and run
go run ./cmd/greet

Configuration

Basic configuration options:

# Start with default configuration
./scripts/start-server.sh start

# Custom port
export DLC_SERVER_PORT=9090
./scripts/start-server.sh start

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

See AGENTS.md for comprehensive configuration guide including:

File-based configuration
Environment variables
Configuration priority rules
OpenTelemetry setup
Advanced scenarios

Usage

CLI

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

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

Web Server

Using the server control script (recommended):

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

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

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

Manual server management:

# Start the server
go run ./cmd/server

# Test API endpoints
curl http://localhost:8080/api/health
# Output: {"status":"healthy"}

curl http://localhost:8080/api/ready
# Output: {"ready":true}

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

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

Testing

# Run all tests
go test ./...

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

Project Structure

DanceLessonsCoach/
├── adr/                    # Architecture Decision Records
├── cmd/                    # Entry points (greet CLI, server)
├── pkg/                    # Core packages (config, greet, server, telemetry)
├── config.yaml             # Configuration file
├── scripts/                # Management scripts
└── go.mod                   # Go module definition

See AGENTS.md for detailed structure and component explanations.


## Architecture

This project uses Architecture Decision Records (ADRs) to document key technical choices. See [adr/](adr/) for complete documentation including decisions on Go 1.26.1, Chi router, Zerolog, OpenTelemetry, interface-based design, graceful shutdown, configuration management, and testing strategies.

**Adding new decisions?** See [adr/README.md](adr/README.md) for guidelines.

## License

MIT

3.0 KiB Raw Blame History