Cost attribution engine¶


ID	`MOD-098`
System	SD06
Repo	`bank-risk-platform`
Build status	Deployed
Deployed	Yes
Last commit	`adef045`

Purpose¶

MOD-098 converts raw usage events and infrastructure costs into attributed financial figures — per licensee, per module, per billing period. It is the engine that makes the three-part tariff (customer levy + facility fee + variable consumption) computable in Snowflake, and produces the data that the billing report (MOD-099) and internal finance reporting (MOD-080) consume.

Cost sources¶

1. Usage events (from MOD-097)¶

Reads metering.usage_events in Snowflake. Joins to metering.cost_rates to derive attributed cost per event type. Aggregates to daily tenant × module summaries.

2. AWS infrastructure costs¶

A daily scheduled Lambda calls the AWS Cost Explorer API (get_cost_and_usage) filtered by the tenant_id tag. Results are written to metering.aws_cost_daily. The Cost Explorer data is 24–48 hours lagged — the current day's infrastructure cost is estimated from the prior day's rate until actuals arrive.

Dimensions pulled: - SERVICE (Lambda, S3, Kinesis, API Gateway, DynamoDB, EventBridge, Secrets Manager, etc.) - UsageType (for resource-level granularity within each service) - Tag: tenant_id, module_id

Untagged costs accumulate to a tenant_id = "unattributed" bucket. These are monitored and alerted via MOD-034 if they exceed a configured threshold of total daily AWS spend.

3. Snowflake compute costs¶

Reads snowflake.account_usage.query_history and snowflake.account_usage.metering_history (1-hour lag). For dedicated per-tenant warehouses, credits are attributed directly. For shared warehouses, attribution is proportional:

tenant_credit_cost = (tenant_query_credits / total_shared_warehouse_credits) × warehouse_cost_for_period

Results written to metering.snowflake_credit_daily.

4. External API costs (market data, enrichment, NZFMA)¶

Pulled by MOD-097's external cost Lambda and available in metering.external_api_costs. Attribution is by the module that made the call — which is tagged in the usage event.

Billing model computation¶

Customer levy¶

customer_levy = active_customers_this_month × rate_card.customer_per_month

active_customers_this_month is the count of distinct customer_id records with at least one transaction in the billing period, read from CDC-replicated accounts.accounts.

Facility fee¶

facility_fee = SUM(activated_modules × rate_card.module_per_month)

Activated modules are defined in billing.tenant_modules (set at onboarding; updated when licensee activates/deactivates a module).

Variable consumption¶

For each variable resource type (Snowflake credits, API calls, ML inferences, notification sends, storage-GB):

variable_charge = MAX(0, actual_usage − included_threshold) × rate_card.variable_rate

Included thresholds are defined in billing.tenant_tiers (the tier the licensee subscribed to).

Infrastructure passthrough (optional)¶

infra_passthrough = actual_aws_cost_tagged_to_tenant + actual_snowflake_cost_attributed_to_tenant

This is the cost-basis transparency line. Shown separately on the report so licensees can see the markup.

Rate card management¶

metering.cost_rates is the canonical rate card. It is versioned by effective_from date. A rate card change (e.g. AWS price decrease, Snowflake pricing update) creates a new version; existing billing periods use the rate card active at their start date. Rate card updates require approval and are never retroactive.

Output Dynamic Tables¶

Table	Refresh	Description
`metering.daily_tenant_summary`	INCREMENTAL, 1h lag	Per-tenant daily cost by module and resource type
`metering.billing_period_summary`	FULL, 4h lag	Rolling billing period totals: levy + facility + variable + passthrough
`metering.unit_economics`	FULL, daily	Internal view: cost to serve per module per customer, gross margin by tenant
`metering.unattributed_costs`	INCREMENTAL, 1h lag	AWS costs with no tenant tag — monitored for tagging gaps

Streamlit dashboard¶

MOD-098 ships a Streamlit page METERING.STREAMLIT_COST_DASHBOARD providing: - Cost allocation by system domain (SD01–SD08) for the current month and trailing 12 months - Cost allocation by product line - Period-over-period comparison - Cost driver category breakdown per domain (infrastructure, headcount-equivalent, shared services)

Consumed by MOD-171 (Risk Intelligence Dashboard) in the risk metrics overview section (cost attribution panel). Consumed by MOD-172 (Operations & Model Intelligence Dashboard) in the cost attribution view. Cross-schema SELECT on METERING.* published views required for RISK_INTELLIGENCE_ROLE and OPERATIONS_ROLE.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-097	Usage event collector	Required	—	Cost attribution reads metering.usage_events produced by the usage event collector as the input data source.
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.
MOD-102	Snowflake account configuration & governance	Required	—	Snowflake account and governance provisioned by MOD-102 must exist before this module can read or write Snowflake.
MOD-171	Risk Intelligence Dashboard	Required	—	Risk Intelligence Dashboard displays cost attribution by system domain in its risk metrics overview section.
MOD-172	Operations & Model Intelligence Dashboard	Required	—	Operations & Model Intelligence Dashboard uses cost attribution published views as its cost view section.

Required by¶

Module	Title	As	Contract
MOD-099	Infrastructure cost reports	Hard dependency	—
MOD-171	Risk Intelligence Dashboard	Hard dependency	—
MOD-172	Operations & Model Intelligence Dashboard	Hard dependency	—

Policies satisfied¶

Policy	Title	Mode	How
REP-001	Regulatory Reporting Policy	`CALC`	Produces daily attributed cost and running billing period totals per licensee — the authoritative source for SaaS invoices and internal gross margin reporting.

Capabilities satisfied¶

Capability	Title	Mode	How
CAP-140	CAP-140	`CALC`	Reads metering.usage_events from Snowflake; pulls AWS Cost Explorer API daily for tagged infrastructure costs; pulls Snowflake metering_history for credit consumption; applies the rate card to produce attributed cost per tenant per module; writes daily snapshots to metering.daily_tenant_summary and rolling billing period totals to metering.billing_period_summary Dynamic Tables.

Part of SD06 — Snowflake Analytics & Risk Platform Compiled 2026-05-22 from source/entities/modules/MOD-098.yaml