dance-lessons-coach/adr

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 with Godog	✅ Accepted (structure superseded by 0024)
0009	BDD Testing with OpenAPI Documentation	✅ Accepted
0010	API v2 Feature Flag	✅ Accepted
0011	Validation Library (go-playground/validator)	✅ Accepted
0012	Git Hooks: Staged-Only Formatting	✅ Accepted
0013	OpenAPI/Swagger Toolchain (swaggo/swag)	✅ Accepted
0014	gRPC Adoption Strategy	❌ Rejected / Deferred
0015	CLI Subcommands with Cobra	✅ Accepted
0016	CI/CD Pipeline Design	✅ Accepted
0017	Trunk-Based Development Workflow	✅ Accepted
0018	User Management and Auth System	✅ Accepted
0019	PostgreSQL Integration	✅ Accepted (SQLite cleanup pending)
0020	Docker Build Strategy	✅ Accepted
0021	JWT Secret Retention Policy	🟡 Proposed (base JWT done; cleanup job not implemented)
0022	Rate Limiting and Cache Strategy	🟡 Proposed (not implemented — Gitea issue #13)
0023	Config Hot Reloading	🟡 Proposed (not implemented)
0024	BDD Test Organization and Isolation	✅ Accepted
0025	BDD Scenario Isolation Strategies	✅ Accepted (Partial — Phase 2 pending ADR-0022)

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 (structure superseded by 0024)
• 0009-hybrid-testing-approach.md - BDD testing with OpenAPI documentation (SDK layer deferred)
• 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
• 0014-grpc-adoption-strategy.md - gRPC adoption strategy (rejected/deferred)
• 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 (base JWT done; cleanup job proposed)
• 0022-rate-limiting-cache-strategy.md - Rate Limiting and Cache Strategy (not yet implemented — issue #13)
• 0023-config-hot-reloading.md - Config Hot Reloading Strategy (not yet implemented)
• 0024-bdd-test-organization-and-isolation.md - BDD test modular organisation by domain
• 0025-bdd-scenario-isolation-strategies.md - Schema-per-scenario isolation for BDD tests (partial)

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