diff --git a/adr/0011-validation-library-selection.md b/adr/0011-validation-library-selection.md new file mode 100644 index 0000000..de9ac76 --- /dev/null +++ b/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) diff --git a/adr/0014-grpc-adoption-strategy.md b/adr/0014-grpc-adoption-strategy.md new file mode 100644 index 0000000..eb8d368 --- /dev/null +++ b/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)