# supercompress/supercompress architecture

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

- Interactive diagram: https://gitdiagram.com/supercompress/supercompress
- Repository: https://github.com/supercompress/supercompress

## Overview

SuperCompress is a query-aware LLM context compression product, delivered through a hosted API/Python client and coding-agent integrations. The main workflow sends context plus an unchanged query to a compressor, which returns reduced text and token statistics; optional CCR preserves removed text for retrieval. The graph also shows the local agent proxy path, hosted account/billing capabilities, and framework integrations. README documents capabilities beyond the sampled files; uncertain internal wiring for those is omitted.

Main entry points: [`api/v1/compress.js`](https://github.com/supercompress/supercompress/blob/main/api/v1/compress.js) (Compress API), [`api/_lib/engine.js`](https://github.com/supercompress/supercompress/blob/main/api/_lib/engine.js) (Compression engine), [`api/retrieve.js`](https://github.com/supercompress/supercompress/blob/main/api/retrieve.js) (Retrieve API), [`supercompress/client.py`](https://github.com/supercompress/supercompress/blob/main/supercompress/client.py) (Python client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product entry points"]
  node_python["Python client<br/>[client.py]"]
  node_python_result["Compression result<br/>[result.py]"]
end

subgraph group_compression["Compression runtime"]
  node_engine["Compression engine<br/>[engine.js]"]
  node_local_engine["Local engine<br/>[local-engine.js]"]
  node_web_engine["Shared engine asset"]
  node_compressed["Compressed context and stats"]
end

subgraph group_hosted["Hosted platform"]
  node_api_compress["Compress API<br/>[compress.js]"]
  node_ccr_store[("CCR originals<br/>[engine.js]")]
  node_retrieve["Retrieve API<br/>[retrieve.js]"]
  node_keys["API key management<br/>[keys.js]"]
  node_account["Account and usage<br/>[account.js]"]
  node_billing["Billing endpoints<br/>[billing.js]"]
  node_webhook["Stripe webhook<br/>[billing-webhook.js]"]
  node_billing_helpers["Billing and ledger<br/>[billing-ledger.js]"]
end

subgraph group_agent["Coding agents"]
  node_mcp["MCP tools<br/>[server.js]"]
  node_proxy_server["LLM proxy<br/>[server.js]"]
  node_proxy_compressor["Proxy compressor<br/>[compressor.js]"]
end

subgraph group_integrations["App integrations"]
  node_integrations["Framework adapters"]
end

node_developer(("Developer or agent"))
node_stripe["Stripe"]
node_firebase[("Firebase services")]
node_provider["LLM provider"]

node_developer -->|"calls"| node_python
node_python -->|"posts context/query"| node_api_compress
node_api_compress -->|"compresses"| node_engine
node_engine -->|"loads engine"| node_web_engine
node_engine -->|"returns text/stats"| node_compressed
node_api_compress -.->|"stores originals"| node_ccr_store
node_developer -->|"invokes tools"| node_mcp
node_mcp -->|"compresses/retrieves"| node_engine
node_mcp -.->|"retrieves fallback"| node_retrieve
node_developer -->|"sends LLM request"| node_proxy_server
node_proxy_server -->|"compresses messages"| node_proxy_compressor
node_proxy_compressor -->|"requests compression"| node_api_compress
node_proxy_server -->|"forwards request"| node_provider
node_integrations -.->|"calls compression API"| node_api_compress
node_python -->|"builds result"| node_python_result
node_developer -->|"requests original"| node_retrieve
node_retrieve -->|"reads owned text"| node_ccr_store
node_retrieve -->|"loads stored record"| node_firebase
node_api_compress -->|"authenticates key"| node_keys
node_keys -->|"checks key"| node_firebase
node_developer -->|"manages account"| node_account
node_developer -->|"manages plan"| node_billing
node_billing -->|"creates billing actions"| node_stripe
node_stripe -->|"sends events"| node_webhook
node_webhook -->|"applies updates"| node_billing_helpers
node_billing_helpers -->|"persists ledger"| node_firebase
node_account -->|"reads account data"| node_firebase

click node_python "https://github.com/supercompress/supercompress/blob/main/supercompress/client.py"
click node_api_compress "https://github.com/supercompress/supercompress/blob/main/api/v1/compress.js"
click node_mcp "https://github.com/supercompress/supercompress/blob/main/mcp/server.js"
click node_proxy_server "https://github.com/supercompress/supercompress/blob/main/packages/proxy/src/server.js"
click node_integrations "https://github.com/supercompress/supercompress/tree/main/integrations"
click node_engine "https://github.com/supercompress/supercompress/blob/main/api/_lib/engine.js"
click node_local_engine "https://github.com/supercompress/supercompress/blob/main/packages/proxy/src/local-engine.js"
click node_web_engine "https://github.com/supercompress/supercompress/tree/main/web"
click node_ccr_store "https://github.com/supercompress/supercompress/blob/main/api/_lib/engine.js"
click node_retrieve "https://github.com/supercompress/supercompress/blob/main/api/retrieve.js"
click node_keys "https://github.com/supercompress/supercompress/blob/main/api/keys.js"
click node_account "https://github.com/supercompress/supercompress/blob/main/api/account.js"
click node_billing "https://github.com/supercompress/supercompress/blob/main/api/billing.js"
click node_webhook "https://github.com/supercompress/supercompress/blob/main/api/billing-webhook.js"
click node_billing_helpers "https://github.com/supercompress/supercompress/blob/main/api/_lib/billing-ledger.js"
click node_proxy_compressor "https://github.com/supercompress/supercompress/blob/main/packages/proxy/src/compressor.js"
click node_python_result "https://github.com/supercompress/supercompress/blob/main/supercompress/result.py"

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_python,node_python_result toneBlue
class node_engine,node_local_engine,node_web_engine,node_compressed,node_firebase toneAmber
class node_api_compress,node_ccr_store,node_retrieve,node_keys,node_account,node_billing,node_webhook,node_billing_helpers toneMint
class node_mcp,node_proxy_server,node_proxy_compressor toneRose
class node_integrations,node_developer,node_stripe,node_provider toneIndigo
```

## Components

### Product entry points

- [Python client](https://github.com/supercompress/supercompress/blob/main/supercompress/client.py): `supercompress/client.py`
- [Compression result](https://github.com/supercompress/supercompress/blob/main/supercompress/result.py): `supercompress/result.py`

### Compression runtime

- [Compression engine](https://github.com/supercompress/supercompress/blob/main/api/_lib/engine.js): `api/_lib/engine.js`
- [Local engine](https://github.com/supercompress/supercompress/blob/main/packages/proxy/src/local-engine.js): `packages/proxy/src/local-engine.js`
- [Shared engine asset](https://github.com/supercompress/supercompress/tree/main/web): `web`
- **Compressed context and stats**

### Hosted platform

- [Compress API](https://github.com/supercompress/supercompress/blob/main/api/v1/compress.js): `api/v1/compress.js`
- [CCR originals](https://github.com/supercompress/supercompress/blob/main/api/_lib/engine.js): `api/_lib/engine.js`
- [Retrieve API](https://github.com/supercompress/supercompress/blob/main/api/retrieve.js): `api/retrieve.js`
- [API key management](https://github.com/supercompress/supercompress/blob/main/api/keys.js): `api/keys.js`
- [Account and usage](https://github.com/supercompress/supercompress/blob/main/api/account.js): `api/account.js`
- [Billing endpoints](https://github.com/supercompress/supercompress/blob/main/api/billing.js): `api/billing.js`
- [Stripe webhook](https://github.com/supercompress/supercompress/blob/main/api/billing-webhook.js): `api/billing-webhook.js`
- [Billing and ledger](https://github.com/supercompress/supercompress/blob/main/api/_lib/billing-ledger.js): `api/_lib/billing-ledger.js`

### Coding agents

- [MCP tools](https://github.com/supercompress/supercompress/blob/main/mcp/server.js): `mcp/server.js`
- [LLM proxy](https://github.com/supercompress/supercompress/blob/main/packages/proxy/src/server.js): `packages/proxy/src/server.js`
- [Proxy compressor](https://github.com/supercompress/supercompress/blob/main/packages/proxy/src/compressor.js): `packages/proxy/src/compressor.js`

### App integrations

- [Framework adapters](https://github.com/supercompress/supercompress/tree/main/integrations): `integrations`

### Other components

- **Developer or agent**
- **Stripe**
- **Firebase services**
- **LLM provider**

## Connections

- Developer or agent → Python client: calls
- Python client → Compress API: posts context/query
- Compress API → Compression engine: compresses
- Compression engine → Shared engine asset: loads engine
- Compression engine → Compressed context and stats: returns text/stats
- Compress API → CCR originals: stores originals
- Developer or agent → MCP tools: invokes tools
- MCP tools → Compression engine: compresses/retrieves
- MCP tools → Retrieve API: retrieves fallback
- Developer or agent → LLM proxy: sends LLM request
- LLM proxy → Proxy compressor: compresses messages
- Proxy compressor → Compress API: requests compression
- LLM proxy → LLM provider: forwards request
- Framework adapters → Compress API: calls compression API
- Python client → Compression result: builds result
- Developer or agent → Retrieve API: requests original
- Retrieve API → CCR originals: reads owned text
- Retrieve API → Firebase services: loads stored record
- Compress API → API key management: authenticates key
- API key management → Firebase services: checks key
- Developer or agent → Account and usage: manages account
- Developer or agent → Billing endpoints: manages plan
- Billing endpoints → Stripe: creates billing actions
- Stripe → Stripe webhook: sends events
- Stripe webhook → Billing and ledger: applies updates
- Billing and ledger → Firebase services: persists ledger
- Account and usage → Firebase services: reads account data