Gabriel Radureau
95596b5e12
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>
137 lines
3.0 KiB
Markdown
137 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/yourusername/DanceLessonsCoach.git
|
|
cd DanceLessonsCoach
|
|
|
|
# Build and run
|
|
go run ./cmd/greet
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Basic configuration options:
|
|
|
|
```bash
|
|
# 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](AGENTS.md#configuration-management) for comprehensive configuration guide including:**
|
|
- File-based configuration
|
|
- Environment variables
|
|
- Configuration priority rules
|
|
- OpenTelemetry setup
|
|
- Advanced scenarios
|
|
|
|
## Usage
|
|
|
|
### CLI
|
|
|
|
```bash
|
|
# 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):**
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](AGENTS.md#project-structure) 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
|