Architecture
OpenMeter separates high-volume usage data from transactional application state. The following diagram shows the primary runtime components and data flows; it omits observability and deployment-specific infrastructure.
Kafka decouples event ingestion from asynchronous processing. ClickHouse stores and aggregates usage data, while PostgreSQL remains the source of truth for transactional product and billing state.
Dashed edges are optional, configuration-dependent flows: event deduplication is disabled by default and uses an in-process memory store unless the Redis driver is configured, and the API server can additionally use Redis for ingest-side deduplication and for tracking long-running query progress.
Not every connection is drawn: the billing worker and scheduled jobs also query usage from ClickHouse, the sink worker reads meter definitions from PostgreSQL, and scheduled jobs run maintenance reads and writes against PostgreSQL.
Components
| Component | Responsibility |
|---|---|
| API server | Event ingestion, management APIs, usage queries, and webhook delivery. |
| Sink worker | Validates, deduplicates, and persists usage events to ClickHouse. |
| Balance worker | Calculates entitlement and credit balances, publishes balance snapshot events. |
| Billing worker | Subscription synchronization, rating, and the invoice lifecycle. |
| Notification service | Evaluates notification rules and records pending notification events. |
| Scheduled jobs | Migrations and cross-domain maintenance. |
The notification service evaluates rules and records pending notification events; actual webhook delivery to Svix runs as a leader-elected reconciler inside the API server. A separate optional Collector component can buffer and forward events from external sources to the ingest API.
Messaging and State
| Dependency | Role |
|---|---|
| Kafka | Transports usage and domain events between the API server and the workers. |
| ClickHouse | Stores usage events and aggregates for metering queries. |
| PostgreSQL | Source of truth for customers, product catalog, subscriptions, billing, and entitlements. |
| Redis | Optional: event deduplication and long-running query progress state. |
| Svix | Webhook delivery to subscribed consumers. |
Ingestion Data Flow
The write path for a usage event, from producer to queryable usage:
- Producers send usage events to the ingest API in CloudEvents format.
- The API server publishes accepted events to Kafka.
- The sink worker consumes, validates, and deduplicates events, then persists them to ClickHouse.
- Meters aggregate the stored usage, and the API serves meter queries from ClickHouse.
Last updated on