# ejnkns/hive architecture

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

- Interactive diagram: https://gitdiagram.com/ejnkns/hive
- Repository: https://github.com/ejnkns/hive

## Overview

1. **What this repo is**
   - `hive` is a local, OpenAI-compatible proxy daemon written in TypeScript for Node.js.
   - Its core role is to sit between coding clients and multiple upstream LLM providers, then choose, retry, and fail over between provider:model nodes automatically.

2. **Top-level runtime shape**
   - The main runtime appears to be centered around `src/hive.ts` and `src/engine.ts`, which likely bootstrap the proxy, telemetry, provider discovery, and dashboard/server pieces.
   - `src/hive/server-config.ts` and `src/hive/create-server/*` define the local server boundary and route wiring.

3. **Request path through the proxy**
   - Incoming OpenAI-style requests enter `src/proxy.ts`.
   - The request is parsed, mutated, routed, and executed against a selected upstream model.
   - The proxy returns a streamed response when successful, or normalizes upstream failures and retries other nodes when needed.

4. **Routing and failover**
   - `src/proxy/node-selector.ts` is the decision point for picking the best provider:model based on current telemetry and session affinity.
   - `src/proxy/failover.ts` handles retrying alternate nodes after failures, with a bounded retry loop.
   - `src/proxy/mutate-request.ts` injects provider-specific auth/headers and adapts the client request to the chosen upstream.

5. **Routing memory and health state**
   - `src/proxy/routing-memory/*` is the in-memory control plane for routing behavior.
   - It includes a **circuit breaker** for temporarily disabling bad providers, **feature discovery** for remembering unsupported capabilities, and a **session registry** for sticking a session to a node when appropriate.

6. **Provider catalog and discovery**
   - `src/providers.ts`, `src/providers/registry.ts`, and the individual provider files under `src/providers/*` define the supported upstreams.
   - The repo supports multiple external model backends, including Groq, SambaNova, Google AI, NVIDIA NIM, GitHub Models, Cerebras, Mistral, OpenCode Zen, Ollama, oMLX, LM Studio, and others.
   - `src/providers/discovery.ts` fetches available models from each provider’s `/models` endpoint at startup and caches the results.

7. **Configuration and startup inputs**
   - Provider API keys and host overrides are loaded from `.env` or environment variables during initialization.
   - `src/hive/load-providers.ts` and `src/hive/manual-override.ts` suggest two config layers: automatic provider loading plus an explicit override path for operator control.
   - `src/id.ts` likely provides stable identity/session IDs used across routing and telemetry.

8. **Telemetry as the feedback loop**
   - `src/telemetry/*` is the scoring and persistence subsystem that feeds routing decisions.
   - It records request outcomes, stream characteristics, latency, throughput, and error classes, then turns them into node scores.
   - `src/telemetry/persist.ts` writes cache data to disk, and the README says this lives under `~/.hive/telemetry-cache.json`.

9. **How scoring is computed**
   - `src/telemetry/calculate-node-score/*` breaks scoring into separate dimensions: latency, throughput, quality, reliability, and auth checks.
   - The system also tracks windows, weights, and derived metrics, so routing can prefer fast and stable nodes rather than just “last successful” ones.
   - Stream parsing and error classification live in `src/telemetry/recorder/*`, which helps distinguish real successes from truncated or failed streams.

10. **Dashboard and operator visibility**
   - The browser UI lives under `src/hive/ui/*` and is served from `src/hive/index.html`.
   - It is a lightweight Web Components dashboard showing provider status, scores, activity, logs, conversations, and stats.
   - `src/hive/create-server/assign-routes.ts` likely exposes both the API surface and the dashboard assets from the same local server.

11. **Logging and shared utilities**
   - `src/hive/shared/logger/*` provides centralized logging and banner output.
   - `src/utils/error-normalizer.ts` and the proxy/telemetry helper modules are cross-cutting support code for keeping upstream failures comparable and actionable.

12. **Repository boundaries to draw in a diagram**
   - One boundary is the **client side**: OpenCode or any OpenAI-compatible client sends requests to hive.
   - A second boundary is the **local hive daemon**: proxy, routing memory, telemetry, provider registry, and dashboard server.
   - A third boundary is the **external provider layer**: multiple third-party LLM APIs and local model servers.
   - The key data loop is: request in → node selection → upstream call → result/error classification → telemetry update → future routing improvement.

