# ranxianglei/billion-context architecture

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

- Interactive diagram: https://gitdiagram.com/ranxianglei/billion-context
- Repository: https://github.com/ranxianglei/billion-context

## Overview

billion-context is a context-compression proxy and agent integration layer. An agent sends model traffic through the proxy; the proxy processes the conversation with acp-kernel’s incremental compression, exposes model-invoked context tools, forwards requests to a compatible model API, and rewrites streaming responses. Client-specific adapters and launch/MITM support provide alternative ways to route traffic. Session state and content support long-lived conversations; a web interface exposes session and operational views. The README documents the core workflow and tools; sampled source confirms the loop, protocol adapters, configuration, and selected integrations, but not every subsystem’s wiring.

Main entry points: [`src/server.ts`](https://github.com/ranxianglei/billion-context/blob/master/src/server.ts) (Proxy server), [`src/loop/core.ts`](https://github.com/ranxianglei/billion-context/blob/master/src/loop/core.ts) (Compression loop), [`src/web/api.ts`](https://github.com/ranxianglei/billion-context/blob/master/src/web/api.ts) (Web API), [`src/loop/index.ts`](https://github.com/ranxianglei/billion-context/blob/master/src/loop/index.ts) (Protocol adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Proxy entry"]
  node_cli["CLI dispatcher<br/>[cli.ts]"]
  node_proxy["Proxy server<br/>[server.ts]"]
end

subgraph group_compression["Context management"]
  node_loop["Compression loop<br/>[core.ts]"]
  node_adapters["Protocol adapters<br/>[index.ts]"]
  node_tools["Context tools<br/>[compress-tool.ts]"]
end

subgraph group_clients["Client integrations"]
  node_agent_plugins["Native agent plugins"]
  node_launcher["Client launchers<br/>[launcher.ts]"]
  node_mitm["TLS MITM routing<br/>[mitm.ts]"]
  node_hermes["Hermes plugin<br/>[__init__.py]"]
end

subgraph group_state["Session and operations"]
  node_session["Session state<br/>[session.ts]"]
  node_content[("Content store<br/>[store.ts]")]
  node_config["Proxy configuration<br/>[config.ts]"]
  node_window["Window resolution<br/>[context-window.ts]"]
end

subgraph group_observability["Web interface"]
  node_web_api["Web API<br/>[api.ts]"]
  node_web_data["Session views<br/>[sessions-data.ts]"]
  node_web_ui["Web interface<br/>[index.ts]"]
  node_logs["Log queries<br/>[logs-query.ts]"]
end

node_agent(("Coding agent"))
node_upstream(("Model API"))
node_kernel["acp-kernel"]

node_agent -->|"sends requests"| node_proxy
node_cli -->|"starts"| node_proxy
node_proxy -->|"processes turns"| node_loop
node_proxy -->|"selects protocol"| node_adapters
node_adapters -->|"adapts streams"| node_loop
node_loop -->|"compresses context"| node_kernel
node_loop -->|"executes tools"| node_tools
node_proxy -->|"forwards requests"| node_upstream
node_upstream -->|"streams responses"| node_proxy
node_proxy -->|"updates state"| node_session
node_proxy -->|"adopts content store"| node_content
node_proxy -->|"resolves routes"| node_config
node_proxy -->|"resolves limits"| node_window
node_agent_plugins -.->|"calls tool endpoints"| node_proxy
node_launcher -.->|"routes client traffic"| node_proxy
node_mitm -.->|"routes intercepted traffic"| node_proxy
node_hermes -.->|"forwards tool calls"| node_proxy
node_proxy -->|"serves admin API"| node_web_api
node_web_api -->|"builds session views"| node_web_data
node_web_api -->|"queries logs"| node_logs
node_web_ui -->|"requests views"| node_web_api

click node_cli "https://github.com/ranxianglei/billion-context/blob/master/src/cli.ts"
click node_proxy "https://github.com/ranxianglei/billion-context/blob/master/src/server.ts"
click node_loop "https://github.com/ranxianglei/billion-context/blob/master/src/loop/core.ts"
click node_adapters "https://github.com/ranxianglei/billion-context/blob/master/src/loop/index.ts"
click node_tools "https://github.com/ranxianglei/billion-context/blob/master/src/compress-tool.ts"
click node_session "https://github.com/ranxianglei/billion-context/blob/master/src/session.ts"
click node_content "https://github.com/ranxianglei/billion-context/blob/master/src/store.ts"
click node_config "https://github.com/ranxianglei/billion-context/blob/master/src/config.ts"
click node_window "https://github.com/ranxianglei/billion-context/blob/master/src/server/context-window.ts"
click node_agent_plugins "https://github.com/ranxianglei/billion-context/tree/master/src/agent"
click node_launcher "https://github.com/ranxianglei/billion-context/blob/master/src/launcher.ts"
click node_mitm "https://github.com/ranxianglei/billion-context/blob/master/src/mitm.ts"
click node_hermes "https://github.com/ranxianglei/billion-context/blob/master/hermes-plugin/__init__.py"
click node_web_api "https://github.com/ranxianglei/billion-context/blob/master/src/web/api.ts"
click node_web_data "https://github.com/ranxianglei/billion-context/blob/master/src/web/sessions-data.ts"
click node_web_ui "https://github.com/ranxianglei/billion-context/blob/master/src/web/index.ts"
click node_logs "https://github.com/ranxianglei/billion-context/blob/master/src/web/logs-query.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_cli,node_proxy toneBlue
class node_loop,node_adapters,node_tools toneAmber
class node_agent_plugins,node_launcher,node_mitm,node_hermes,node_upstream toneMint
class node_session,node_content,node_config,node_window toneRose
class node_web_api,node_web_data,node_web_ui,node_logs,node_agent,node_kernel toneIndigo
```

## Components

### Proxy entry

- [CLI dispatcher](https://github.com/ranxianglei/billion-context/blob/master/src/cli.ts): `src/cli.ts`
- [Proxy server](https://github.com/ranxianglei/billion-context/blob/master/src/server.ts): `src/server.ts`

### Context management

- [Compression loop](https://github.com/ranxianglei/billion-context/blob/master/src/loop/core.ts): `src/loop/core.ts`
- [Protocol adapters](https://github.com/ranxianglei/billion-context/blob/master/src/loop/index.ts): `src/loop/index.ts`
- [Context tools](https://github.com/ranxianglei/billion-context/blob/master/src/compress-tool.ts): `src/compress-tool.ts`

### Client integrations

- [Native agent plugins](https://github.com/ranxianglei/billion-context/tree/master/src/agent): `src/agent`
- [Client launchers](https://github.com/ranxianglei/billion-context/blob/master/src/launcher.ts): `src/launcher.ts`
- [TLS MITM routing](https://github.com/ranxianglei/billion-context/blob/master/src/mitm.ts): `src/mitm.ts`
- [Hermes plugin](https://github.com/ranxianglei/billion-context/blob/master/hermes-plugin/__init__.py): `hermes-plugin/__init__.py`

### Session and operations

- [Session state](https://github.com/ranxianglei/billion-context/blob/master/src/session.ts): `src/session.ts`
- [Content store](https://github.com/ranxianglei/billion-context/blob/master/src/store.ts): `src/store.ts`
- [Proxy configuration](https://github.com/ranxianglei/billion-context/blob/master/src/config.ts): `src/config.ts`
- [Window resolution](https://github.com/ranxianglei/billion-context/blob/master/src/server/context-window.ts): `src/server/context-window.ts`

### Web interface

- [Web API](https://github.com/ranxianglei/billion-context/blob/master/src/web/api.ts): `src/web/api.ts`
- [Session views](https://github.com/ranxianglei/billion-context/blob/master/src/web/sessions-data.ts): `src/web/sessions-data.ts`
- [Web interface](https://github.com/ranxianglei/billion-context/blob/master/src/web/index.ts): `src/web/index.ts`
- [Log queries](https://github.com/ranxianglei/billion-context/blob/master/src/web/logs-query.ts): `src/web/logs-query.ts`

### Other components

- **Coding agent**
- **Model API**
- **acp-kernel**

## Connections

- Coding agent → Proxy server: sends requests
- CLI dispatcher → Proxy server: starts
- Proxy server → Compression loop: processes turns
- Proxy server → Protocol adapters: selects protocol
- Protocol adapters → Compression loop: adapts streams
- Compression loop → acp-kernel: compresses context
- Compression loop → Context tools: executes tools
- Proxy server → Model API: forwards requests
- Model API → Proxy server: streams responses
- Proxy server → Session state: updates state
- Proxy server → Content store: adopts content store
- Proxy server → Proxy configuration: resolves routes
- Proxy server → Window resolution: resolves limits
- Native agent plugins → Proxy server: calls tool endpoints
- Client launchers → Proxy server: routes client traffic
- TLS MITM routing → Proxy server: routes intercepted traffic
- Hermes plugin → Proxy server: forwards tool calls
- Proxy server → Web API: serves admin API
- Web API → Session views: builds session views
- Web API → Log queries: queries logs
- Web interface → Web API: requests views