📝 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
parent 3c1aaea789
commit 95596b5e12
12 changed files with 1471 additions and 98 deletions
--- a/README.md
+++ b/README.md
@@ -11,6 +11,8 @@ A Go project demonstrating idiomatic package structure, CLI implementation, and
 - 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

@@ -25,68 +27,29 @@ cd DanceLessonsCoach
 go run ./cmd/greet
 ```

-## Optional Configuration
+## Configuration

-The project supports configuration via YAML file, environment variables, or defaults.
-Configuration priority: file > environment variables > defaults
-
-### Configuration File
-
-By default, the application looks for `config.yaml` in the current working directory.
-
-Create a `config.yaml` file:
-
-```yaml
-server:
-  host: "0.0.0.0"
-  port: 8080
-shutdown:
-  timeout: 30s
-logging:
-  json: false  # Set to true for JSON format logging
-```
-
-Then start the server:
+Basic configuration options:

 ```bash
-go run ./cmd/server
+# 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
 ```

-### Custom Config File Path
-
-To specify a custom config file path, use the `DLC_CONFIG_FILE` environment variable:
-
-```bash
-# Use a specific config file
-export DLC_CONFIG_FILE="/path/to/your/config.yaml"
-go run ./cmd/server
-
-# Or in one command
-DLC_CONFIG_FILE="/path/to/your/config.yaml" go run ./cmd/server
-```
-
-### Environment Variables
-
-You can also configure via environment variables with `DLC_` prefix:
-
-```bash
-# Set configuration via environment variables
-export DLC_SERVER_HOST="0.0.0.0"
-export DLC_SERVER_PORT=8080
-export DLC_SHUTDOWN_TIMEOUT=30s
-export DLC_LOGGING_JSON=false  # Set to true for JSON format logging
-
-# Start the server
-go run ./cmd/server
-```
-
-### Configuration Priority
-
-1. **File-based configuration** (highest priority)
-2. **Environment variables** (override defaults)
-3. **Default values** (lowest priority)
-
-This means if you have both a config file and environment variables, the file takes precedence.
+**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

@@ -151,25 +114,23 @@ go test ./pkg/greet/

 ```
 DanceLessonsCoach/
-├── cmd/
-│   ├── greet/              # CLI entry point
-│   │   └── main.go
-│   └── server/             # Web server entry point
-│       └── main.go
-├── pkg/
-│   ├── config/             # Configuration management
-│   │   └── config.go
-│   ├── greet/              # Core greet functionality
-│   │   ├── api_v1.go       # API v1 handlers
-│   │   ├── greet.go        # Core service
-│   │   └── greet_test.go    # Unit tests
-│   └── server/             # Server implementation
-│       └── server.go
-├── config.example.yaml     # Configuration template
-├── go.mod                   # Go module definition
-└── README.md                # Project documentation
+├── 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