13. **Tooling and validation**
   - The project is TypeScript-based and includes tests alongside each major subsystem, indicating behavior is heavily verified at the routing, provider, telemetry, and proxy levels.
   - `vite.config.ts` and the UI folder suggest the dashboard is built and served as a frontend bundle, while the daemon itself is a Node process.

Main entry points: [`src/telemetry.ts`](https://github.com/ejnkns/hive/blob/main/src/telemetry.ts) (Telemetry), [`src/engine.ts`](https://github.com/ejnkns/hive/blob/main/src/engine.ts) (Engine), [`src/proxy/route-request.ts`](https://github.com/ejnkns/hive/blob/main/src/proxy/route-request.ts) (Route req), [`src/providers.ts`](https://github.com/ejnkns/hive/blob/main/src/providers.ts) (Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_requester(("Client<br/>external caller"))
end

subgraph group_daemon["Local daemon"]
  node_hive_ts["Hive<br/>bootstrap<br/>[hive.ts]"]
  node_engine_ts["Engine<br/>runtime orchestrator<br/>[engine.ts]"]
  node_create_server_ts["Server<br/>[create-server.ts]"]
  node_assign_routes_ts["Routes<br/>route wiring<br/>[assign-routes.ts]"]
  node_server_config_ts["Config<br/>[server-config.ts]"]
  node_proxy_ts["Proxy<br/>[proxy.ts]"]
  node_route_request_ts["Route req<br/>request routing<br/>[route-request.ts]"]
  node_node_selector_ts["Select node<br/>routing decision<br/>[node-selector.ts]"]
  node_mutate_request_ts["Mutate req<br/>request adapter<br/>[mutate-request.ts]"]
  node_failover_ts["Failover<br/>retry loop<br/>[failover.ts]"]
  node_routing_memory_ts["Routing memory<br/>control plane state<br/>[routing-memory.ts]"]
  node_ui_app_ts["Dashboard<br/>operator UI<br/>[hive-app.ts]"]
  node_logger_ts["Logger<br/>shared logging<br/>[logger.ts]"]
end

subgraph group_providers["Upstreams"]
  node_providers_ts["Providers<br/>provider catalog<br/>[providers.ts]"]
  node_registry_ts["Registry<br/>[registry.ts]"]
  node_discovery_ts["Discovery<br/>[discovery.ts]"]
  node_provider_impls[("Backends<br/>provider adapters")]
end

subgraph group_telemetry["Telemetry"]
  node_telemetry_ts["Telemetry<br/>feedback loop<br/>[telemetry.ts]"]
  node_recorder_ts["Recorder<br/>[recorder.ts]"]
  node_score_ts["Scoring"]
  node_persist_ts["Persist<br/>telemetry cache<br/>[persist.ts]"]
end

node_client_requester -->|"request"| node_proxy_ts
node_hive_ts -->|"boot"| node_engine_ts
node_engine_ts -->|"start server"| node_create_server_ts
node_create_server_ts -->|"wire routes"| node_assign_routes_ts
node_create_server_ts -->|"config"| node_server_config_ts
node_engine_ts -->|"load"| node_providers_ts
node_engine_ts -->|"init"| node_telemetry_ts
node_engine_ts -->|"serve UI"| node_ui_app_ts
node_proxy_ts -->|"dispatch"| node_route_request_ts
node_route_request_ts -->|"pick node"| node_node_selector_ts
node_route_request_ts -->|"adapt"| node_mutate_request_ts
node_route_request_ts -->|"retry"| node_failover_ts
node_node_selector_ts -->|"consult"| node_routing_memory_ts
node_mutate_request_ts -->|"provider rules"| node_providers_ts
node_providers_ts -->|"normalize"| node_registry_ts
node_registry_ts -->|"discover models"| node_discovery_ts
node_discovery_ts -->|"query /models"| node_provider_impls
node_route_request_ts -->|"record"| node_telemetry_ts
node_telemetry_ts -->|"classify"| node_recorder_ts
node_telemetry_ts -->|"score"| node_score_ts
node_telemetry_ts -->|"cache"| node_persist_ts
node_score_ts -->|"feedback"| node_node_selector_ts
node_routing_memory_ts -->|"state updates"| node_telemetry_ts
node_hive_ts -->|"log"| node_logger_ts
node_ui_app_ts -->|"display"| node_telemetry_ts
node_ui_app_ts -->|"display"| node_providers_ts

click node_hive_ts "https://github.com/ejnkns/hive/blob/main/src/hive.ts"
click node_engine_ts "https://github.com/ejnkns/hive/blob/main/src/engine.ts"
click node_create_server_ts "https://github.com/ejnkns/hive/blob/main/src/hive/create-server.ts"
click node_assign_routes_ts "https://github.com/ejnkns/hive/blob/main/src/hive/create-server/assign-routes.ts"
click node_server_config_ts "https://github.com/ejnkns/hive/blob/main/src/hive/server-config.ts"
click node_proxy_ts "https://github.com/ejnkns/hive/blob/main/src/proxy.ts"
click node_route_request_ts "https://github.com/ejnkns/hive/blob/main/src/proxy/route-request.ts"
click node_node_selector_ts "https://github.com/ejnkns/hive/blob/main/src/proxy/node-selector.ts"
click node_mutate_request_ts "https://github.com/ejnkns/hive/blob/main/src/proxy/mutate-request.ts"
click node_failover_ts "https://github.com/ejnkns/hive/blob/main/src/proxy/failover.ts"
click node_routing_memory_ts "https://github.com/ejnkns/hive/blob/main/src/proxy/routing-memory.ts"
click node_ui_app_ts "https://github.com/ejnkns/hive/blob/main/src/hive/ui/hive-app.ts"
click node_providers_ts "https://github.com/ejnkns/hive/blob/main/src/providers.ts"
click node_registry_ts "https://github.com/ejnkns/hive/blob/main/src/providers/registry.ts"
click node_discovery_ts "https://github.com/ejnkns/hive/blob/main/src/providers/discovery.ts"
click node_telemetry_ts "https://github.com/ejnkns/hive/blob/main/src/telemetry.ts"
click node_recorder_ts "https://github.com/ejnkns/hive/blob/main/src/telemetry/recorder.ts"
click node_score_ts "https://github.com/ejnkns/hive/blob/main/src/telemetry/calculate-node-score.ts"
click node_persist_ts "https://github.com/ejnkns/hive/blob/main/src/telemetry/persist.ts"
click node_logger_ts "https://github.com/ejnkns/hive/blob/main/src/hive/shared/logger.ts"

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_client_requester toneBlue
class node_hive_ts,node_engine_ts,node_create_server_ts,node_assign_routes_ts,node_server_config_ts,node_proxy_ts,node_route_request_ts,node_node_selector_ts,node_mutate_request_ts,node_failover_ts,node_routing_memory_ts,node_ui_app_ts,node_logger_ts toneAmber
class node_providers_ts,node_registry_ts,node_discovery_ts,node_provider_impls toneMint
class node_telemetry_ts,node_recorder_ts,node_score_ts,node_persist_ts toneRose
```

## Components

### Client

OpenAI-compatible coding clients and other callers

- **Client**: external caller · OpenAI-compatible coding client sending requests to hive

### Local daemon

Bootstrap, server, proxy, routing, telemetry, and dashboard runtime

- [Hive](https://github.com/ejnkns/hive/blob/main/src/hive.ts): bootstrap · Main daemon entrypoint · `src/hive.ts`
- [Engine](https://github.com/ejnkns/hive/blob/main/src/engine.ts): runtime orchestrator · Coordinates daemon startup and runtime subsystems · `src/engine.ts`
- [Server](https://github.com/ejnkns/hive/blob/main/src/hive/create-server.ts): server assembly · Builds the local HTTP server and app surface · `src/hive/create-server.ts`
- [Routes](https://github.com/ejnkns/hive/blob/main/src/hive/create-server/assign-routes.ts): route wiring · Attaches API routes and dashboard assets · `src/hive/create-server/assign-routes.ts`
- [Config](https://github.com/ejnkns/hive/blob/main/src/hive/server-config.ts): server config · Defines local server boundary and settings · `src/hive/server-config.ts`
- [Proxy](https://github.com/ejnkns/hive/blob/main/src/proxy.ts): request proxy · Entry point for OpenAI-style request handling · `src/proxy.ts`
- [Route req](https://github.com/ejnkns/hive/blob/main/src/proxy/route-request.ts): request routing · Dispatches a request through selection and execution · `src/proxy/route-request.ts`
- [Select node](https://github.com/ejnkns/hive/blob/main/src/proxy/node-selector.ts): routing decision · Chooses the best provider:model node · `src/proxy/node-selector.ts`
- [Mutate req](https://github.com/ejnkns/hive/blob/main/src/proxy/mutate-request.ts): request adapter · Injects auth and upstream-specific request changes · `src/proxy/mutate-request.ts`
- [Failover](https://github.com/ejnkns/hive/blob/main/src/proxy/failover.ts): retry loop · Retries alternate nodes after upstream failure · `src/proxy/failover.ts`
- [Routing memory](https://github.com/ejnkns/hive/blob/main/src/proxy/routing-memory.ts): control plane state · In-memory routing state for breaker, features, and sessions · `src/proxy/routing-memory.ts`
- [Dashboard](https://github.com/ejnkns/hive/blob/main/src/hive/ui/hive-app.ts): operator UI · Browser dashboard for provider status, logs, and stats · `src/hive/ui/hive-app.ts`
- [Logger](https://github.com/ejnkns/hive/blob/main/src/hive/shared/logger.ts): shared logging · Centralized logging and startup banner output · `src/hive/shared/logger.ts`

### Upstreams

Provider catalog, discovery, and concrete model backends

- [Providers](https://github.com/ejnkns/hive/blob/main/src/providers.ts): provider catalog · Top-level provider definitions and supported backends · `src/providers.ts`
- [Registry](https://github.com/ejnkns/hive/blob/main/src/providers/registry.ts): provider registry · Normalizes provider metadata and access paths · `src/providers/registry.ts`
- [Discovery](https://github.com/ejnkns/hive/blob/main/src/providers/discovery.ts): model discovery · Fetches and caches available models from providers · `src/providers/discovery.ts`
- **Backends**: provider adapters · Concrete upstream adapters such as Groq, Ollama, Mistral, and others

### Telemetry

Scoring, recording, persistence, and routing feedback loop

- [Telemetry](https://github.com/ejnkns/hive/blob/main/src/telemetry.ts): feedback loop · Collects outcomes and feeds routing decisions · `src/telemetry.ts`
- [Recorder](https://github.com/ejnkns/hive/blob/main/src/telemetry/recorder.ts): stream recorder · Classifies stream tokens, errors, and refusal signals · `src/telemetry/recorder.ts`
- [Scoring](https://github.com/ejnkns/hive/blob/main/src/telemetry/calculate-node-score.ts): node scoring · Computes node scores from latency, throughput, reliability, quality, and auth · `src/telemetry/calculate-node-score.ts`
- [Persist](https://github.com/ejnkns/hive/blob/main/src/telemetry/persist.ts): telemetry cache · Writes routing and telemetry cache to disk · `src/telemetry/persist.ts`

## Connections

- Client → Proxy: request · Client sends an OpenAI-compatible request to the daemon
- Hive → Engine: boot · Bootstrap hands control to the runtime engine
- Engine → Server: start server · Engine creates the local server boundary
- Server → Routes: wire routes · Server assembly installs API and dashboard routes
- Server → Config: config · Server uses local configuration and listening settings
- Engine → Providers: load · Engine initializes provider catalog and discovery
- Engine → Telemetry: init · Engine brings up telemetry feedback components
- Engine → Dashboard: serve UI · Engine exposes the operator dashboard
- Proxy → Route req: dispatch · Proxy forwards the request into routing workflow
- Route req → Select node: pick node · Request routing asks for the best upstream node
- Route req → Mutate req: adapt · Request is mutated for the chosen provider
- Route req → Failover: retry · Routing invokes bounded failover after failure
- Select node → Routing memory: consult · Selection uses circuit breaker, features, and session memory
- Mutate req → Providers: provider rules · Mutation depends on provider-specific request shape
- Providers → Registry: normalize · Catalog maps provider implementations into a common registry
- Registry → Discovery: discover models · Registry is populated from provider model discovery
- Discovery → Backends: query /models · Discovery fetches model lists from upstream providers
- Route req → Telemetry: record · Routing emits request outcomes and stream metrics
- Telemetry → Recorder: classify · Telemetry recorder parses streams and error classes
- Telemetry → Scoring: score · Telemetry computes node scores from observed metrics
- Telemetry → Persist: cache · Telemetry state is persisted locally for reuse
- Scoring → Select node: feedback · Scoring feeds future routing decisions
- Routing memory → Telemetry: state updates · Routing memory is updated from telemetry outcomes
- Hive → Logger: log · Startup and runtime logging is centralized
- Dashboard → Telemetry: display · Dashboard surfaces telemetry and provider health
- Dashboard → Providers: display · Dashboard shows provider status and available models