Skip to content

Snowflake read API service
ID MOD-176
System SD07
Repo bank-platform
Build status Deployed
Deployed Yes
Last commit 5ecab7c07737b2efd3acf97d348c9a1b47974769

The Snowflake read API service is the governed gateway between application services and Snowflake Tier 3 data (ADR-038). It is the concrete implementation of the "Snowflake read API" service mandated by ADR-038 and is built in bank-platform (SD07) because the auth, circuit-breaking, warehouse management, and query governance concerns are platform-wide, not scoped to any single system domain.

Two access patterns

Tier 3a — Customer-facing signals

Pre-shaped presentation table point lookups scoped to the requesting customer's party_id. These serve the customer mobile/web app via bank-app. Queries are trivial indexed lookups against purpose-built presentation tables refreshed by Snowflake Dynamic Tables.

  • Warehouse: Dedicated XS warehouse, always-on during business hours, 10-minute auto-suspend on inactivity
  • Latency target: ≤500ms p99
  • Scoping: Every query is bound to the authenticated party_id — the API rejects any query whose result set would span multiple customers regardless of parameters passed
  • Endpoint: GET /v1/snowflake/signals/{party_id}/{signal_type}

Tier 3b — Back-office and regulatory queries

Structured metric queries forwarded to the Snowflake Cortex Analyst REST API. These serve MOD-177 (SD06 risk dashboard renderer) and internal back-office tooling. Callers send structured metric requests {metric, groupBy, filters}; Cortex Analyst generates and executes the SQL against the SD06 modules' published semantic views.

  • Warehouse: Dedicated back-office warehouse, auto-suspend after inactivity
  • Latency target: ≤5 s p95 acceptable for back-office use
  • Scoping: Role-scoped via MOD-044 RBAC — Snowflake row access policies enforce the same restriction at the data layer as defence-in-depth
  • Endpoint: POST /v1/snowflake/metrics

Semantic view ownership

CREATE SEMANTIC VIEW DDL is authored and maintained by each SD06 module in its own migrations directory, alongside dbt models. MOD-176 has no knowledge of view structure — it is a proxy. Cortex Analyst resolves metric names against the semantic models registered in the Snowflake account. This preserves the schema-as-product contract (ADR-046): SD06 modules own their data and metric definitions; SD07 owns the query proxy and access governance.

Operational constraints

  • Circuit breaker (Tier 3a): If query latency exceeds 1 second p95, the API returns a structured degraded response ({available: false, reason: "snowflake_latency"}). Slow Snowflake has zero impact on the transaction path.
  • Circuit breaker (Tier 3b): 10-second timeout; structured error response on breach.
  • Query governance: Every query is logged with caller identity, query type, metric name or signal type, warehouse, query duration, and Snowflake query ID — for cost attribution and anomaly detection via MOD-076.
  • No cache: Presentation table freshness (Tier 3a) is managed by Dynamic Table refresh cadence. Tier 3b results are not cached — Cortex Analyst latency on the back-office warehouse is acceptable.

Module dependencies

Depends on

Module Title Required? Contract Reason
MOD-044 JWT role-based access control Required — JWT RBAC tokens issued by MOD-044 are verified on every inbound query to enforce per-caller and role-scoped access control.
MOD-102 Snowflake account configuration & governance Required — Snowflake account configuration, warehouse provisioning, and RBAC roles managed by MOD-102 are prerequisites — both the XS customer warehouse and the back-office warehouse must be provisioned before this module can be deployed.
MOD-104 AWS shared infrastructure bootstrap Required — AWS shared infrastructure (Lambda runtime, API Gateway, IAM, KMS) provisioned by MOD-104 is required before this module can be deployed.
MOD-075 Internal API gateway Required — Inbound requests from bank-app are routed through the internal API gateway; this service is registered as a backend on MOD-075.

Required by

Module Title As Contract
MOD-177 SD06 risk dashboard renderer Hard dependency —

Policies satisfied

Policy Title Mode How
DT-001 Information Security Policy GATE All inbound queries pass through TLS-terminated, JWT-authenticated endpoints — no Snowflake credentials are exposed to calling services or the browser.
DT-002 Cybersecurity Policy GATE Per-caller rate limiting and RBAC role scoping enforced at the API layer — unauthenticated or out-of-scope queries are rejected before reaching Snowflake.

Capabilities satisfied

(No capabilities mapped)

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