2.5 KiB
ADR-0001: gRPC as the Primary Communication Interface
Date: 2026-02-09 Status: Accepted Deciders: Rafael Ruiz (CTO, AVAP Technology), MrHouston Engineering
Context
The Brunix Assistance Engine needs a communication protocol to serve AI completions from internal backend services and client applications. The primary requirement is real-time token streaming — the engine must forward Ollama's token output to clients with minimal latency, not buffer the full response.
Secondary requirements:
- Strict API contract enforcement (no schema drift)
- High throughput for potential multi-client scenarios
- Easy introspection and testing in development
Candidates evaluated: REST/HTTP+JSON, gRPC, WebSockets, GraphQL subscriptions.
Decision
Use gRPC with Protocol Buffers (proto3) as the primary interface, exposed on port 50051 (container) / 50052 (host).
The API contract is defined in a single source of truth: Docker/protos/brunix.proto.
An OpenAI-compatible HTTP proxy (openai_proxy.py, port 8000) is provided as a secondary interface to enable integration with standard tooling (continue.dev, LiteLLM, etc.) without modifying the core engine.
Rationale
| Criterion | REST+JSON | gRPC | WebSockets |
|---|---|---|---|
| Streaming support | Requires SSE or chunked | ✅ Native server-side streaming | ✅ Bidirectional |
| Schema enforcement | ❌ Optional (OpenAPI) | ✅ Enforced by protobuf | ❌ None |
| Code generation | Manual or OpenAPI tooling | ✅ Automatic stub generation | Manual |
| Performance | Good | ✅ Better (binary framing) | Good |
| Dev tooling | Excellent | Good (grpcurl, reflection) |
Limited |
| Browser-native | ✅ Yes | ❌ Requires grpc-web proxy | ✅ Yes |
gRPC was chosen because: (1) streaming is a first-class citizen, not bolted on; (2) the proto contract makes API evolution explicit and breaking changes detectable at compile time; (3) stub generation eliminates a class of integration bugs.
The lack of browser-native support is not a concern — all current clients are server-side services or CLI tools.
Consequences
- All API changes require modifying
brunix.protoand regenerating stubs (grpc_tools.protoc). - Client libraries must use the generated stubs or
grpcurl— no curl-based ad-hoc testing of the main API. - The OpenAI proxy adds a second entry point that must be kept in sync with the gRPC interface behavior.
- gRPC reflection is enabled in development. It should be evaluated for disabling in production to reduce the attack surface.