Skip to main content

Functional Specification Document: IPU Metering and Billing System

Category: architecture
Author: Pramod Prasanth
Version: 1.0
Date: September 29, 2025
Status: Draft

1.0 Overview​

1.1. Introduction​

This document outlines the functional requirements for the Intelligence Processing Unit (IPU) Metering and Billing System. This system is the core operational component of ChainAlign's hybrid value-based pricing model. Its purpose is to accurately track the consumption of high-value computational events (IPUs), provide customers with transparent visibility into their usage, and generate the necessary data for billing.

1.2. Business Rationale​

As defined in the ChainAlign Pricing Strategy, the IPU model is designed to align revenue with customer value. Customers pay more as they derive more value from complex, AI-driven decisions. This system is critical to:

  • Monetize Value: Capture expansion revenue by billing for usage of the most advanced platform capabilities (simulations, AI recommendations).
  • Build Trust: Provide customers with radical transparency into what they are paying for, eliminating "bill shock" and justifying the platform's cost.
  • Enable Sales: Give the sales team a clear, defensible, and scalable pricing model to present to enterprise buyers.

2.0 Core Requirements​

2.1. Functional Requirements​

  • The system must track usage events triggered by specific, high-value backend operations.
  • The system must associate each usage event with a specific tenant and user.
  • The system must provide an administrative dashboard for customers to view their current and historical IPU usage.
  • The customer-facing dashboard must show the current consumption against the monthly quota.
  • The dashboard must provide an auditable log of individual usage events.
  • The backend must expose a secure API endpoint to provide usage data to the frontend.

2.2. Non-Functional Requirements​

  • Scalability: The tracking mechanism must be non-blocking and capable of handling a high volume of events without impacting application performance.
  • Accuracy: The metering system must be the single source of truth for billing, requiring 100% accuracy in event capture.
  • Auditability: All usage data must be stored in an immutable log format.
  • Configurability: The cost (in IPUs) of each event type must be easily configurable without requiring a code deployment.

3.0 Proposed Technical Solution​

This solution is designed as a pragmatic v1.0 that can be implemented within the current Node.js backend, with a clear path to a more distributed microservices architecture in the future.

3.1. Backend Architecture​

3.1.1. Database Schema​

Two new tables will be created via a knex migration.

  1. ipu_usage_events: An immutable log of every billable event.

    • id: BIGSERIAL, Primary Key
    • tenant_id: UUID, FK to tenants.id, indexed
    • user_id: UUID, FK to users.id
    • event_type: VARCHAR(255) (e.g., COMPLEX_SIMULATION)
    • ipu_cost: DECIMAL(10, 4)
    • trace_id: UUID (Links to the specific decision/workflow run for auditability)
    • internal_cost_data: JSONB (For internal use. Stores raw cost metrics like LLM tokens, CPU time, etc.)
    • created_at: TIMESTAMPTZ, default now()

  2. tenant_billing_cycles: An aggregate table for efficient querying.

    • id: BIGSERIAL, Primary Key
    • tenant_id: UUID, FK to tenants.id, indexed
    • cycle_start_date: DATE
    • cycle_end_date: DATE
    • ipu_quota: INTEGER (The tenant's monthly quota based on their subscription tier)
    • total_ipus_consumed: DECIMAL(10, 4), default 0

3.1.2. IPU Cost Configuration​

A new configuration file will define the IPU cost for each event.

  • File Location: backend/src/config/ipuCosts.js
  • Content: 
    module.exports = {
      // 1 IPU = €20 as per strategy document
      COMPLEX_SIMULATION: 1.0,
      MARKET_RECOMMENDATION: 1.0,
      STANDARD_SCENARIO_ANALYSIS: 0.5,
    };

3.1.3. Metering Service​

A new centralized service will handle all usage recording logic.

  • File Location: backend/src/services/meteringService.js
  • Primary Method: async recordUsage(tenantId, userId, eventType, traceId)
    • Retrieves ipu_cost from ipuCosts.js.
    • Inserts a record into the ipu_usage_events table.
    • Updates the total_ipus_consumed in the tenant_billing_cycles table for the current cycle. This will be an atomic UPDATE ... SET total_ipus_consumed = total_ipus_consumed + ? operation.

3.1.4. API Endpoint​

A new route will be created to expose usage data to the frontend.

  • Route: GET /api/usage
  • Authentication: Must be authenticated and authorized. Only users with an "Orchestrator" or "Admin" role can access it.
  • Response Body: 
    {
      "ipuQuota": 750,
      "ipusConsumed": 350.5,
      "cycleStartDate": "2025-09-01T00:00:00.000Z",
      "cycleEndDate": "2025-09-30T23:59:59.999Z",
      "usageHistory": [
        {
          "timestamp": "2025-09-28T10:00:00.000Z",
          "eventType": "COMPLEX_SIMULATION",
          "ipuCost": 1.0,
          "user": "Pramod M.",
          "traceId": "uuid-for-decision-1"
        },
        // ... more events
      ]
    }

3.2. Frontend Implementation​

3.2.1. New Page: Usage Dashboard​

A new page will be created, accessible from the main application dashboard (e.g., under "Settings" or "Billing").

  • File Location: frontend/src/pages/UsageDashboardPage.jsx
  • Functionality: This page will fetch data from the GET /api/usage endpoint upon loading.

3.2.2. UI Components​

The dashboard will feature three main components as described in the pricing concept notes:

  1. The Consumption Gauge:

    • A large visual progress bar or gauge.
    • Displays text: "350.5 / 750 IPUs consumed".
    • The bar color could change from green to yellow to red as usage approaches the quota.

  2. Usage Analytics & Projections:

    • A small card displaying "Estimated days remaining" in the current cycle, calculated based on the average daily usage over the past week.
    • A pie chart visualizing the "Top Cost Drivers", breaking down IPU consumption by eventType.

  3. Detailed Audit Log:

    • A data table displaying the usageHistory array from the API.
    • Columns: Date, Decision Type, IPU Cost, User, Details (link to trace).
    • This provides the line-item evidence to build customer trust.

4.0 Out of Scope (for v1.0)​

  • Real-time Alerts: Proactive email or in-app notifications when a customer reaches 80%, 90%, and 100% of their IPU quota will be implemented in a future version.
  • Automated Invoicing: This system will provide the necessary data for billing, but the generation of invoices and payment processing is out of scope for this FSD.
  • Sidecar Architecture: The initial implementation will be a centralized service in the Node.js monolith. Migration to a more scalable sidecar/event queue architecture (e.g., Kafka) will be considered as the platform scales.

5.0 Success Metrics​

  • Customer Self-Service: Reduction in support tickets related to billing and usage questions.
  • Data Accuracy: 100% reconciliation between logged usage events and generated invoices.
  • User Engagement: High engagement with the Usage Dashboard page, indicating customers find it valuable.
  • Revenue Enablement: Successful billing and collection for IPU overages.