# openmeterio/openmeter architecture

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

- Interactive diagram: https://gitdiagram.com/openmeterio/openmeter
- Repository: https://github.com/openmeterio/openmeter

## Overview

OpenMeter is API-first usage-based monetization infrastructure. Its principal workflow accepts usage events, meters and aggregates them, exposes usage queries and access decisions, then supports pricing, subscriptions, credits, and invoicing. The graph highlights those domain stages, the HTTP/API entry layer, and storage. Several domain capabilities are documented in the README but their internal wiring is not shown in the excerpts, so those links are documented rather than inferred from module names.

Main entry points: [`openmeter/billing/lineengine/engine.go`](https://github.com/openmeterio/openmeter/blob/main/openmeter/billing/lineengine/engine.go) (Invoice line engine), [`api/v3/server/routes.go`](https://github.com/openmeterio/openmeter/blob/main/api/v3/server/routes.go) (API routes), [`openmeter/streaming/clickhouse/meter_query.go`](https://github.com/openmeterio/openmeter/blob/main/openmeter/streaming/clickhouse/meter_query.go) (Usage aggregation), [`openmeter/server/server.go`](https://github.com/openmeterio/openmeter/blob/main/openmeter/server/server.go) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and clients"]
  node_server["HTTP server<br/>[server.go]"]
  node_routes["API routes<br/>[routes.go]"]
  node_sdk["JavaScript SDK<br/>[events.ts]"]
end

subgraph group_metering["Usage metering"]
  node_ingest["Event ingestion<br/>[ingest.go]"]
  node_sink["Event storage<br/>[storage.go]"]
  node_streaming[("Usage aggregation<br/>[meter_query.go]")]
  node_meter_query["Meter queries<br/>[query.go]"]
end

subgraph group_access["Access control"]
  node_entitlement_worker["Balance updates<br/>[ingesthandler.go]"]
  node_access_check["Access decisions"]
end

subgraph group_billing["Catalog and billing"]
  node_catalog["Plans and pricing"]
  node_subscriptions["Subscriptions"]
  node_credits["Customer credits"]
  node_billing_engine["Invoice line engine<br/>[engine.go]"]
  node_usage_charges["Usage charges<br/>[lineengine.go]"]
  node_flat_charges["Flat charges<br/>[lineengine.go]"]
  node_invoice_store[("Invoice-line queries")]
end

node_developer(("API client"))
node_event_source(("Usage producer"))
node_external_services["Payment and tax providers"]

node_developer -->|"calls API"| node_server
node_developer -->|"uses SDK"| node_sdk
node_sdk -.->|"sends requests"| node_server
node_server -->|"serves routes"| node_routes
node_event_source -->|"submits events"| node_ingest
node_ingest -.->|"stores events"| node_sink
node_sink -->|"inserts events"| node_streaming
node_streaming -->|"provides usage"| node_meter_query
node_streaming -->|"usage affects balances"| node_entitlement_worker
node_routes -.->|"routes access calls"| node_access_check
node_routes -->|"routes subscription calls"| node_subscriptions
node_catalog -->|"defines offerings"| node_subscriptions
node_subscriptions -.->|"supports billing"| node_billing_engine
node_billing_engine -.->|"delegates usage lines"| node_usage_charges
node_billing_engine -.->|"delegates flat lines"| node_flat_charges
node_usage_charges -.->|"produces invoice lines"| node_invoice_store
node_flat_charges -.->|"produces invoice lines"| node_invoice_store
node_credits -->|"credits billing"| node_billing_engine
node_billing_engine -.->|"integrates providers"| node_external_services

click node_server "https://github.com/openmeterio/openmeter/blob/main/openmeter/server/server.go"
click node_routes "https://github.com/openmeterio/openmeter/blob/main/api/v3/server/routes.go"
click node_sdk "https://github.com/openmeterio/openmeter/blob/main/api/spec/packages/aip-client-javascript/src/funcs/events.ts"
click node_ingest "https://github.com/openmeterio/openmeter/blob/main/openmeter/ingest/httpdriver/ingest.go"
click node_sink "https://github.com/openmeterio/openmeter/blob/main/openmeter/sink/storage.go"
click node_streaming "https://github.com/openmeterio/openmeter/blob/main/openmeter/streaming/clickhouse/meter_query.go"
click node_meter_query "https://github.com/openmeterio/openmeter/blob/main/openmeter/meter/httphandler/query.go"
click node_entitlement_worker "https://github.com/openmeterio/openmeter/blob/main/openmeter/entitlement/balanceworker/ingesthandler.go"
click node_access_check "https://github.com/openmeterio/openmeter/tree/main/api/v3/handlers/customers/entitlementaccess"
click node_catalog "https://github.com/openmeterio/openmeter/tree/main/openmeter/productcatalog"
click node_subscriptions "https://github.com/openmeterio/openmeter/tree/main/api/v3/handlers/subscriptions"
click node_credits "https://github.com/openmeterio/openmeter/tree/main/api/v3/handlers/customers/credits"
click node_billing_engine "https://github.com/openmeterio/openmeter/blob/main/openmeter/billing/lineengine/engine.go"
click node_usage_charges "https://github.com/openmeterio/openmeter/blob/main/openmeter/billing/charges/usagebased/service/lineengine.go"
click node_flat_charges "https://github.com/openmeterio/openmeter/blob/main/openmeter/billing/charges/flatfee/service/lineengine.go"
click node_invoice_store "https://github.com/openmeterio/openmeter/blob/main/openmeter/ent/db/billinginvoiceline_query.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_server,node_routes,node_sdk,node_developer toneBlue
class node_ingest,node_sink,node_streaming,node_meter_query toneAmber
class node_entitlement_worker,node_access_check toneMint
class node_catalog,node_subscriptions,node_credits,node_billing_engine,node_usage_charges,node_flat_charges,node_invoice_store toneRose
class node_event_source,node_external_services toneIndigo
```

## Components

### API and clients

- [HTTP server](https://github.com/openmeterio/openmeter/blob/main/openmeter/server/server.go): `openmeter/server/server.go`
- [API routes](https://github.com/openmeterio/openmeter/blob/main/api/v3/server/routes.go): `api/v3/server/routes.go`
- [JavaScript SDK](https://github.com/openmeterio/openmeter/blob/main/api/spec/packages/aip-client-javascript/src/funcs/events.ts): `api/spec/packages/aip-client-javascript/src/funcs/events.ts`

### Usage metering

- [Event ingestion](https://github.com/openmeterio/openmeter/blob/main/openmeter/ingest/httpdriver/ingest.go): `openmeter/ingest/httpdriver/ingest.go`
- [Event storage](https://github.com/openmeterio/openmeter/blob/main/openmeter/sink/storage.go): `openmeter/sink/storage.go`
- [Usage aggregation](https://github.com/openmeterio/openmeter/blob/main/openmeter/streaming/clickhouse/meter_query.go): `openmeter/streaming/clickhouse/meter_query.go`
- [Meter queries](https://github.com/openmeterio/openmeter/blob/main/openmeter/meter/httphandler/query.go): `openmeter/meter/httphandler/query.go`

### Access control

- [Balance updates](https://github.com/openmeterio/openmeter/blob/main/openmeter/entitlement/balanceworker/ingesthandler.go): `openmeter/entitlement/balanceworker/ingesthandler.go`
- [Access decisions](https://github.com/openmeterio/openmeter/tree/main/api/v3/handlers/customers/entitlementaccess): `api/v3/handlers/customers/entitlementaccess`

### Catalog and billing

- [Plans and pricing](https://github.com/openmeterio/openmeter/tree/main/openmeter/productcatalog): `openmeter/productcatalog`
- [Subscriptions](https://github.com/openmeterio/openmeter/tree/main/api/v3/handlers/subscriptions): `api/v3/handlers/subscriptions`
- [Customer credits](https://github.com/openmeterio/openmeter/tree/main/api/v3/handlers/customers/credits): `api/v3/handlers/customers/credits`
- [Invoice line engine](https://github.com/openmeterio/openmeter/blob/main/openmeter/billing/lineengine/engine.go): `openmeter/billing/lineengine/engine.go`
- [Usage charges](https://github.com/openmeterio/openmeter/blob/main/openmeter/billing/charges/usagebased/service/lineengine.go): `openmeter/billing/charges/usagebased/service/lineengine.go`
- [Flat charges](https://github.com/openmeterio/openmeter/blob/main/openmeter/billing/charges/flatfee/service/lineengine.go): `openmeter/billing/charges/flatfee/service/lineengine.go`
- [Invoice-line queries](https://github.com/openmeterio/openmeter/blob/main/openmeter/ent/db/billinginvoiceline_query.go): `openmeter/ent/db/billinginvoiceline_query.go`

### Other components

- **API client**
- **Usage producer**
- **Payment and tax providers**

## Connections

- API client → HTTP server: calls API (evidence: `README.md`)
- API client → JavaScript SDK: uses SDK (evidence: `README.md`)
- JavaScript SDK → HTTP server: sends requests
- HTTP server → API routes: serves routes (evidence: `openmeter/server/server.go`)
- Usage producer → Event ingestion: submits events (evidence: `README.md`)
- Event ingestion → Event storage: stores events
- Event storage → Usage aggregation: inserts events (evidence: `openmeter/sink/storage.go`)
- Usage aggregation → Meter queries: provides usage (evidence: `openmeter/meter/httphandler/query.go`)
- Usage aggregation → Balance updates: usage affects balances (evidence: `README.md`)
- API routes → Access decisions: routes access calls (evidence: `api/v3/server/routes.go`)
- API routes → Subscriptions: routes subscription calls (evidence: `api/v3/server/routes.go`)
- Plans and pricing → Subscriptions: defines offerings (evidence: `README.md`)
- Subscriptions → Invoice line engine: supports billing
- Invoice line engine → Usage charges: delegates usage lines
- Invoice line engine → Flat charges: delegates flat lines
- Usage charges → Invoice-line queries: produces invoice lines
- Flat charges → Invoice-line queries: produces invoice lines
- Customer credits → Invoice line engine: credits billing (evidence: `README.md`)
- Invoice line engine → Payment and tax providers: integrates providers (evidence: `README.md`)
