📝 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>

adr/0004-interface-based-design.md

@@ -0,0 +1,95 @@
+# Adopt interface-based design pattern
+
+* Status: Accepted
+* Deciders: Gabriel Radureau, AI Agent
+* Date: 2026-04-02
+
+## Context and Problem Statement
+
+We needed to choose a design pattern for DanceLessonsCoach that provides:
+- Good testability and mocking capabilities
+- Flexibility for future changes
+- Clear separation of concerns
+- Dependency injection support
+- Maintainability and readability
+
+## Decision Drivers
+
+* Need for easy testing and mocking
+* Desire for flexible, maintainable architecture
+* Requirement for clear component boundaries
+* Need for dependency injection
+* Long-term evolution of the codebase
+
+## Considered Options
+
+* Interface-based design - Define interfaces first, implement later
+* Direct implementation - Implement concrete types directly
+* Functional approach - Use functions and composition
+* DDD-style aggregates - Domain-driven design patterns
+
+## Decision Outcome
+
+Chosen option: "Interface-based design" because it provides excellent testability, clear contracts, flexibility for future changes, and good support for dependency injection while maintaining good readability.
+
+## Pros and Cons of the Options
+
+### Interface-based design
+
+* Good, because excellent for testing and mocking
+* Good, because clear component contracts
+* Good, because flexible for future changes
+* Good, because supports dependency injection well
+* Good, because encourages good separation of concerns
+* Bad, because slightly more boilerplate
+* Bad, because can be over-engineered if taken too far
+
+### Direct implementation
+
+* Good, because simpler and more direct
+* Good, because less boilerplate
+* Bad, because harder to test and mock
+* Bad, because less flexible for changes
+* Bad, because tighter coupling
+
+### Functional approach
+
+* Good, because can be very clean and simple
+* Good, because good for pure functions
+* Bad, because less familiar in Go ecosystem
+* Bad, because harder to manage state
+
+### DDD-style aggregates
+
+* Good, because good for complex domains
+* Good, because clear boundaries
+* Bad, because overkill for simple services
+* Bad, because more complex to implement
+
+## Links
+
+* [Go Interfaces](https://go.dev/tour/methods/9)
+* [Effective Go - Interfaces](https://go.dev/doc/effective_go#interfaces)
+* [Dependency Injection in Go](https://go.dev/blog/wire)
+
+## Implementation Examples
+
+```go
+// Good: Interface defined first
+type Greeter interface {
+    Greet(ctx context.Context, name string) string
+}
+
+type Service struct{}
+
+func (s *Service) Greet(ctx context.Context, name string) string {
+    // implementation
+}
+
+// Bad: Direct implementation without interface
+type Service struct{}
+
+func (s *Service) Greet(name string) string {
+    // implementation
+}
+```