Usage event collector

ID	MOD-097
System	SD07
Repo	bank-platform
Build status	Deployed
Deployed	Yes
Last commit	bbdfbac46a1b5cf6dc25b4c7cd428a8daa669d03

---

Purpose

MOD-097 is the instrumentation layer for the entire platform. It collects a structured usage event every time any module performs a billable operation, and streams those events into the Snowflake metering schema where they become the raw material for cost attribution, billing, and unit economics analysis.

The module introduces no changes to individual module code. Instrumentation is applied as a shared Lambda layer attached to all tenant-context function invocations, and via EventBridge rule patterns that capture billable operations by their existing event shapes.

What counts as a billable usage event

Event type	Examples	Unit
API_CALL	Customer API request through API Gateway	Per call
ML_INFERENCE	Fraud score, credit score, categorisation, enrichment	Per inference
SNOWFLAKE_QUERY	Risk model run, regulatory calculation, analytics query	Per credit consumed
ENRICHMENT_CALL	Merchant name/logo lookup, geo-enrichment, market data	Per call
NOTIFICATION_SEND	Push notification, SMS, email via Pinpoint	Per send
DOCUMENT_STORE	S3 put/get for KYC documents, receipts	Per MB
CDC_EVENT	Kinesis Firehose record delivered to Snowflake	Per 1,000 records
DECISION_PUBLICATION	Snowflake write-back to Postgres (MOD-079 pattern)	Per write

Event schema

Every usage event emitted to the bank-platform EventBridge bus has the following structure:

{
  "source": "bank.platform.metering",
  "detail-type": "usage_event",
  "detail": {
    "schema_version": "1.0",
    "idempotency_key": "<uuid>",
    "tenant_id": "<licensee or 'self' for own platform>",
    "module_id": "MOD-XXX",
    "facility_id": "SD0X",
    "event_type": "API_CALL",
    "quantity": 1,
    "resource_units": 0.001,
    "resource_unit_type": "LAMBDA_GB_SECONDS",
    "environment": "prod",
    "timestamp": "2026-04-15T10:23:00Z",
    "correlation_id": "<originating request id>"
  }
}

tenant_id is "self" for the bank's own customers (not SaaS licensees). This allows the same pipeline to generate both external SaaS billing and internal unit economics.

Pipeline

Lambda invocation (any module)
  └─ Lambda layer intercept → emit usage_event to EventBridge
        └─ EventBridge rule → Kinesis Data Firehose
              └─ S3 landing zone (compressed JSON, partitioned by date/tenant)
                    └─ Snowflake Snowpipe → metering.usage_events
                          └─ (available within ~5 minutes of event)

External API costs (Marketplace subscriptions, NZFMA, enrichment providers) are collected separately via a daily Lambda that reads invoices or usage reports from each provider and writes to metering.external_api_costs.

Tagging governance

Every AWS resource deployed for a tenant (Lambda, S3, Kinesis, DynamoDB, SQS, API Gateway stage) must carry the tags: - tenant_id — the licensee identifier (or self) - module_id — the module owning the resource - environment — prod / staging / dev

Missing tags cause the resource's costs to fall to the unattributed overhead bucket. IaC (SST/CDK) enforces required tags at the synthesis step. CI runs aws-cdk-lib/aws-config tag compliance rules before deploying to prod.

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-043	EventBridge domain event governance	Required	—	Usage events are emitted via the EventBridge domain event buses governed by the EventBridge governance module.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, S3, KMS, Kinesis, Cognito) is required before this module can be deployed.

Required by

Module	Title	As	Contract
MOD-098	Cost attribution engine	Hard dependency	—

---

Policies satisfied

Policy	Title	Mode	How
REP-001	Regulatory Reporting Policy	LOG	All billable usage events are logged with tenant, module, resource type, and timestamp — provides the immutable audit trail for SaaS billing and internal cost accounting.

---

Capabilities satisfied

Capability	Title	Mode	How
CAP-140	CAP-140	AUTO	Instruments all modules via a shared Lambda layer and EventBridge rule pattern; every billable operation emits a bank-platform.usage_event with tenant_id, module_id, event_type, quantity, and resource_units; events stream via Kinesis Firehose to S3 and into Snowflake metering.usage_events within 5 minutes.

---

Part of SD07 — Data Platform & Governance Infrastructure Compiled 2026-05-22 from source/entities/modules/MOD-097.yaml