Gabriel Radureau
8bae62c28e
ADR 0011 and 0014 were referenced in the README list but their files were absent from the repository. Reconstruct them from available context: - 0011: go-playground/validator selection (already implemented in go.mod) - 0014: gRPC adoption strategy (evaluated and deferred/rejected) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
# 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)
|