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