# akashagarwalind/trimproof architecture

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

- Interactive diagram: https://gitdiagram.com/akashagarwalind/trimproof
- Repository: https://github.com/akashagarwalind/trimproof

## Overview

trimproof is a Go gateway that conditionally re-encodes eligible LLM request data, forwards requests to Anthropic or OpenAI-compatible providers, and validates responses. Its principal workflow is route selection and identity, four transformation gates, provider forwarding, and optional Tier 1 validation. Shadow evaluation and promotion use paired provider calls to decide whether a route should enable or disable optimization. Audit, metrics, token calibration, and operator reporting are supporting capabilities. Some wiring is documented in the README; unsampled implementation details and uncertain links are omitted.

Main entry points: [`pkg/server/server.go`](https://github.com/akashagarwalind/trimproof/blob/master/pkg/server/server.go) (HTTP gateway), [`pkg/eval/shadow.go`](https://github.com/akashagarwalind/trimproof/blob/master/pkg/eval/shadow.go) (Shadow evaluator), [`pkg/policy/gates.go`](https://github.com/akashagarwalind/trimproof/blob/master/pkg/policy/gates.go) (Four gates), [`pkg/calibrate/calibrate.go`](https://github.com/akashagarwalind/trimproof/blob/master/pkg/calibrate/calibrate.go) (Token calibrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway runtime"]
  node_gateway_main["Gateway process<br/>[main.go]"]
  node_http_gateway["HTTP gateway<br/>[server.go]"]
  node_identity["Identity handling<br/>[identity.go]"]
  node_route_registry["Route registry<br/>[registry.go]"]
  node_provider_adapters["Provider adapters<br/>[anthropic.go]"]
  node_openai_adapter["OpenAI adapter<br/>[openai.go]"]
end

subgraph group_transform["Encoding and gates"]
  node_policy_gates["Four gates<br/>[gates.go]"]
  node_toonx_codec["TOONX codec<br/>[toonx.go]"]
  node_toonx_decode["TOONX decoder<br/>[decode.go]"]
  node_token_estimator["Token estimates<br/>[tokens.go]"]
end

subgraph group_safety["Validation and identity"]
  node_validator["Tier 1 validation<br/>[validator.go]"]
  node_authorization["Scope authorization<br/>[authz.go]"]
end

subgraph group_evaluation["Evaluation and promotion"]
  node_shadow["Shadow evaluator<br/>[shadow.go]"]
  node_evaluation_store[("Evaluation pairs<br/>[store.go]")]
  node_promoter["Route promoter<br/>[promotion.go]"]
end

subgraph group_operations["Observability and reporting"]
  node_audit["Audit pipeline<br/>[audit.go]"]
  node_metrics["OTel metrics<br/>[metrics.go]"]
  node_calibrator["Token calibrator<br/>[calibrate.go]"]
  node_report_cli["Report CLI<br/>[main.go]"]
  node_report_builder["Report builder<br/>[report.go]"]
end

node_client(("LLM client"))
node_upstream(("LLM providers"))
node_anthropic_count(("Anthropic counter"))

node_client -->|"sends request"| node_http_gateway
node_http_gateway -->|"checks identity"| node_identity
node_http_gateway -->|"looks up route"| node_route_registry
node_http_gateway -->|"decides transforms"| node_policy_gates
node_policy_gates -->|"encodes eligible data"| node_toonx_codec
node_policy_gates -->|"estimates savings"| node_token_estimator
node_http_gateway -->|"parses and renders"| node_provider_adapters
node_http_gateway -->|"routes OpenAI API"| node_openai_adapter
node_http_gateway -->|"forwards request"| node_upstream
node_upstream -->|"returns response"| node_http_gateway
node_http_gateway -->|"validates response"| node_validator
node_validator -->|"checks tool scope"| node_authorization
node_toonx_codec -->|"verifies round trip"| node_toonx_decode
node_gateway_main -->|"starts gateway"| node_http_gateway
node_gateway_main -->|"starts evaluator"| node_shadow
node_http_gateway -->|"observes exchanges"| node_shadow
node_shadow -->|"runs paired calls"| node_upstream
node_shadow -->|"stores pairs"| node_evaluation_store
node_shadow -->|"evaluates route"| node_promoter
node_promoter -->|"reads route state"| node_route_registry
node_http_gateway -->|"emits exchanges"| node_audit
node_http_gateway -->|"reports metrics"| node_metrics
node_http_gateway -->|"observes requests"| node_calibrator
node_calibrator -->|"requests token counts"| node_anthropic_count
node_calibrator -->|"corrects estimates"| node_token_estimator
node_report_cli -->|"builds report"| node_report_builder
node_report_builder -->|"reads evaluation pairs"| node_evaluation_store
node_report_builder -->|"summarizes audit log"| node_audit

click node_gateway_main "https://github.com/akashagarwalind/trimproof/blob/master/cmd/gateway/main.go"
click node_http_gateway "https://github.com/akashagarwalind/trimproof/blob/master/pkg/server/server.go"
click node_identity "https://github.com/akashagarwalind/trimproof/blob/master/pkg/server/identity.go"
click node_route_registry "https://github.com/akashagarwalind/trimproof/blob/master/pkg/server/registry.go"
click node_provider_adapters "https://github.com/akashagarwalind/trimproof/blob/master/pkg/provider/anthropic/anthropic.go"
click node_openai_adapter "https://github.com/akashagarwalind/trimproof/blob/master/pkg/provider/openai/openai.go"
click node_policy_gates "https://github.com/akashagarwalind/trimproof/blob/master/pkg/policy/gates.go"
click node_toonx_codec "https://github.com/akashagarwalind/trimproof/blob/master/pkg/codec/toonx/toonx.go"
click node_toonx_decode "https://github.com/akashagarwalind/trimproof/blob/master/pkg/codec/toonx/decode.go"
click node_token_estimator "https://github.com/akashagarwalind/trimproof/blob/master/pkg/tokens/tokens.go"
click node_validator "https://github.com/akashagarwalind/trimproof/blob/master/pkg/validator/validator.go"
click node_authorization "https://github.com/akashagarwalind/trimproof/blob/master/pkg/validator/authz.go"
click node_shadow "https://github.com/akashagarwalind/trimproof/blob/master/pkg/eval/shadow.go"
click node_evaluation_store "https://github.com/akashagarwalind/trimproof/blob/master/pkg/eval/store.go"
click node_promoter "https://github.com/akashagarwalind/trimproof/blob/master/pkg/eval/promotion.go"
click node_audit "https://github.com/akashagarwalind/trimproof/blob/master/pkg/audit/audit.go"
click node_metrics "https://github.com/akashagarwalind/trimproof/blob/master/pkg/audit/metrics.go"
click node_calibrator "https://github.com/akashagarwalind/trimproof/blob/master/pkg/calibrate/calibrate.go"
click node_report_cli "https://github.com/akashagarwalind/trimproof/blob/master/cmd/trimproof/main.go"
click node_report_builder "https://github.com/akashagarwalind/trimproof/blob/master/internal/report/report.go"

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_gateway_main,node_http_gateway,node_identity,node_route_registry,node_provider_adapters,node_openai_adapter,node_client toneBlue
class node_policy_gates,node_toonx_codec,node_toonx_decode,node_token_estimator toneAmber
class node_validator,node_authorization toneMint
class node_shadow,node_evaluation_store,node_promoter toneRose
class node_audit,node_metrics,node_calibrator,node_report_cli,node_report_builder,node_upstream,node_anthropic_count toneIndigo
```

## Components

### Gateway runtime

- [Gateway process](https://github.com/akashagarwalind/trimproof/blob/master/cmd/gateway/main.go): `cmd/gateway/main.go`
- [HTTP gateway](https://github.com/akashagarwalind/trimproof/blob/master/pkg/server/server.go): `pkg/server/server.go`
- [Identity handling](https://github.com/akashagarwalind/trimproof/blob/master/pkg/server/identity.go): `pkg/server/identity.go`
- [Route registry](https://github.com/akashagarwalind/trimproof/blob/master/pkg/server/registry.go): `pkg/server/registry.go`
- [Provider adapters](https://github.com/akashagarwalind/trimproof/blob/master/pkg/provider/anthropic/anthropic.go): `pkg/provider/anthropic/anthropic.go`
- [OpenAI adapter](https://github.com/akashagarwalind/trimproof/blob/master/pkg/provider/openai/openai.go): `pkg/provider/openai/openai.go`

### Encoding and gates

- [Four gates](https://github.com/akashagarwalind/trimproof/blob/master/pkg/policy/gates.go): `pkg/policy/gates.go`
- [TOONX codec](https://github.com/akashagarwalind/trimproof/blob/master/pkg/codec/toonx/toonx.go): `pkg/codec/toonx/toonx.go`
- [TOONX decoder](https://github.com/akashagarwalind/trimproof/blob/master/pkg/codec/toonx/decode.go): `pkg/codec/toonx/decode.go`
- [Token estimates](https://github.com/akashagarwalind/trimproof/blob/master/pkg/tokens/tokens.go): `pkg/tokens/tokens.go`

### Validation and identity

- [Tier 1 validation](https://github.com/akashagarwalind/trimproof/blob/master/pkg/validator/validator.go): `pkg/validator/validator.go`
- [Scope authorization](https://github.com/akashagarwalind/trimproof/blob/master/pkg/validator/authz.go): `pkg/validator/authz.go`

### Evaluation and promotion

- [Shadow evaluator](https://github.com/akashagarwalind/trimproof/blob/master/pkg/eval/shadow.go): `pkg/eval/shadow.go`
- [Evaluation pairs](https://github.com/akashagarwalind/trimproof/blob/master/pkg/eval/store.go): `pkg/eval/store.go`
- [Route promoter](https://github.com/akashagarwalind/trimproof/blob/master/pkg/eval/promotion.go): `pkg/eval/promotion.go`

### Observability and reporting

- [Audit pipeline](https://github.com/akashagarwalind/trimproof/blob/master/pkg/audit/audit.go): `pkg/audit/audit.go`
- [OTel metrics](https://github.com/akashagarwalind/trimproof/blob/master/pkg/audit/metrics.go): `pkg/audit/metrics.go`
- [Token calibrator](https://github.com/akashagarwalind/trimproof/blob/master/pkg/calibrate/calibrate.go): `pkg/calibrate/calibrate.go`
- [Report CLI](https://github.com/akashagarwalind/trimproof/blob/master/cmd/trimproof/main.go): `cmd/trimproof/main.go`
- [Report builder](https://github.com/akashagarwalind/trimproof/blob/master/internal/report/report.go): `internal/report/report.go`

### Other components

- **LLM client**
- **LLM providers**
- **Anthropic counter**

## Connections

- LLM client → HTTP gateway: sends request (evidence: `README.md`)
- HTTP gateway → Identity handling: checks identity (evidence: `pkg/server/server.go`)
- HTTP gateway → Route registry: looks up route (evidence: `pkg/server/server.go`)
- HTTP gateway → Four gates: decides transforms (evidence: `pkg/server/server.go`)
- Four gates → TOONX codec: encodes eligible data (evidence: `pkg/policy/gates.go`)
- Four gates → Token estimates: estimates savings (evidence: `pkg/policy/gates.go`)
- HTTP gateway → Provider adapters: parses and renders (evidence: `pkg/server/server.go`)
- HTTP gateway → OpenAI adapter: routes OpenAI API (evidence: `pkg/server/server.go`)
- HTTP gateway → LLM providers: forwards request (evidence: `pkg/server/server.go`)
- LLM providers → HTTP gateway: returns response (evidence: `README.md`)
- HTTP gateway → Tier 1 validation: validates response (evidence: `README.md`)
- Tier 1 validation → Scope authorization: checks tool scope (evidence: `pkg/validator/authz.go`)
- TOONX codec → TOONX decoder: verifies round trip (evidence: `pkg/codec/toonx/toonx.go`)
- Gateway process → HTTP gateway: starts gateway (evidence: `cmd/gateway/main.go`)
- Gateway process → Shadow evaluator: starts evaluator (evidence: `cmd/gateway/main.go`)
- HTTP gateway → Shadow evaluator: observes exchanges (evidence: `pkg/eval/shadow.go`)
- Shadow evaluator → LLM providers: runs paired calls (evidence: `pkg/eval/shadow.go`)
- Shadow evaluator → Evaluation pairs: stores pairs (evidence: `pkg/eval/shadow.go`)
- Shadow evaluator → Route promoter: evaluates route (evidence: `pkg/eval/shadow.go`)
- Route promoter → Route registry: reads route state (evidence: `pkg/eval/promotion.go`)
- HTTP gateway → Audit pipeline: emits exchanges (evidence: `pkg/audit/audit.go`)
- HTTP gateway → OTel metrics: reports metrics (evidence: `README.md`)
- HTTP gateway → Token calibrator: observes requests (evidence: `pkg/calibrate/calibrate.go`)
- Token calibrator → Anthropic counter: requests token counts (evidence: `pkg/calibrate/calibrate.go`)
- Token calibrator → Token estimates: corrects estimates (evidence: `pkg/calibrate/calibrate.go`)
- Report CLI → Report builder: builds report (evidence: `cmd/trimproof/main.go`)
- Report builder → Evaluation pairs: reads evaluation pairs (evidence: `internal/report/report.go`)
- Report builder → Audit pipeline: summarizes audit log (evidence: `internal/report/report.go`)
