55 lines
2.5 KiB
Markdown
55 lines
2.5 KiB
Markdown
# ADR-0001: gRPC as the Primary Communication Interface
|
|
|
|
**Date:** 2026-02-09
|
|
**Status:** Accepted
|
|
**Deciders:** Rafael Ruiz (CTO, AVAP Technology)
|
|
|
|
---
|
|
|
|
## 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.proto` and 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.
|