dance-lessons-coach/adr/README.md

Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records (ADRs) for the dance-lessons-coach project.

Index of ADRs

Number	Title	Status
0001	Go 1.26.1 Standard	✅ Accepted
0002	Chi Router	✅ Accepted
0003	Zerolog Logging	✅ Accepted
0004	Interface-Based Design	✅ Accepted
0005	Graceful Shutdown	✅ Accepted
0006	Configuration Management	✅ Accepted
0007	OpenTelemetry Integration	✅ Accepted
0008	BDD Testing	✅ Accepted
0009	Hybrid Testing Approach	✅ Accepted
0010	CI/CD Pipeline Design	✅ Accepted
0011	Trunk-Based Development	✅ Accepted
0012	Commit Message Conventions	✅ Accepted
0013	Version Management Lifecycle	✅ Accepted
0014	Swagger Documentation	✅ Accepted
0015	Rate Limiting Strategy	✅ Accepted
0016	Cache Invalidation Strategy	✅ Accepted
0017	JWT Secret Rotation	✅ Accepted
0018	Configuration Hot Reloading	✅ Accepted
0019	BDD Feature Structure	✅ Accepted
0020	Database Migration Strategy	✅ Accepted
0021	API Versioning Strategy	✅ Accepted
0022	Rate Limiting and Cache Strategy	✅ Accepted
0023	Config Hot Reloading	🟡 Proposed
0024	BDD Test Organization and Isolation	🟡 Proposed

What is an ADR?

An ADR is a document that captures an important architectural decision made along with its context and consequences.

Format

Each ADR follows this structure:

# [Short title is a few words]

* Status: [Proposed | Accepted | Deprecated | Superseded]
* Deciders: [List of decision makers]
* Date: [YYYY-MM-DD]

## Context and Problem Statement

[Describe the context and problem statement]

## Decision Drivers

* [Driver 1]
* [Driver 2]
* [Driver 3]

## Considered Options

* [Option 1]
* [Option 2]
* [Option 3]

## Decision Outcome

Chosen option: "[Option 1]" because [justification]

## Pros and Cons of the Options

### [Option 1]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]

### [Option 2]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]

## Links

* [Link type] [Link to ADR]
* [Link type] [Link to ADR]

ADR List

• 0001-go-1.26.1-standard.md - Use Go 1.26.1 as the standard Go version
• 0002-chi-router.md - Use Chi router for HTTP routing
• 0003-zerolog-logging.md - Use Zerolog for structured logging
• 0004-interface-based-design.md - Adopt interface-based design pattern
• 0005-graceful-shutdown.md - Implement graceful shutdown with readiness endpoints
• 0006-configuration-management.md - Use Viper for configuration management
• 0007-opentelemetry-integration.md - Integrate OpenTelemetry for distributed tracing
• 0008-bdd-testing.md - Adopt BDD with Godog for behavioral testing
• 0009-hybrid-testing-approach.md - Combine BDD and Swagger-based testing
• 0010-api-v2-feature-flag.md - API v2 implementation with feature flag control
• 0011-validation-library-selection.md - Selection of go-playground/validator for input validation
• 0012-git-hooks-staged-only-formatting.md - Git hooks format only staged Go files
• 0013-openapi-swagger-toolchain.md - ✅ OpenAPI/Swagger documentation with swaggo/swag (Implemented)
• 0014-grpc-adoption-strategy.md - Hybrid REST/gRPC adoption strategy
• 0015-cli-subcommands-cobra.md - Cobra CLI framework adoption
• 0016-ci-cd-pipeline-design.md - CI/CD pipeline architecture
• 0017-trunk-based-development-workflow.md - Trunk-based development workflow
• 0018-user-management-auth-system.md - User management and authentication system
• 0019-postgresql-integration.md - PostgreSQL database integration
• 0020-docker-build-strategy.md - Docker Build Strategy: Traditional vs Buildx
• 0021-jwt-secret-retention-policy.md - JWT Secret Retention Policy with Configurable TTL and Retention
• 0022-rate-limiting-cache-strategy.md - Rate Limiting and Cache Strategy with Multi-Phase Implementation
• 0023-config-hot-reloading.md - Config Hot Reloading Strategy

How to Add a New ADR

1. Create a new file with the next available number (e.g., 0010-new-decision.md)
2. Follow the template format
3. Update this README.md with the new ADR
4. Commit the changes

Status Legend

• Proposed: Decision is being discussed
• Accepted: Decision has been made and implemented
• Deprecated: Decision is no longer relevant
• Superseded: Decision has been replaced by another ADR