Navigation
On this page

System Architecture

This page explains the internal architecture of UsageFlow and how its components work together to provide a scalable usage-based billing platform.

UsageFlow is designed to handle:

  • high-volume usage event ingestion
  • flexible pricing configuration
  • automated invoice generation
  • reliable webhook delivery

High-Level Architecture

UsageFlow is built as a multi-tenant SaaS platform with several core components.

Client Application
↓
UsageFlow API
↓
PostgreSQL Database
↓
Background Workers
↓
Webhook Delivery

Each component plays a specific role in the billing pipeline.

Core Components

Dashboard (Frontend)

The dashboard is built using Next.js and provides a user interface for organizations to manage their billing configuration.

Organizations can:

  • create metrics
  • configure pricing plans
  • generate API keys
  • view usage analytics
  • inspect invoices
  • configure webhook endpoints

This interface allows teams to manage billing without writing code.

Public API Layer

UsageFlow exposes APIs for:

  • tracking usage events
  • retrieving invoices
  • checking subscriptions

Example APIs:

POST /api/track
GET /api/invoices
GET /api/subscriptions

These endpoints allow external applications to integrate with UsageFlow.

Database Layer

UsageFlow stores all billing data in PostgreSQL.

Key tables include:

  • organizations
  • memberships
  • metrics
  • plans
  • plan_metrics
  • subscriptions
  • usage_events
  • aggregated_usage
  • invoices
  • webhook_events
  • webhook_deliveries
  • audit_logs

Each table represents a specific entity within the billing system.

Multi-Tenant Design

UsageFlow supports multiple organizations using a single database.

Each record includes an orgId field that isolates data between tenants.

Example:

Organization A

  • usage events
  • invoices
  • subscriptions

Organization B

  • separate billing data

This approach allows UsageFlow to scale while maintaining strict data isolation.

Usage Event Ingestion

Usage events are the foundation of the billing system.

When an application performs a billable action, it sends a request to the ingestion API.

Example:

POST /api/track

Example payload:

{
  "metric": "API_CALL",
  "amount": 1,
  "customerId": "user_123"
}

Usage events are stored in the usage_events table.

These raw events serve as the source of truth for billing calculations.

Usage Aggregation

Processing millions of raw usage events directly during invoice generation would be inefficient.

To solve this, UsageFlow aggregates usage events periodically.

Aggregation pipeline:

Raw Usage Events
↓
Aggregation Worker
↓
Aggregated Usage Records

Example aggregated record:

Metric: API_CALL
Total Usage: 12,000
Billing Period: March

Aggregated usage is stored in the aggregated_usage table.

This improves performance when calculating invoices.

Invoice Generation

Invoices are generated based on:

  • the active subscription
  • the plan configuration
  • aggregated usage data

Invoice calculation pipeline:

Subscription
↓
Plan Pricing Rules
↓
Aggregated Usage
↓
Invoice Generated

Example calculation:

Base Price: $100
API Calls: 12,000
Included: 10,000
Overage: 2,000 × $0.01
Total: $120

Invoices are stored in the invoices table and represent immutable financial records.

Webhook Delivery System

UsageFlow supports event-driven integrations using webhooks.

When important events occur, UsageFlow creates a webhook event.

Example events:

invoice.created
invoice.paid
invoice.failed
subscription.suspended

Webhook pipeline:

Billing Event
↓
Webhook Event Created
↓
Job Added to Queue
↓
Worker Sends HTTP Request
↓
Delivery Logged

Each delivery attempt is stored in the webhook_deliveries table.

Background Workers

UsageFlow uses background workers to process asynchronous tasks.

Worker responsibilities include:

  • usage aggregation
  • invoice generation
  • webhook delivery
  • retry logic for failed webhooks

Workers consume jobs from a queue system powered by BullMQ and Redis.

Example job types:

AGGREGATE_USAGE
GENERATE_INVOICE
DELIVER_WEBHOOK

This architecture keeps the main API responsive while processing heavy tasks in the background.

Security Considerations

UsageFlow implements several security mechanisms:

API Key Authentication

Usage ingestion APIs require a valid API key.

API keys are stored in hashed form to prevent leaks.

Idempotency Protection

Usage events include an Idempotency-Key header.

This prevents duplicate billing events when requests are retried.

Role-Based Access Control

Access to organization resources is restricted based on roles:

OWNER
ADMIN
DEVELOPER
VIEWER

Permissions are enforced at both the API and UI layers.

Scalability Considerations

UsageFlow is designed to scale as usage grows.

Key scalability features include:

  • event-based architecture
  • asynchronous workers
  • aggregated usage storage
  • multi-tenant database design

This allows UsageFlow to support high-volume usage tracking and billing workloads.

Observability

UsageFlow provides visibility into system activity through:

  • webhook delivery logs
  • audit logs
  • usage analytics dashboards

This helps organizations monitor billing operations and debug issues.

Full Billing Pipeline

The complete UsageFlow pipeline looks like this:

Customer Uses Product
↓
Usage Event Sent to API
↓
Event Stored in Database
↓
Aggregation Worker Processes Events
↓
Aggregated Usage Stored
↓
Invoice Generated
↓
Webhook Notification Sent

This pipeline ensures accurate usage-based billing.

Summary

UsageFlow is composed of several core systems working together:

Frontend Dashboard
↓
Public APIs
↓
PostgreSQL Database
↓
Background Workers
↓
Webhook Integrations

Together, these components create a scalable usage-based billing platform for modern SaaS applications.

Next Steps

Continue exploring the documentation: