plano/docs/ADR/001-envoy-as-data-plane.md

# ADR 001: Envoy as the Data Plane

**Status:** Accepted

## Context

Plano needs to proxy all traffic between clients, LLM providers, and developer APIs. The options were:
1. Build a custom proxy from scratch in Rust (e.g., using `hyper`/`axum` directly)
2. Use an existing L7 proxy (Envoy, NGINX, HAProxy) and extend it
3. Use a service mesh sidecar approach

We need: TLS termination, connection pooling, retry policies, load balancing, header-based routing, streaming support (SSE), compression, and observability — all at production quality.

## Decision

Use **Envoy Proxy** as the data plane. All external traffic — both inbound client requests and outbound LLM/API calls — flows through Envoy. The native Rust service (Brightstaff) never makes direct outbound connections to external hosts.

## Consequences

**Enables:**
- Production-grade L7 proxying (TLS, HTTP/2, connection pooling, retries) without building it ourselves
- WASM filter extension model for inline request/response processing
- Standard observability (access logs, stats, tracing) out of the box
- Header-based routing via Envoy's route configuration — no custom routing code needed for cluster selection
- Hot-restart and graceful draining for zero-downtime updates

**Requires:**
- All Brightstaff external calls must go through Envoy listeners (localhost:12001 for LLMs, localhost:11000 for APIs)
- Custom headers (`x-arch-*`) for routing decisions — Envoy matches on these in its route config
- Envoy configuration must be generated from user config (Jinja2 template → envoy.yaml)
- Team must understand Envoy's configuration model (listeners, clusters, filter chains)

**Prevents:**
- Direct HTTP calls from Brightstaff to external services (this is intentional — it ensures all traffic gets WASM filter processing, auth injection, rate limiting, and observability)
- Simple single-binary deployment (we need Envoy + Brightstaff, managed by Supervisord)