Architecture & Mechanics

Envy separates administrative intent from data-plane execution. It persists state in PostgreSQL and reconciles desired state into Kubernetes and the selected Istio, Cilium, or Linkerd mesh without ever proxying application payloads.

---

High-Level Topology

How Envy configures a preview

The API records desired state in PostgreSQL. The reconciler reads that state and configures Kubernetes workloads and mesh routes. Application requests travel through the mesh, not through the Envy API or database.

Agent / externalEnvy / routingPreview overrideShared baseline

Scroll sideways to follow wider branches, or read the connections below.

Read the connections

• Developer / CI → Envy REST API: authenticated http.
• Coding agent → Envy REST API: authenticated http.
• Envy REST API → PostgreSQL: persist intent.
• PostgreSQL → Reconciler: read desired state.
• Reconciler → Kubernetes: reconcile workloads.
• Reconciler → Mesh: reconcile routes.

---

Existing delivery pipelines

Argo CD can keep maintaining the baseline while Envy creates separate preview workloads from approved Deployment templates. Existing previews retain captured override configuration; inherited services and shared data remain live. See Argo CD & Deployment Previews for ownership, onboarding, and configuration lifecycle.

Control Plane Architecture

The control plane comprises four core layers:

1. REST API (internal/api):

   • Authenticated HTTP interface (Authorization: Bearer <token>).
   • Validates client payloads, handles optional Idempotency-Key headers, and enforces generation constraints.
   • Writes desired state to PostgreSQL and returns 202 Accepted with a polling Location header.

2. Model Context Protocol Adapter (internal/mcp):

   • Thin stdio server that translates MCP tool calls (create_composition, get_composition, etc.) into requests handled by Envy’s HTTP client.
   • Requires zero Kubernetes credentials or cluster-admin permissions.

3. PostgreSQL Persistence Layer (internal/persistence/postgres):

   • Persistent store for all compositions, operations, idempotency records, and audit events.
   • Uses sqlc-generated, type-safe database queries.
   • One active reconciler worker holds a PostgreSQL transaction-safe advisory lock to ensure single-leader consistency.

4. Reconciler Worker (internal/reconciler):

   • Polls durable state and converges Kubernetes and mesh routing objects to match client intent.
   • Reconciles workloads via the Kubernetes provider and routes via the selected mesh provider.
   • Executes real ingress verification checks (internal/verification) to confirm live traffic routing before marking a composition ready.

---

Data Plane & Routing Mechanics

Ingress Routing Contract

When a composition is created, Envy adds a preview endpoint alongside the existing baseline endpoint at the configured ingress controller:

• Baseline Ingress:
  • Hostname: http://baseline.envy.localhost:8080
  • Ingress Behavior: Explicitly strips any inbound baggage headers to prevent context spoofing.
• Composition Preview Ingress:
  • Hostname: http://cmp-<id>.envy.localhost:8080
  • Ingress Behavior: Sets the request header baggage: composition=<id>.
  • Ingress Response Marker: Sets x-envy-route: <id>.

One application, two request paths

Both URLs reuse gateway and service-a. The selected mesh selects service-b v2 only when the request carries the matching composition ID. Both service-b versions connect to the same shared data.

Envy / routingPreview overrideShared baseline

Scroll sideways to follow wider branches, or read the connections below.

Read the connections

• Baseline URL → gateway · v1: baseline request.
• Preview URL → gateway · v1: preview request.
• gateway · v1 → service-a · v1: forward baggage.
• service-a · v1 → service-b · v1: no matching context.
• service-a · v1 → service-b · v2: composition=cmp-123.
• service-b · v1 → Database & cache: read / write.
• service-b · v2 → Database & cache: read / write.

Context Propagation (W3C Baggage)

Envy uses standard W3C Distributed Tracing and Baggage specifications. Microservices in the chain derive outgoing baggage from the incoming HTTP request:

GET /orders HTTP/1.1
Host: service-b.default.svc.cluster.local:8080
baggage: composition=cmp-7f39a
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Applications must extract baggage from incoming requests and inject it into downstream requests. The selected mesh routes using the resulting header; they cannot propagate context between separate application requests. Standard OpenTelemetry instrumentation can handle propagation without an Envy-specific SDK. See the complete HTTP example.

---

Resiliency Guarantees

• Request execution: Envy’s control plane is entirely out-of-band. Once routes are configured, application traffic flows through the mesh data plane.
• Surviving Restarts: If the Envy control plane process restarts or crashes, running compositions continue serving preview traffic without interruption.
• Deterministic Teardown: Deletion intent is persisted transactionally. The reconciler verifies that ingress returns a clean 404 (without the x-envy-route header) before draining and deleting pod workloads.