Gabriel Radureau
73a3af1552
Full pass over all 25 ADRs to align documentation with actual implementation state. Changes by ADR: README index: completely rewritten — previous table mapped numbers to wrong titles from 0010 onward. 0008 (BDD Testing): added note that flat features/ structure and godog CLI invocation are superseded by ADR-0024; framework decision stands. 0009 (Hybrid Testing): renamed from "Combine BDD and Swagger-based testing" to "BDD Testing with OpenAPI Documentation"; clarified that the SDK-testing layer was never built and has no open issue. 0013 (OpenAPI/Swagger): removed leftover merge conflict artifact (=======) and duplicated 60-line block. 0015 (Cobra CLI): fixed status contradiction — body said "Implemented" while footer said "Proposed". Now Accepted. 0018 (User Management): status Proposed → Accepted; system is fully implemented (JWT, bcrypt, GORM repos all present). 0019 (PostgreSQL): status Proposed → Accepted (Partial); added warning that sqlite_repository.go and gorm/driver/sqlite still present contrary to ADR intent. 0021 (JWT Retention): fixed wrong cross-reference (previously cited ADR-0009 "Hybrid Testing" as source of JWT multi-secret support); fixed title number from "10" to "21"; clarified that base JWT is implemented but the retention cleanup job is not. 0022 (Rate Limiting/Cache): added warning block linking to open Gitea issue #13; changed all 20 false ✅ implementation checkboxes to ❌. 0023 (Config Hot Reloading): added note that BDD scenarios exist for this feature but the feature itself is not yet implemented. 0024 (BDD Organization): status Proposed → Accepted; modular domain structure is fully built. 0025 (BDD Scenario Isolation): status Proposed → Accepted (Partial); Phase 1 done, Phase 2 blocked on ADR-0022. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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
- Create a new file with the next available number (e.g.,
0010-new-decision.md) - Follow the template format
- Update this README.md with the new ADR
- 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