# preburn/preburn architecture

> Architecture diagram of the GitHub repository preburn/preburn, 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/preburn/preburn
- Repository: https://github.com/preburn/preburn

## Overview

Preburn is a margin-control service for AI products: a customer’s app checks a proposed call, receives an allow/route/cap/deny decision, calls its provider directly, then reports measured usage. The service prices usage, records revenue and cost, and uses customer margin signals and policies to guide decisions; a dashboard manages configuration and reviews outcomes. The README documents the Postgres, Valkey, and worker roles. Sampled route excerpts support several admin and reporting surfaces, but most internal wiring is inferred only where the README explicitly describes it.

Main entry points: [`internal/httpapi/api.go`](https://github.com/preburn/preburn/blob/main/internal/httpapi/api.go) (HTTP API), [`internal/decisions/check.go`](https://github.com/preburn/preburn/blob/main/internal/decisions/check.go) (Check decision), [`internal/decisions/report_routes.go`](https://github.com/preburn/preburn/blob/main/internal/decisions/report_routes.go) (Usage report), [`internal/app/worker.go`](https://github.com/preburn/preburn/blob/main/internal/app/worker.go) (Background worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime decisions"]
  node_api["HTTP API<br/>[api.go]"]
  node_check["Check decision<br/>[check.go]"]
  node_report["Usage report<br/>[report_routes.go]"]
  node_release["Release reservation<br/>[release.go]"]
  node_policies["Policy rules<br/>[resolution.go]"]
end

subgraph group_economics["Pricing and margin"]
  node_pricing["Usage pricing<br/>[rating.go]"]
  node_revenue["Revenue records<br/>[service.go]"]
  node_ledger["Cost ledger<br/>[entries.go]"]
  node_customers["Customer records<br/>[service.go]"]
  node_signals["Margin signals<br/>[signals.go]"]
  node_plans["Plans and allowances<br/>[service.go]"]
end

subgraph group_operations["Operations and state"]
  node_postgres[("Postgres")]
  node_valkey[("Valkey counters")]
  node_worker["Background worker<br/>[worker.go]"]
end

subgraph group_dashboard["Dashboard and access"]
  node_dashboard_api["Dashboard API<br/>[overview_routes.go]"]
  node_dashboard_ui["Dashboard UI<br/>[overview-page.tsx]"]
  node_policy_ui["Policy editor<br/>[policy-editor.tsx]"]
  node_access["Members and keys<br/>[routes.go]"]
end

node_client_app(("Customer app"))
node_ai_provider(("AI provider"))

node_client_app -->|"checks and reports"| node_api
node_client_app -->|"calls directly"| node_ai_provider
node_api -->|"dispatches checks"| node_check
node_api -->|"dispatches reports"| node_report
node_api -->|"dispatches releases"| node_release
node_check -->|"prices estimate"| node_pricing
node_check -->|"computes margin"| node_signals
node_check -->|"applies policy"| node_policies
node_report -->|"prices usage"| node_pricing
node_report -->|"records cost"| node_ledger
node_revenue -->|"creates unknown"| node_customers
node_dashboard_ui -->|"requests data"| node_dashboard_api
node_policy_ui -->|"manages policies"| node_api
node_access -->|"stores access state"| node_postgres
node_api -->|"reads and writes"| node_postgres
node_api -->|"reads and writes counters"| node_valkey
node_worker -->|"maintains records"| node_postgres
node_worker -->|"repairs counters"| node_valkey

click node_api "https://github.com/preburn/preburn/blob/main/internal/httpapi/api.go"
click node_check "https://github.com/preburn/preburn/blob/main/internal/decisions/check.go"
click node_report "https://github.com/preburn/preburn/blob/main/internal/decisions/report_routes.go"
click node_release "https://github.com/preburn/preburn/blob/main/internal/decisions/release.go"
click node_policies "https://github.com/preburn/preburn/blob/main/internal/policies/resolution.go"
click node_pricing "https://github.com/preburn/preburn/blob/main/internal/pricing/rating.go"
click node_revenue "https://github.com/preburn/preburn/blob/main/internal/revenue/service.go"
click node_ledger "https://github.com/preburn/preburn/blob/main/internal/ledger/entries.go"
click node_customers "https://github.com/preburn/preburn/blob/main/internal/customers/service.go"
click node_signals "https://github.com/preburn/preburn/blob/main/internal/signals/signals.go"
click node_plans "https://github.com/preburn/preburn/blob/main/internal/plans/service.go"
click node_dashboard_api "https://github.com/preburn/preburn/blob/main/internal/dashboard/overview_routes.go"
click node_dashboard_ui "https://github.com/preburn/preburn/blob/main/web/src/features/overview/overview-page.tsx"
click node_policy_ui "https://github.com/preburn/preburn/blob/main/web/src/features/policies/policy-editor.tsx"
click node_access "https://github.com/preburn/preburn/blob/main/internal/members/routes.go"
click node_worker "https://github.com/preburn/preburn/blob/main/internal/app/worker.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_api,node_check,node_report,node_release,node_policies toneBlue
class node_pricing,node_revenue,node_ledger,node_customers,node_signals,node_plans toneAmber
class node_postgres,node_valkey,node_worker toneMint
class node_dashboard_api,node_dashboard_ui,node_policy_ui,node_access toneRose
class node_client_app,node_ai_provider toneIndigo
```

## Components

### Runtime decisions

- [HTTP API](https://github.com/preburn/preburn/blob/main/internal/httpapi/api.go): `internal/httpapi/api.go`
- [Check decision](https://github.com/preburn/preburn/blob/main/internal/decisions/check.go): `internal/decisions/check.go`
- [Usage report](https://github.com/preburn/preburn/blob/main/internal/decisions/report_routes.go): `internal/decisions/report_routes.go`
- [Release reservation](https://github.com/preburn/preburn/blob/main/internal/decisions/release.go): `internal/decisions/release.go`
- [Policy rules](https://github.com/preburn/preburn/blob/main/internal/policies/resolution.go): `internal/policies/resolution.go`

### Pricing and margin

- [Usage pricing](https://github.com/preburn/preburn/blob/main/internal/pricing/rating.go): `internal/pricing/rating.go`
- [Revenue records](https://github.com/preburn/preburn/blob/main/internal/revenue/service.go): `internal/revenue/service.go`
- [Cost ledger](https://github.com/preburn/preburn/blob/main/internal/ledger/entries.go): `internal/ledger/entries.go`
- [Customer records](https://github.com/preburn/preburn/blob/main/internal/customers/service.go): `internal/customers/service.go`
- [Margin signals](https://github.com/preburn/preburn/blob/main/internal/signals/signals.go): `internal/signals/signals.go`
- [Plans and allowances](https://github.com/preburn/preburn/blob/main/internal/plans/service.go): `internal/plans/service.go`

### Operations and state

- **Postgres**
- **Valkey counters**
- [Background worker](https://github.com/preburn/preburn/blob/main/internal/app/worker.go): `internal/app/worker.go`

### Dashboard and access

- [Dashboard API](https://github.com/preburn/preburn/blob/main/internal/dashboard/overview_routes.go): `internal/dashboard/overview_routes.go`
- [Dashboard UI](https://github.com/preburn/preburn/blob/main/web/src/features/overview/overview-page.tsx): `web/src/features/overview/overview-page.tsx`
- [Policy editor](https://github.com/preburn/preburn/blob/main/web/src/features/policies/policy-editor.tsx): `web/src/features/policies/policy-editor.tsx`
- [Members and keys](https://github.com/preburn/preburn/blob/main/internal/members/routes.go): `internal/members/routes.go`

### Other components

- **Customer app**
- **AI provider**

## Connections

- Customer app → HTTP API: checks and reports
- Customer app → AI provider: calls directly
- HTTP API → Check decision: dispatches checks
- HTTP API → Usage report: dispatches reports
- HTTP API → Release reservation: dispatches releases
- Check decision → Usage pricing: prices estimate
- Check decision → Margin signals: computes margin
- Check decision → Policy rules: applies policy
- Usage report → Usage pricing: prices usage
- Usage report → Cost ledger: records cost
- Revenue records → Customer records: creates unknown
- Dashboard UI → Dashboard API: requests data
- Policy editor → HTTP API: manages policies
- Members and keys → Postgres: stores access state
- HTTP API → Postgres: reads and writes
- HTTP API → Valkey counters: reads and writes counters
- Background worker → Postgres: maintains records
- Background worker → Valkey counters: repairs counters