# launchdarkly/ld-relay architecture

> Architecture diagram of the GitHub repository launchdarkly/ld-relay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/launchdarkly/ld-relay
- Repository: https://github.com/launchdarkly/ld-relay

## Overview

LaunchDarkly Relay Proxy accepts SDK connections, maintains upstream LaunchDarkly streams, and serves/proxies flag data and related services to many clients. Its main request path is HTTP routing through Relay to environment-specific contexts, while environment data can also arrive through automatic configuration or offline archives. It additionally supports event forwarding, persistent flag and Big Segment storage, and OTLP observability. Edges are limited to relationships shown in excerpts or documented in the README; unsampled subsystems are represented without guessed internal call chains.

Main entry points: [`internal/relayenv/env_context_impl.go`](https://github.com/launchdarkly/ld-relay/blob/v9/internal/relayenv/env_context_impl.go) (Environment context), [`relay/relay_routes.go`](https://github.com/launchdarkly/ld-relay/blob/v9/relay/relay_routes.go) (Endpoint router), [`internal/streams/stream_provider_server_side.go`](https://github.com/launchdarkly/ld-relay/blob/v9/internal/streams/stream_provider_server_side.go) (Stream providers), [`internal/autoconfig/stream_manager.go`](https://github.com/launchdarkly/ld-relay/blob/v9/internal/autoconfig/stream_manager.go) (Auto-config stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and routing"]
  node_relay_server["HTTP server<br/>[server.go]"]
  node_route_handlers["Endpoint router<br/>[relay_routes.go]"]
  node_relay_core["Relay core<br/>[relay.go]"]
end

subgraph group_environment["Environment lifecycle"]
  node_env_context["Environment context"]
  node_env_factory["Environment factory<br/>[env_rep.go]"]
  node_project_router["Project router<br/>[project_router.go]"]
end

subgraph group_delivery["Streaming and data"]
  node_stream_providers["Stream providers"]
  node_stream_events["Stream events<br/>[stream_events.go]"]
  node_event_forwarding["Event forwarding<br/>[event_publisher.go]"]
  node_sdk_clients_internal["Server SDK client<br/>[client_factory.go]"]
end

subgraph group_enterprise["Enterprise features"]
  node_autoconfig_stream["Auto-config stream<br/>[stream_manager.go]"]
  node_autoconfig_cache[("Auto-config cache<br/>[dynamodb_store.go]")]
  node_offline_archive["Offline archive<br/>[archive_manager.go]"]
end

subgraph group_operations["Storage and observability"]
  node_flag_store[("Persistent flag store<br/>[data_stores.go]")]
  node_big_segments["Big Segments sync<br/>[sync.go]"]
  node_big_segment_store[("Big Segment store<br/>[store.go]")]
  node_status_metrics["Status metrics<br/>[status_measures.go]"]
  node_otel_export["OTLP telemetry<br/>[otlp.go]"]
end

node_sdk_clients(("SDK clients"))
node_launchdarkly(("LaunchDarkly services"))
node_persistent_backends[("Redis / DynamoDB / Consul")]
node_telemetry_backend(("OTLP backend"))

node_relay_server -->|"serves routes"| node_route_handlers
node_sdk_clients -->|"HTTP requests"| node_route_handlers
node_route_handlers -->|"uses contexts"| node_env_context
node_env_context -.->|"creates SDK client"| node_sdk_clients_internal
node_env_context -->|"registers streams"| node_stream_providers
node_stream_providers -.->|"streams updates"| node_sdk_clients
node_sdk_clients_internal -.->|"uses data store"| node_flag_store
node_flag_store -.->|"persists flag data"| node_persistent_backends
node_launchdarkly -->|"upstream stream"| node_stream_providers
node_launchdarkly -.->|"receives events"| node_event_forwarding
node_event_forwarding -.->|"forwards events"| node_launchdarkly
node_env_context -->|"starts sync"| node_big_segments
node_big_segments -.->|"writes segments"| node_big_segment_store
node_big_segment_store -.->|"persists segments"| node_persistent_backends
node_autoconfig_stream -->|"parses environments"| node_env_factory
node_autoconfig_stream -.->|"caches updates"| node_autoconfig_cache
node_project_router -->|"routes environment data"| node_env_factory
node_offline_archive -.->|"supplies offline data"| node_env_context
node_env_context -->|"registers metrics"| node_status_metrics
node_status_metrics -.->|"exports measures"| node_otel_export
node_otel_export -.->|"exports OTLP"| node_telemetry_backend

click node_relay_server "https://github.com/launchdarkly/ld-relay/blob/v9/internal/application/server.go"
click node_route_handlers "https://github.com/launchdarkly/ld-relay/blob/v9/relay/relay_routes.go"
click node_relay_core "https://github.com/launchdarkly/ld-relay/blob/v9/relay/relay.go"
click node_env_context "https://github.com/launchdarkly/ld-relay/blob/v9/internal/relayenv/env_context_impl.go"
click node_env_factory "https://github.com/launchdarkly/ld-relay/blob/v9/internal/envfactory/env_rep.go"
click node_project_router "https://github.com/launchdarkly/ld-relay/blob/v9/internal/projmanager/project_router.go"
click node_autoconfig_stream "https://github.com/launchdarkly/ld-relay/blob/v9/internal/autoconfig/stream_manager.go"
click node_autoconfig_cache "https://github.com/launchdarkly/ld-relay/blob/v9/internal/autoconfigcache/dynamodb_store.go"
click node_offline_archive "https://github.com/launchdarkly/ld-relay/blob/v9/internal/filedata/archive_manager.go"
click node_stream_providers "https://github.com/launchdarkly/ld-relay/blob/v9/internal/streams/stream_provider_server_side.go"
click node_stream_events "https://github.com/launchdarkly/ld-relay/blob/v9/internal/streams/stream_events.go"
click node_event_forwarding "https://github.com/launchdarkly/ld-relay/blob/v9/internal/events/event_publisher.go"
click node_sdk_clients_internal "https://github.com/launchdarkly/ld-relay/blob/v9/internal/sdks/client_factory.go"
click node_flag_store "https://github.com/launchdarkly/ld-relay/blob/v9/internal/sdks/data_stores.go"
click node_big_segments "https://github.com/launchdarkly/ld-relay/blob/v9/internal/bigsegments/sync.go"
click node_big_segment_store "https://github.com/launchdarkly/ld-relay/blob/v9/internal/bigsegments/store.go"
click node_status_metrics "https://github.com/launchdarkly/ld-relay/blob/v9/internal/metrics/status_measures.go"
click node_otel_export "https://github.com/launchdarkly/ld-relay/blob/v9/internal/metrics/otlp.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_relay_server,node_route_handlers,node_relay_core,node_sdk_clients toneBlue
class node_env_context,node_env_factory,node_project_router,node_persistent_backends toneAmber
class node_stream_providers,node_stream_events,node_event_forwarding,node_sdk_clients_internal toneMint
class node_autoconfig_stream,node_autoconfig_cache,node_offline_archive toneRose
class node_flag_store,node_big_segments,node_big_segment_store,node_status_metrics,node_otel_export,node_launchdarkly,node_telemetry_backend toneIndigo
```

## Components

### Runtime and routing

- [HTTP server](https://github.com/launchdarkly/ld-relay/blob/v9/internal/application/server.go): `internal/application/server.go`
- [Endpoint router](https://github.com/launchdarkly/ld-relay/blob/v9/relay/relay_routes.go): `relay/relay_routes.go`
- [Relay core](https://github.com/launchdarkly/ld-relay/blob/v9/relay/relay.go): `relay/relay.go`

### Environment lifecycle

- [Environment context](https://github.com/launchdarkly/ld-relay/blob/v9/internal/relayenv/env_context_impl.go): `internal/relayenv/env_context_impl.go`
- [Environment factory](https://github.com/launchdarkly/ld-relay/blob/v9/internal/envfactory/env_rep.go): `internal/envfactory/env_rep.go`
- [Project router](https://github.com/launchdarkly/ld-relay/blob/v9/internal/projmanager/project_router.go): `internal/projmanager/project_router.go`

### Streaming and data

- [Stream providers](https://github.com/launchdarkly/ld-relay/blob/v9/internal/streams/stream_provider_server_side.go): `internal/streams/stream_provider_server_side.go`
- [Stream events](https://github.com/launchdarkly/ld-relay/blob/v9/internal/streams/stream_events.go): `internal/streams/stream_events.go`
- [Event forwarding](https://github.com/launchdarkly/ld-relay/blob/v9/internal/events/event_publisher.go): `internal/events/event_publisher.go`
- [Server SDK client](https://github.com/launchdarkly/ld-relay/blob/v9/internal/sdks/client_factory.go): `internal/sdks/client_factory.go`

### Enterprise features

- [Auto-config stream](https://github.com/launchdarkly/ld-relay/blob/v9/internal/autoconfig/stream_manager.go): `internal/autoconfig/stream_manager.go`
- [Auto-config cache](https://github.com/launchdarkly/ld-relay/blob/v9/internal/autoconfigcache/dynamodb_store.go): `internal/autoconfigcache/dynamodb_store.go`
- [Offline archive](https://github.com/launchdarkly/ld-relay/blob/v9/internal/filedata/archive_manager.go): `internal/filedata/archive_manager.go`

### Storage and observability

- [Persistent flag store](https://github.com/launchdarkly/ld-relay/blob/v9/internal/sdks/data_stores.go): `internal/sdks/data_stores.go`
- [Big Segments sync](https://github.com/launchdarkly/ld-relay/blob/v9/internal/bigsegments/sync.go): `internal/bigsegments/sync.go`
- [Big Segment store](https://github.com/launchdarkly/ld-relay/blob/v9/internal/bigsegments/store.go): `internal/bigsegments/store.go`
- [Status metrics](https://github.com/launchdarkly/ld-relay/blob/v9/internal/metrics/status_measures.go): `internal/metrics/status_measures.go`
- [OTLP telemetry](https://github.com/launchdarkly/ld-relay/blob/v9/internal/metrics/otlp.go): `internal/metrics/otlp.go`

### Other components

- **SDK clients**
- **LaunchDarkly services**
- **Redis / DynamoDB / Consul**
- **OTLP backend**

## Connections

- HTTP server → Endpoint router: serves routes (evidence: `internal/application/server.go`)
- SDK clients → Endpoint router: HTTP requests (evidence: `relay/relay_routes.go`)
- Endpoint router → Environment context: uses contexts (evidence: `relay/relay_routes.go`)
- Environment context → Server SDK client: creates SDK client
- Environment context → Stream providers: registers streams (evidence: `internal/relayenv/env_context_impl.go`)
- Stream providers → SDK clients: streams updates
- Server SDK client → Persistent flag store: uses data store
- Persistent flag store → Redis / DynamoDB / Consul: persists flag data
- LaunchDarkly services → Stream providers: upstream stream
- LaunchDarkly services → Event forwarding: receives events
- Event forwarding → LaunchDarkly services: forwards events
- Environment context → Big Segments sync: starts sync (evidence: `internal/relayenv/env_context_impl.go`)
- Big Segments sync → Big Segment store: writes segments
- Big Segment store → Redis / DynamoDB / Consul: persists segments
- Auto-config stream → Environment factory: parses environments (evidence: `internal/autoconfig/stream_manager.go`)
- Auto-config stream → Auto-config cache: caches updates (evidence: `internal/autoconfig/stream_manager.go`)
- Project router → Environment factory: routes environment data (evidence: `internal/projmanager/project_router.go`)
- Offline archive → Environment context: supplies offline data
- Environment context → Status metrics: registers metrics (evidence: `internal/relayenv/env_context_impl.go`)
- Status metrics → OTLP telemetry: exports measures
- OTLP telemetry → OTLP backend: exports OTLP