Skip to main content
Private Preview· Early access by invitation. Request access →
Kirimana.
Sign in Early access
Architecture

The medallion, contract-driven

Kirimana operationalises a contract-driven medallion. The medallion isn’t a pattern we suggest — it’s the structure every contract slots into.

The three layers

LayerRoleContract kind
BronzeRaw, tagged, source-of-truth landingbronze.<source>.<table>
SilverConformed, deduplicated, business-cleansilver.<domain>.<entity>
GoldKimball star schema for consumptiongold.<goal>.fact_<x> + gold.<goal>.dim_<y>

Every contract carries kirimana.medallion_state — bronze, silver, or gold. Drift between layers is contract-enforced. You can’t promote a silver contract to gold without the gold contract validating against the silver source. The state machine is the guardrail.

Bronze — the raw, tagged source of truth

  • One bronze contract per source-table
  • Ingestion-mode taxonomy (push / pull / streaming / CDC) is a first-class field
  • _kirimana_* provenance columns stamped on every row (where the ingest mode supports it)
  • Schema-drift detection at apply time + PR time
  • AI policy on bronze typically read: allowed, write: blocked — you don’t let an LLM mutate raw

Silver — three modeling techniques, one project-wide choice

The silver-layer technique is a project-wide strategic choice set at dca init, locked after the first silver contract is written. Three options, each fully supported with linters, generators, and how-tos.

1. Flat (denormalised)

  • One silver entity = one denormalised, deduplicated table
  • Best for: small teams, single-domain, rapid time-to-first-value
  • Lints check deduplication keys, business-time + system-time columns, surrogate keys when joining

2. Data Vault 2.0

  • Hubs + Links + Satellites split per source-system
  • Best for: regulated industries, M&A-heavy environments, source-system audit trail required
  • Lints check hub keys, link relationships, satellite versioning, hash-key generation

3. Kimball Dimensional (silver + gold)

  • Silver as conformed dimensions + facts; gold inherits and extends to goal-shaped star schemas
  • Best for: BI-heavy organisations, well-understood domains, fast consumption
  • Lints check SCD Type 2 dimension semantics, surrogate-key strategy, additivity flags on measures, conformed-dimension registry consistency

Why locked after first silver contract? Mixing techniques is a slow disaster. Locking is a governance decision the project commits to publicly. You can rerun dca init --reset-silver-technique with the right RBAC capability, but it’s an event, not a background change.

Gold — always Kimball

Gold is always Kimball, regardless of silver technique. Why:

  • Gold is the consumption surface — BI tools, semantic layers, KPIs all expect star schemas
  • Conformed dimensions across goals enable cross-domain analytics
  • The KPI workbench and semantic-layer exporters (dbt Semantic Layer / MetricFlow / Cube) target Kimball gold

The conformed-dimension registry detects cross-goal conflicts at PR time. You can’t ship gold.revenue.dim_customer if it’s incompatible with gold.churn.dim_customer already in production.

What contracts look like at each layer

# bronze
kind: DataContract
id: bronze.crm.account
owner: data-platform-engineer@your-org.example
customProperties:
  kirimana.classification: restricted
  kirimana.medallion_state: bronze
  kirimana.ingestion: { mode: airbyte, source_id: crm_account }
  kirimana.ai_policy: { read: allowed, write: blocked, audit: required }
# silver (Kimball-dimensional silver technique)
kind: DataContract
id: silver.customer_360.dim_customer
owner: data-product-owner@your-org.example
customProperties:
  kirimana.classification: restricted
  kirimana.medallion_state: silver
  kirimana.silver_technique: kimball_dimensional
  kirimana.scd_type: 2
  kirimana.lineage:
    upstream: [bronze.crm.account]
# gold
kind: DataContract
id: gold.revenue.fact_invoice
owner: analytics-engineer@your-org.example
customProperties:
  kirimana.classification: restricted
  kirimana.medallion_state: gold
  kirimana.gold:
    grain: invoice_line
    additivity: { amount: full, discount_pct: non_additive }
  kirimana.lineage:
    upstream: [silver.customer_360.dim_customer, silver.billing.fact_payment]
    goal: customer-segment-revenue-Q3

Where Kirimana enforces the pattern

  • dca contract lint — six star-schema lint rules at gold; silver-technique-specific rules at silver
  • dca init — locks the silver technique
  • kirimana.gold.* customProperties — additivity, SCD type, surrogate-key strategy
  • Conformed-dimension registry — cross-goal conflict detection
  • AI assist — dca suggest gold routes to fact or dimension prompts based on context

When the medallion isn’t right

If your organisation has a hard reason not to do medallion (an explicit ML-feature-store-only architecture, for example), Kirimana isn’t a hard requirement. You can use individual primitives — the contract artefact, the AI policy gate, the audit redaction — without the bronze→silver→gold structure. But you’ll lose the linters and the gold semantic-layer exporters.

We don’t recommend it. The medallion is the structure that makes contracts compose.

Linked resources