# 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](0001-go-1.26.1-standard.md) | Use Go 1.26.1 as the standard Go version | Accepted |
| [0002](0002-chi-router.md) | Use Chi router for HTTP routing | Accepted |
| [0003](0003-zerolog-logging.md) | Use Zerolog for structured logging | Accepted |
| [0004](0004-interface-based-design.md) | Adopt interface-based design pattern | Accepted |
| [0005](0005-graceful-shutdown.md) | Implement graceful shutdown with readiness endpoints | Accepted |
| [0006](0006-configuration-management.md) | Use Viper for configuration management | Accepted |
| [0007](0007-opentelemetry-integration.md) | Integrate OpenTelemetry for distributed tracing | Accepted |
| [0008](0008-bdd-testing.md) | Adopt BDD with Godog for behavioral testing | Accepted |
| [0009](0009-hybrid-testing-approach.md) | Combine BDD and Swagger-based testing | Implemented |
| [0010](0010-api-v2-feature-flag.md) | API v2 Feature Flag Implementation | Accepted |
| [0012](0012-git-hooks-staged-only-formatting.md) | Git Hooks: Staged-Only Formatting | Accepted |
| [0013](0013-openapi-swagger-toolchain.md) | OpenAPI/Swagger Toolchain Selection | Implemented |
| [0015](0015-cli-subcommands-cobra.md) | CLI Subcommands and Flag Management with Cobra | Implemented |
| [0016](0016-ci-cd-pipeline-design.md) | CI/CD Pipeline Design for Multi-Platform Compatibility | Accepted |
| [0017](0017-trunk-based-development-workflow.md) | Trunk-Based Development Workflow for CI/CD Safety | Approved |
| [0018](0018-user-management-auth-system.md) | User Management and Authentication System | Implemented |
| [0019](0019-postgresql-integration.md) | PostgreSQL Database Integration | Implemented |
| [0020](0020-docker-build-strategy.md) | Docker Build Strategy: Traditional vs Buildx | Accepted |
| [0021](0021-jwt-secret-retention-policy.md) | JWT Secret Retention Policy | Implemented |
| [0022](0022-rate-limiting-cache-strategy.md) | Rate Limiting and Cache Strategy | Implemented (Phase 1) |
| [0023](0023-config-hot-reloading.md) | Config Hot Reloading Strategy | Implemented |
| [0024](0024-bdd-test-organization-and-isolation.md) | BDD Test Organization and Isolation Strategy | Implemented |
| [0025](0025-bdd-scenario-isolation-strategies.md) | BDD Scenario Isolation Strategies | Implemented |
| [0026](0026-composite-info-endpoint.md) | Composite Info Endpoint vs Separate Calls | Implemented |
| [0027](0027-ollama-tier1-onboarding.md) | Ollama Tier 1 onboarding via meta-trainer-bootstrap | Proposed |
| [0028](0028-passwordless-auth-migration.md) | Passwordless authentication: magic link → OpenID Connect | Proposed |
| [0029](0029-email-infrastructure-mailpit.md) | Email infrastructure: Mailpit local + production deferred | Proposed |
| [0030](0030-bdd-email-parallel-strategy.md) | BDD email assertions with parallel test execution | 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):

```markdown
# 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.