How Provider Clients Are Registered and Managed in WorkWeave Router

WorkWeave Router registers upstream LLM provider clients at startup in the composition root using a centralized mapping strategy that wires concrete implementations to provider names while tracking deployment credentials and passthrough eligibility for intelligent request routing.

WorkWeave Router implements a strict composition root pattern to manage upstream LLM provider integrations. Understanding how provider clients are registered and managed in WorkWeave Router requires examining the initialization flow in cmd/router/main.go, where the system constructs a central registry of provider clients during application startup. This architecture separates provider construction from request handling, enabling the router to support both deployment-keyed and bring-your-own-key (BYOK) authentication modes.

The Provider Contract Architecture

Defining the Client Interface

The foundation of provider management resides in internal/providers/provider.go, which declares the providers.Client interface that every upstream adapter must implement. This file also defines provider constants such as ProviderAnthropic, ProviderOpenAI, and ProviderFireworks, along with translation families that map provider-specific models to internal representations. The interface abstraction allows the proxy service to interact with any LLM provider through a unified API without concerning itself with provider-specific implementation details.

The Registration Flow in the Composition Root

Initialization in cmd/router/main.go

The registration process executes once during application startup in the composition root. The router creates three critical data structures to manage provider state:

• providerMap := make(map[string]providers.Client) – Stores the concrete client instance for each provider name
• envKeyedProviders := make(map[string]struct{}) – Tracks providers configured with deployment-level API keys
• passthroughEligible flags – Marks providers usable via client-supplied tokens when no deployment key exists

Deployment Mode Determination

Before registering providers, the router determines its operational mode. A byokOnly flag indicates whether the instance runs in managed mode with bring-your-own-key restrictions. This flag controls whether the system reads deployment-level API keys from environment variables or forces clients to supply their own credentials for every request.

Provider Registration Patterns

Simple Providers Using the Helper Function

For OpenAI-compatible providers such as Fireworks, Makora, Together, and XAI, the router uses the registerDeploymentKeyedProvider helper function. This function encapsulates the boilerplate logic for checking environment variables, constructing clients, and populating the eligibility collections.

fireworksBaseURL := config.GetOr("FIREWORKS_BASE_URL", openaiCompatProvider.FireworksBaseURL)
registerDeploymentKeyedProvider(
    providerMap,
    envKeyedProviders,
    logger,
    providers.ProviderFireworks,
    "Fireworks",
    "FIREWORKS_API_KEY",
    fireworksBaseURL,
    byokOnly,
    func(key, baseURL string) providers.Client {
        return openaiCompatProvider.NewClientWithModelIDMap(
            key,
            baseURL,
            upstreamIDsForProvider(providers.ProviderFireworks),
        )
    })

As implemented in cmd/router/main.go (lines 271-298), this helper performs four operations: reading the environment variable (unless byokOnly is set), invoking the factory function to create the client, inserting the client into providerMap, and conditionally adding the provider name to envKeyedProviders when a key is present.

Custom Providers with Inline Registration

Providers requiring specialized initialization logic, such as Anthropic, OpenAI, and Google, bypass the helper function for inline registration. The Anthropic registration demonstrates the pattern explicitly:

anthropicKey := ""
if !byokOnly {
    anthropicKey = config.GetOr("ANTHROPIC_API_KEY", "")
}
providerMap[providers.ProviderAnthropic] = anthropic.NewClient(anthropicKey, anthropic.DefaultBaseURL)

switch {
case byokOnly:
    logger.Info("Anthropic provider enabled (BYOK only)", "base_url", anthropic.DefaultBaseURL)
case anthropicKey != "":
    envKeyedProviders[providers.ProviderAnthropic] = struct{}{}
    logger.Info("Anthropic provider enabled (router key)", "base_url", anthropic.DefaultBaseURL)
default:
    anthropicPassthroughEligible = true
    logger.Info("Anthropic provider enabled (client auth passthrough)", "base_url", anthropic.DefaultBaseURL)
}

