dance-lessons-coach/adr/README.md

Architecture Decision Records (ADRs)

This directory contains the Architecture Decision Records (ADRs) for the dance-lessons-coach project. Each ADR captures a structurally important decision, its context, and its consequences.

Index

ADR	Title	Status
0001	Use Go 1.26.1 as the standard Go version	Accepted
0002	Use Chi router for HTTP routing	Accepted
0003	Use Zerolog for structured logging	Accepted
0004	Adopt interface-based design pattern	Accepted
0005	Implement graceful shutdown with readiness endpoints	Accepted
0006	Use Viper for configuration management	Accepted
0007	Integrate OpenTelemetry for distributed tracing	Accepted
0008	Adopt BDD with Godog for behavioral testing	Accepted
0009	Combine BDD and Swagger-based testing	Partially Implemented
0010	API v2 Feature Flag Implementation	Accepted
0012	Git Hooks: Staged-Only Formatting	Accepted
0013	OpenAPI/Swagger Toolchain Selection	Partially Implemented
0015	CLI Subcommands and Flag Management with Cobra	Implemented
0016	CI/CD Pipeline Design for Multi-Platform Compatibility	Accepted
0017	Trunk-Based Development Workflow for CI/CD Safety	Approved
0018	User Management and Authentication System	Proposed
0019	PostgreSQL Database Integration	Proposed
0020	Docker Build Strategy: Traditional vs Buildx	Accepted
0021	JWT Secret Retention Policy	Proposed
0022	Rate Limiting and Cache Strategy	Proposed
0023	Config Hot Reloading Strategy	Proposed
0024	BDD Test Organization and Isolation Strategy	Proposed
0025	BDD Scenario Isolation Strategies	Proposed

Note

: numbers 0011 and 0014 are not currently in use. Reserved for future ADRs or representing previously deleted entries.

What is an ADR?

An ADR is a document capturing one significant architectural decision: the context that motivated it, the decision itself, and its consequences. ADRs are append-only — once published, an ADR is not edited (except for typo / status updates). New decisions that supersede previous ones are recorded as new ADRs that explicitly link back.

Canonical Format

All ADRs follow the canonical format below (homogenized 2026-05-03):

# NN. Short title summarising the decision

**Status:** <Proposed | Accepted | Implemented | Partially Implemented | Approved | Rejected | Deferred | Deprecated | Superseded by ADR-NNNN>
**Date:** YYYY-MM-DD
**Authors:** Name(s)

[Optional fields, all in `**Field:** value` format:]
**Decision Drivers:** ...
**Implementation Status:** ...
**Implementation Date:** ...
**Last Updated:** ...

## Context and Problem Statement

[Describe the context and problem statement.]

## Decision Drivers

* Driver 1
* Driver 2

## Considered Options

* Option 1
* Option 2

## Decision Outcome

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

## Pros and Cons of the Options

### Option 1

* Good, because [argument].
* Bad, because [argument].

### Option 2

* Good, because [argument].
* Bad, because [argument].

## Links

* Related ADR: [ADR-NNNN](NNNN-slug.md)
* Issue: [#NN](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/NN)

Status Legend

Status	Meaning
Proposed	Decision is being discussed; no implementation yet.
Accepted	Decision has been made; implementation may be pending or in progress.
Approved	Same as Accepted; alternative term used in some legacy ADRs.
Implemented	Decision is fully implemented and in production.
Partially Implemented	Decision is partly implemented; remainder is deferred or pending.
Rejected	Decision considered and explicitly rejected. The ADR documents why.
Deferred	Decision postponed; revisit later.
Deprecated	Decision is no longer relevant; system has moved on.
Superseded by ADR-NNNN	Decision has been replaced by another ADR. Always include the link.

How to Add a New ADR

1. Pick the next available number (currently next would be 0026).
2. Copy an existing ADR (e.g., 0001-go-1.26.1-standard.md) as a starting template.
3. Edit the title, status, date, authors, and content.
4. Update this README.md index with the new ADR.
5. Commit using gitmoji convention (e.g., 📝 docs(adr): add ADR-0026 about ...).
6. Open a PR for review.