# teamchong/pxpipe architecture

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

- Interactive diagram: https://gitdiagram.com/teamchong/pxpipe
- Repository: https://github.com/teamchong/pxpipe

## Overview

1. **What this repo is**
   - `pxpipe` is a token-compression proxy/library for Claude Code–style traffic.
   - Its core move is architectural: it rewrites selected **request-side** context into PNG images before the request leaves the machine, while leaving **responses** untouched.

2. **Main ingress/egress boundary**
   - The primary runtime boundary is an **Anthropic-compatible `/v1/messages` proxy**.
   - Clients such as Claude Code point `ANTHROPIC_BASE_URL` at the local proxy; the proxy forwards to Anthropic/GPT backends after transformation.
   - Unsupported models or non-eligible content are passed through byte-identically.

3. **Request transformation pipeline**
   - The central pipeline lives in `src/core/transform.ts` and related helpers.
   - It parses a request, classifies message blocks, decides what is profitable to image, and rewrites eligible blocks into image content.
   - Important policy knobs include `keepSharp` for forcing text retention and `emitRecoverable` for retaining originals of imaged blocks.

4. **Rendering subsystem**
   - Text-to-image conversion is isolated in `src/core/render.ts`, `png.ts`, `atlas.ts`, and `atlas-gray.ts`.
   - The renderer wraps dense text into fixed-size pages, then encodes pages as PNGs using bundled font assets in `assets/`.
   - This is the mechanical heart of the compression: long text slabs become dense image pages sized to fit model vision input efficiently.

5. **Eligibility, sizing, and layout**
   - `src/core/applicability.ts`, `measurement.ts`, and `factsheet.ts` determine whether a block should be imaged and how it should be laid out.
   - The system is intentionally selective: recent turns, sparse prose, and small chunks stay text; bulky tool output, history, and system/tool-document slabs are candidates for imaging.
   - The docs under `docs/RENDER_SIZING.md` and `docs/TRANSFORM_INFO.md` appear to capture these constraints and the page geometry assumptions.

6. **Cost, caching, and “savings” accounting**
   - `src/core/baseline.ts`, `openai-savings.ts`, `history.ts`, and `openai-history.ts` track the economics of a transformed request versus a counterfactual plain-text request.
   - The proxy measures savings against a token-count baseline and records actual billed usage, rather than inferring savings from just the touched portion.
   - Cache behavior matters: the architecture preserves static prefixes where possible so prompt caching still works, and the accounting explicitly includes cache write/read effects.

7. **Model profiles and provider-specific behavior**
   - `src/core/gpt-model-profiles.ts`, `openai.ts`, and `proxy.ts` reflect that the system is not Anthropic-only.
   - The README shows two key provider families: Claude/Anthropic and GPT models, with different handling for tool definitions and cache markers.
   - Model allowlisting is part of the control plane: some models are imaged by default, others are opt-in or pass through unchanged.

8. **Persistence and telemetry**
   - The proxy writes operational events to `~/.pxpipe/events.jsonl` and uses those rows as the canonical record for savings and behavior.
   - `src/core/tracker.ts`, `stats.ts`, `sessions.ts`, and `export.ts` suggest a second layer that aggregates per-session and per-request state for analysis, dashboards, and export.
   - `src/export-collect.ts` is the likely boundary for turning raw proxy logs into reportable artifacts.

9. **Local dashboard and operator controls**
   - `src/dashboard.ts` plus `src/dashboard/` implement a local UI served by the proxy.
   - The dashboard exposes live model chips, token savings, per-request conversions, and a kill switch.
   - This is an operational control surface, not a separate backend: it reads the same proxy state and event log.

10. **Runtime targets and packaging**
   - The repo is designed for **pure JS runtime portability** across Node and Cloudflare Workers; `src/node.ts` and `src/worker.ts` are the deployment entrypoints.
   - `wrangler.toml` indicates an edge/Workers deployment path, while `bin/cli.js` is the local CLI entry.
   - `@napi-rs/canvas` is build-time only; the runtime stays JavaScript-first.

11. **Research, evaluation, and receipts**
   - The `eval/` tree is a substantial measurement harness, not production code.
   - It contains benchmark runners, grading scripts, receipts, and reports for recall, savings, SWE-bench variants, GSM8K, and other experiments that justify the compression policy.
   - The `demo/` tree contains smaller reproducible scenarios, including cost A/B examples and context-efficiency demos.

12. **Testing and release boundaries**
   - The `tests/` suite is broad and architectural: cache alignment, proxy behavior, render fidelity, export correctness, dashboard API, restart/restore, and savings honesty.
   - GitHub Actions in `.github/workflows/` run CI and release workflows, indicating the repo is shipped as a packaged tool/library with reproducible builds.
   - The presence of `pnpm-workspace.yaml`, `tsconfig.json`, and `vitest.config.ts` shows a TypeScript monorepo-style setup with a single cohesive runtime package plus supporting evaluation assets.

