adr/0011-validation-library-selection.md

@@ -0,0 +1,36 @@
+# 11. Validation Library Selection
+
+* Status: Accepted
+* Deciders: Gabriel Radureau, AI Agent
+* Date: 2026-04-05
+* Implementation Date: 2026-04-05
+
+## Context and Problem Statement
+
+The dance-lessons-coach application needs input validation for API request bodies and configuration values. We need a library that integrates well with Go structs and provides clear error messages.
+
+## Decision Drivers
+
+* Struct-tag-based validation to avoid boilerplate
+* Good error messages with field-level detail
+* Active maintenance and wide adoption
+* Compatibility with existing interface-based design
+
+## Considered Options
+
+* `github.com/go-playground/validator/v10` — struct-tag driven, widely adopted
+* `github.com/asaskevich/govalidator` — tag-based but less expressive
+* Manual validation — full control, no dependency, high boilerplate
+
+## Decision Outcome
+
+Chosen option: **`go-playground/validator/v10`** because it is the de-facto standard in the Go ecosystem, supports struct-tag annotations, provides field-level error detail, and integrates cleanly with our interface-based design.
+
+## Implementation
+
+`github.com/go-playground/validator/v10 v10.30.2` is present in `go.mod`.
+The `pkg/validation/` package wraps the validator for reuse across handlers.
+
+## Links
+
+* [go-playground/validator GitHub](https://github.com/go-playground/validator)

adr/0014-grpc-adoption-strategy.md

@@ -0,0 +1,44 @@
+# 14. gRPC Adoption Strategy
+
+* Status: Rejected / Deferred
+* Deciders: Gabriel Radureau, AI Agent
+* Date: 2026-04-05
+
+## Context and Problem Statement
+
+As the API grows, gRPC was evaluated as an alternative or complement to REST for internal service communication. The question was whether to adopt gRPC alongside the existing Chi REST API.
+
+## Decision Drivers
+
+* Performance of inter-service communication
+* Type safety via Protocol Buffers
+* Streaming support
+* Team familiarity and operational overhead
+
+## Considered Options
+
+* **Hybrid REST/gRPC** — add gRPC endpoints alongside existing REST endpoints
+* **REST only** — maintain current Chi router approach
+* **gRPC-first with transcoding** — use bufbuild/connect for unified REST+gRPC
+
+## Decision Outcome
+
+Chosen option: **REST only (deferred)**. gRPC adoption is not warranted at the current scale. The application has a small number of endpoints, a single-binary deployment model, and no internal service mesh that would benefit from gRPC's efficiency.
+
+### Reasons for deferral
+
+1. **No inter-service communication today** — the application is a single binary; gRPC's main benefit (efficient binary RPC between services) does not apply
+2. **Complexity cost** — adding Protobuf toolchain, code generation, and a second transport layer would significantly increase cognitive overhead
+3. **Chi router commitment** — the REST API is well-designed with OpenAPI documentation; introducing gRPC in parallel creates dual-maintenance burden
+4. **Team capacity** — limited bandwidth for large architectural changes
+
+## When to reconsider
+
+* Application evolves into multiple services that need efficient internal RPC
+* Streaming use cases emerge (real-time lesson progress, etc.)
+* External consumers explicitly require gRPC endpoints
+
+## Links
+
+* [ADR-0002: Chi Router](0002-chi-router.md)
+* [ADR-0013: OpenAPI/Swagger Toolchain](0013-openapi-swagger-toolchain.md)