# 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)