13. **Diagram-friendly summary**
   - If you draw this repo, the key flow is: **client → local proxy → transform/render decision → PNG/text rewrite → upstream model API → response passthrough**.
   - Surrounding that path are three support planes: **policy/accounting** (savings, cache, model profiles), **observability/UI** (events, dashboard, exports), and **research/test harnesses** (`eval/`, `demo/`, `tests/`) that validate whether the compression remains useful and honest.

Main entry points: [`src/core/proxy.ts`](https://github.com/teamchong/pxpipe/blob/main/src/core/proxy.ts) (Proxy), [`src/core/render.ts`](https://github.com/teamchong/pxpipe/blob/main/src/core/render.ts) (Render), [`src/core/transform.ts`](https://github.com/teamchong/pxpipe/blob/main/src/core/transform.ts) (Transform), [`src/core/tracker.ts`](https://github.com/teamchong/pxpipe/blob/main/src/core/tracker.ts) (Tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_node_cli["CLI<br/>entrypoint<br/>[cli.js]"]
  node_node_node["Node app<br/>entrypoint<br/>[node.ts]"]
  node_node_worker["Worker app<br/>entrypoint<br/>[worker.ts]"]
end

subgraph group_grp_core["Core pipeline"]
  node_node_proxy["Proxy<br/>[proxy.ts]"]
  node_node_transform["Transform<br/>rewrite pipeline<br/>[transform.ts]"]
  node_node_applicability["Applicability<br/>policy rules<br/>[applicability.ts]"]
  node_node_measurement["Measurement<br/>sizing logic<br/>[measurement.ts]"]
  node_node_factsheet["Factsheet<br/>layout facts<br/>[factsheet.ts]"]
  node_node_render["Render<br/>text-to-image<br/>[render.ts]"]
  node_node_png["PNG encode<br/>image encoding<br/>[png.ts]"]
  node_node_atlas["Atlas<br/>[atlas.ts]"]
  node_node_atlas_gray["Gray atlas<br/>font atlas<br/>[atlas-gray.ts]"]
  node_node_profiles["Model profiles<br/>allowlist/profile"]
  node_node_openai["OpenAI bridge<br/>provider adapter<br/>[openai.ts]"]
end

subgraph group_grp_ops["Ops & data"]
  node_node_accounting["Accounting<br/>savings tracking<br/>[baseline.ts]"]
  node_node_history["History<br/>request ledger<br/>[history.ts]"]
  node_node_tracker["Tracker<br/>event log<br/>[tracker.ts]"]
  node_node_export["Export<br/>reporting<br/>[export-collect.ts]"]
  node_node_stats["Stats<br/>aggregation<br/>[stats.ts]"]
  node_node_sessions["Sessions<br/>state store<br/>[sessions.ts]"]
  node_node_dashboard["Dashboard<br/>UI<br/>[dashboard.ts]"]
end

subgraph group_grp_research["Research & QA"]
  node_node_eval["Eval suite<br/>benchmark harness<br/>[README.md]"]
  node_node_demo["Demos<br/>examples<br/>[README.md]"]
  node_node_tests["Tests<br/>validation suite<br/>[public-api.test.ts]"]
end

node_node_cli -->|"start"| node_node_proxy
node_node_node -->|"serves"| node_node_proxy
node_node_worker -->|"serves"| node_node_proxy
node_node_proxy -->|"rewrite"| node_node_transform
node_node_transform -->|"decide"| node_node_applicability
node_node_transform -->|"measure"| node_node_measurement
node_node_transform -->|"render"| node_node_render
node_node_measurement -->|"constraints"| node_node_factsheet
node_node_render -->|"glyphs"| node_node_atlas
node_node_render -->|"glyphs"| node_node_atlas_gray
node_node_render -->|"encode"| node_node_png
node_node_proxy -->|"select model"| node_node_profiles
node_node_proxy -->|"adapt"| node_node_openai
node_node_proxy -->|"record savings"| node_node_accounting
node_node_accounting -->|"consult"| node_node_history
node_node_proxy -->|"emit"| node_node_tracker
node_node_tracker -->|"aggregate"| node_node_stats
node_node_stats -->|"group"| node_node_sessions
node_node_dashboard -->|"read"| node_node_tracker
node_node_dashboard -->|"read"| node_node_stats
node_node_export -->|"consume"| node_node_tracker
node_node_eval -->|"exercise"| node_node_render
node_node_demo -->|"demonstrate"| node_node_transform
node_node_tests -->|"verify"| node_node_proxy
node_node_tests -->|"verify"| node_node_render
node_node_tests -->|"verify"| node_node_export

click node_node_cli "https://github.com/teamchong/pxpipe/blob/main/bin/cli.js"
click node_node_node "https://github.com/teamchong/pxpipe/blob/main/src/node.ts"
click node_node_worker "https://github.com/teamchong/pxpipe/blob/main/src/worker.ts"
click node_node_proxy "https://github.com/teamchong/pxpipe/blob/main/src/core/proxy.ts"
click node_node_transform "https://github.com/teamchong/pxpipe/blob/main/src/core/transform.ts"
click node_node_applicability "https://github.com/teamchong/pxpipe/blob/main/src/core/applicability.ts"
click node_node_measurement "https://github.com/teamchong/pxpipe/blob/main/src/core/measurement.ts"
click node_node_factsheet "https://github.com/teamchong/pxpipe/blob/main/src/core/factsheet.ts"
click node_node_render "https://github.com/teamchong/pxpipe/blob/main/src/core/render.ts"
click node_node_png "https://github.com/teamchong/pxpipe/blob/main/src/core/png.ts"
click node_node_atlas "https://github.com/teamchong/pxpipe/blob/main/src/core/atlas.ts"
click node_node_atlas_gray "https://github.com/teamchong/pxpipe/blob/main/src/core/atlas-gray.ts"
click node_node_profiles "https://github.com/teamchong/pxpipe/blob/main/src/core/gpt-model-profiles.ts"
click node_node_openai "https://github.com/teamchong/pxpipe/blob/main/src/core/openai.ts"
click node_node_accounting "https://github.com/teamchong/pxpipe/blob/main/src/core/baseline.ts"
click node_node_history "https://github.com/teamchong/pxpipe/blob/main/src/core/history.ts"
click node_node_tracker "https://github.com/teamchong/pxpipe/blob/main/src/core/tracker.ts"
click node_node_export "https://github.com/teamchong/pxpipe/blob/main/src/export-collect.ts"
click node_node_stats "https://github.com/teamchong/pxpipe/blob/main/src/stats.ts"
click node_node_sessions "https://github.com/teamchong/pxpipe/blob/main/src/sessions.ts"
click node_node_dashboard "https://github.com/teamchong/pxpipe/blob/main/src/dashboard.ts"
click node_node_eval "https://github.com/teamchong/pxpipe/blob/main/eval/README.md"
click node_node_demo "https://github.com/teamchong/pxpipe/blob/main/demo/README.md"
click node_node_tests "https://github.com/teamchong/pxpipe/blob/main/tests/public-api.test.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_node_cli,node_node_node,node_node_worker toneBlue
class node_node_proxy,node_node_transform,node_node_applicability,node_node_measurement,node_node_factsheet,node_node_render,node_node_png,node_node_atlas,node_node_atlas_gray,node_node_profiles,node_node_openai toneAmber
class node_node_accounting,node_node_history,node_node_tracker,node_node_export,node_node_stats,node_node_sessions,node_node_dashboard toneMint
class node_node_eval,node_node_demo,node_node_tests toneRose
```

## Components

### Runtime

Deployment entrypoints and proxy boundary

- [CLI](https://github.com/teamchong/pxpipe/blob/main/bin/cli.js): entrypoint · Local command entry for running and controlling the tool · `bin/cli.js`
- [Node app](https://github.com/teamchong/pxpipe/blob/main/src/node.ts): entrypoint · Node runtime entrypoint and server bootstrap · `src/node.ts`
- [Worker app](https://github.com/teamchong/pxpipe/blob/main/src/worker.ts): entrypoint · Cloudflare Workers entrypoint · `src/worker.ts`

### Core pipeline

Request transformation, rendering, and model-specific handling

- [Proxy](https://github.com/teamchong/pxpipe/blob/main/src/core/proxy.ts): HTTP proxy · Anthropic-compatible /v1/messages boundary that forwards transformed traffic · `src/core/proxy.ts`
- [Transform](https://github.com/teamchong/pxpipe/blob/main/src/core/transform.ts): rewrite pipeline · Parses requests, classifies blocks, and rewrites eligible text into images · `src/core/transform.ts`
- [Applicability](https://github.com/teamchong/pxpipe/blob/main/src/core/applicability.ts): policy rules · Selects which blocks are profitable or allowed to image · `src/core/applicability.ts`
- [Measurement](https://github.com/teamchong/pxpipe/blob/main/src/core/measurement.ts): sizing logic · Estimates block size and layout constraints for compression decisions · `src/core/measurement.ts`
- [Factsheet](https://github.com/teamchong/pxpipe/blob/main/src/core/factsheet.ts): layout facts · Captures page geometry and transform assumptions · `src/core/factsheet.ts`
- [Render](https://github.com/teamchong/pxpipe/blob/main/src/core/render.ts): text-to-image · Converts dense text slabs into paged image content · `src/core/render.ts`
- [PNG encode](https://github.com/teamchong/pxpipe/blob/main/src/core/png.ts): image encoding · Encodes rendered pages into PNG payloads · `src/core/png.ts`
- [Atlas](https://github.com/teamchong/pxpipe/blob/main/src/core/atlas.ts): font atlas · Primary glyph atlas used by the renderer · `src/core/atlas.ts`
- [Gray atlas](https://github.com/teamchong/pxpipe/blob/main/src/core/atlas-gray.ts): font atlas · Alternate grayscale atlas for rendering · `src/core/atlas-gray.ts`
- [Model profiles](https://github.com/teamchong/pxpipe/blob/main/src/core/gpt-model-profiles.ts): allowlist/profile · Model-specific behavior and eligibility rules · `src/core/gpt-model-profiles.ts`
- [OpenAI bridge](https://github.com/teamchong/pxpipe/blob/main/src/core/openai.ts): provider adapter · Provider-specific request shaping for GPT/OpenAI-style traffic · `src/core/openai.ts`

### Ops & data

Accounting, persistence, sessions, and dashboard surfaces

- [Accounting](https://github.com/teamchong/pxpipe/blob/main/src/core/baseline.ts): savings tracking · Baseline, history, and savings math for transformed requests · `src/core/baseline.ts`
- [History](https://github.com/teamchong/pxpipe/blob/main/src/core/history.ts): request ledger · Tracks request and cache history for cost accounting · `src/core/history.ts`
- [Tracker](https://github.com/teamchong/pxpipe/blob/main/src/core/tracker.ts): event log · Writes canonical operational events and usage records · `src/core/tracker.ts`
- [Export](https://github.com/teamchong/pxpipe/blob/main/src/export-collect.ts): reporting · Aggregates logs into exportable reports and artifacts · `src/export-collect.ts`
- [Stats](https://github.com/teamchong/pxpipe/blob/main/src/stats.ts): aggregation · Session and request-level summaries for savings and behavior · `src/stats.ts`
- [Sessions](https://github.com/teamchong/pxpipe/blob/main/src/sessions.ts): state store · Groups proxy activity into session state · `src/sessions.ts`
- [Dashboard](https://github.com/teamchong/pxpipe/blob/main/src/dashboard.ts): UI · Local operator UI served alongside the proxy · `src/dashboard.ts`

### Research & QA

Evaluation, demos, tests, and validation assets

- [Eval suite](https://github.com/teamchong/pxpipe/blob/main/eval/README.md): benchmark harness · Measurement and grading harness for compression quality and savings · `eval/README.md`
- [Demos](https://github.com/teamchong/pxpipe/blob/main/demo/README.md): examples · Reproducible scenarios for cost and context-efficiency behavior · `demo/README.md`
- [Tests](https://github.com/teamchong/pxpipe/blob/main/tests/public-api.test.ts): validation suite · Architectural and end-to-end regression coverage · `tests/public-api.test.ts`

## Connections

- CLI → Proxy: start · Launches the local proxy and control surface
- Node app → Proxy: serves · Bootstraps the proxy in Node runtime
- Worker app → Proxy: serves · Bootstraps the proxy in Workers runtime
- Proxy → Transform: rewrite · Transforms eligible requests before forwarding
- Transform → Applicability: decide · Checks whether blocks should stay text or become images
- Transform → Measurement: measure · Estimates block size and fit for pagination
- Transform → Render: render · Sends selected text slabs to image generation
- Measurement → Factsheet: constraints · Uses geometry and layout assumptions
- Render → Atlas: glyphs · Uses bundled font atlas for page construction
- Render → Gray atlas: glyphs · Can use grayscale atlas variant
- Render → PNG encode: encode · Packages rendered pages as PNG images
- Proxy → Model profiles: select model · Applies allowlisting and model-specific behavior
- Proxy → OpenAI bridge: adapt · Handles GPT/OpenAI-style provider differences
- Proxy → Accounting: record savings · Computes counterfactual and transformed cost
- Accounting → History: consult · Uses request and cache history for billing math
- Proxy → Tracker: emit · Writes operational events for canonical recordkeeping
- Tracker → Stats: aggregate · Feeds session and request summaries
- Stats → Sessions: group · Organizes activity into sessions
- Dashboard → Tracker: read · Displays live events and usage state
- Dashboard → Stats: read · Shows savings and per-request summaries
- Export → Tracker: consume · Turns event logs into reports and exports
- Eval suite → Render: exercise · Benchmarks render quality and compression behavior
- Demos → Transform: demonstrate · Shows cost and context-efficiency scenarios
- Tests → Proxy: verify · Covers proxy, cache, and passthrough behavior
- Tests → Render: verify · Checks render fidelity and sizing behavior
- Tests → Export: verify · Checks export and accounting correctness