This inline approach, located at lines 90-108 in the main entry point, allows for provider-specific constructor arguments while maintaining consistent state tracking across the three management collections.

Deployment Modes and Eligibility Tracking

Self-Hosted vs Managed Mode

The router distinguishes between self-hosted deployments, where API keys may reside in environment variables, and managed deployments running BYOK-only mode. When byokOnly evaluates to true, the system skips environment variable lookups entirely, forcing authentication to occur through client-supplied Authorization headers.

Passthrough Eligibility for Client Credentials

In self-hosted scenarios lacking deployment keys, certain providers remain accessible via passthrough authentication. The system sets boolean flags such as anthropicPassthroughEligible and openaiPassthroughEligible during registration, later merging these into the passthroughEligible collection passed to the proxy service. This mechanism enables the router to route requests to providers like Anthropic and OpenAI even when no deployment-level credentials exist, provided the client includes valid API keys in the request headers.

Validation and Service Injection

Startup Validation

After completing registration, the router validates the configuration using providers.ValidateDispatchable. This function, defined in internal/providers/provider.go (lines 57-73), verifies that every registered provider possesses a corresponding entry in the ProviderFamilies translation map. If validation fails, the router panics during boot, preventing runtime 502 errors from misconfigured provider mappings.

Injecting the Registry into the Proxy Service

The final step injects the fully constructed registries into the request handling layer:

proxySvc := proxy.NewService(
    routeEntry,
    providerMap,
    telemetryEmitter,
    embedOnlyUser,
    semanticCache,
    pinStore,
    hardPinExplore,
    hardPinProvider,
    hardPinModel,
    repo.Telemetry,
).WithDeploymentKeyedProviders(envKeyedProviders).
  WithPassthroughEligibleProviders(passthroughEligible)

This injection occurs at lines 1414-1417 in cmd/router/main.go, transferring ownership of the provider map and eligibility sets to the proxy service. The proxy uses these structures to resolve providers for incoming requests, respecting deployment-key priority, BYOK restrictions, and per-request provider overrides.

Summary

• WorkWeave Router registers all provider clients at startup in cmd/router/main.go using a composition root pattern that separates construction from runtime request handling.
• The system maintains three critical collections: providerMap for concrete client storage, envKeyedProviders for deployment-credentialed providers, and passthroughEligible for client-auth scenarios.
• Registration follows either a helper-function pattern for OpenAI-compatible providers or inline initialization for custom providers like Anthropic and Google.
• The byokOnly flag controls whether the router uses deployment-level API keys or forces clients to supply their own credentials.
• Startup validation via providers.ValidateDispatchable ensures every registered provider has a valid translation family mapping, preventing silent failures during request processing.

Frequently Asked Questions

What is the composition root pattern in WorkWeave Router?

The composition root pattern centralizes all provider client construction in cmd/router/main.go, ensuring that dependencies are created and wired together at application startup rather than during request processing. This approach keeps the proxy service agnostic of provider construction details while enabling strict dependency management and testing isolation.

How does WorkWeave Router handle missing deployment API keys?

When a deployment-level API key is absent and the router runs in self-hosted mode, the system marks the provider as passthrough-eligible if supported. Clients can then route requests through the router using their own API keys in the Authorization header. If the router operates in BYOK-only mode, missing deployment keys simply result in the provider being unavailable for deployment-keyed routing, though passthrough remains possible for eligible providers.

What happens if a provider is registered without a translation family entry?

The router calls providers.ValidateDispatchable after registration to verify that every provider in providerMap has a corresponding entry in the ProviderFamilies map. If a provider lacks this mapping, the application panics during startup with a clear error message, preventing the system from accepting requests it cannot properly route or translate.

Can new providers be registered at runtime?

No. WorkWeave Router follows a static registration model where all providers must be configured and instantiated during the startup sequence in cmd/router/main.go. The providerMap is immutable after construction and injected into the proxy service, requiring an application restart to add or modify upstream LLM providers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}