Most data platform writeups are comparisons. Snowflake vs BigQuery. Fivetran vs Airbyte. dbt vs SQLMesh. These are real choices, but they are not the ones that determine whether the platform succeeds. The hard decisions are architectural and organisational — made in Slack threads and Notion documents that get deleted, under deadline pressure, by people who will leave the company before the consequences arrive.
This is an attempt to surface seven of them. Not to give you a checklist, but to name the decisions so you can at least make them deliberately.
Decision 1: Prioritise sources by disagreement, not complexity
The instinct is to start with the most technically interesting source — usually the event stream or the product database. They are large, complex, and satisfying to model. They are also invisible to most of the business.
A better heuristic: start with the source that causes the most disagreement in meetings. In most B2B SaaS companies, that is CRM data (Salesforce) or billing data (Chargebee, Stripe). These sources power the numbers that appear in board decks and sales reviews. The moment you produce reliable, agreed-upon figures from them, you earn organisational credibility. That credibility is the political capital that funds the next six months of work.
Starting with a complex but low-visibility source produces an excellent pipeline that nobody notices — the analytics equivalent of drilling penalty kicks for a five-a-side game that never goes to penalties. Build where the pain is. Build where three versions of the same spreadsheet are circulating every Monday morning.
Decision 2: Write the layer contract before the first model
The staging / intermediate / mart separation is well-documented in dbt's own guides. What is almost never documented is the contract — the explicit, written rules about what each layer may and may not contain.
Without a written contract, the project drifts. An analyst adds a join to a staging model because it was faster. An engineer puts business logic in a mart because the intermediate model was too far away. Three months later, the same transformation exists in four places with subtly different results, and nobody agrees which one is correct.
The contract should be short enough to read in two minutes. Put it in your project README:
# Layer contract
Staging — one model per source table; rename, cast, deduplicate only;
no joins across sources; no business logic
Intermediate — business logic and cross-source joins;
never queried directly by BI tools or analysts
Marts — documented grain, documented owner, documented metric definitions;
the only layer BI tools and AI agents may read
Reference it in code review. Enforce it with dbt's model groups or linting rules. The specific rules matter less than the act of writing them down and making them visible.
Decision 3: Establish a materialisation policy, not a case-by-case habit
Table, view, incremental, or ephemeral — most teams decide on a per-model basis, in the moment, without a policy. That produces an inconsistent project where some marts are views (slow for dashboards), some staging models are tables (burning compute unnecessarily), and incremental models exist wherever someone once had a performance problem.
It's the difference between walking to the corner shop for milk every time and stocking your own fridge. A view is the corner-shop trip — always fresh, because you're reading the live source every time, but slow if you do it before every dashboard refresh. A table is the stocked fridge — fast to grab from, but only as fresh as your last shopping trip, which is exactly why a stale table is a worse failure mode than a stale view: nobody notices an empty shelf they can't see.
A simple default policy eliminates most of the decision overhead:
- Views for staging and lightweight intermediate models — cheap to rebuild, always current
- Tables for marts — fast for BI tools, predictable query performance
- Incremental only when the table is genuinely large and the transformation logic is stable enough to trust without a full rebuild
The qualifier on incremental is important. An incremental model accumulates errors silently. A logic bug in a full-refresh model gets corrected on the next run. In an incremental model, it affects every row added since the bug was introduced — and you may not notice until someone compares numbers across a date boundary.
Decision 4: Who owns the metric definition — and where is that written down
This is not a technical decision. It is an organisational one. But it has a technical output: the description field in schema.yml.
Most B2B SaaS companies have at least two conflicting definitions of MRR. Finance calculates it one way (recognised revenue, adjusted for timing). Sales calculates it another (contracted value, no adjustments). RevOps calculates it a third way (net of upgrades and downgrades, per their own cohort logic). Each team's spreadsheet produces a defensible number. None of them match.
The platform architect's job is to force this conversation, reach an agreed definition, and record the outcome in the codebase — not in Confluence, not in Notion, but in schema.yml next to the column it describes:
models:
- name: mart_subscription_mrr
columns:
- name: mrr_usd_cents
description: >
Monthly recurring revenue at period end, in USD cents. Calculated as
contracted subscription value divided by contract length in months.
Excludes usage-based components and one-time fees. Aligns with
Finance board reporting definition agreed 2025-Q1. For downgrade
treatment see mart_subscription_downgrades.
The phrase "agreed 2025-Q1" matters. Definitions change. Recording when the definition was agreed prevents the same argument from recurring indefinitely — and makes the next revision a deliberate decision rather than a quiet drift.
Decision 5: The documentation standard
Four types of documentation serve different readers and different purposes. The decision is where each type lives — and enforcing that consistently.
| Type | Purpose | Where it lives |
|---|---|---|
| Column descriptions | What this field means, how it is calculated, edge cases | schema.yml |
| Model descriptions | Grain, owner, what to use this for and what not to | schema.yml |
| Project context | Architecture decisions, conventions, domain vocabulary, AI tool configuration | README.md / CLAUDE.md |
| Change rationale | Why a definition changed, who approved it, what the previous behaviour was | dbt model description or commit message |
The failure mode: all of it ends up in Confluence, which falls out of date within weeks because it is decoupled from the code. Documentation that lives adjacent to the code it describes gets updated when the code changes. Documentation in a separate wiki gets updated when someone remembers.
There is a second-order benefit to schema.yml descriptions specifically: they become the knowledge base for AI querying. If you are building a governed LLM layer on top of your warehouse — as described in the governed AI post — the quality of your intent-matching prompts is directly determined by the precision of your model descriptions. Good docs do double duty.
Decision 6: Certified versus exploratory models — and making the distinction visible
Not all dbt models are equal. Some are certified: reviewed, tested, owned by someone accountable, safe to use in a board presentation. Others are exploratory: built for a specific analysis, not production-maintained, potentially stale after one sprint.
It's the difference between a reserved parking permit and a visitor pass. The permit holder gets a numbered spot, their name on file, and someone to call if it's blocked. The visitor pass gets you in for an afternoon, no guarantee it'll be there tomorrow, and nobody's annoyed if you don't renew it. Board decks should only ever park in permit spots.
The distinction must be visible — not just understood by the team who built it, but enforced structurally so that a new analyst connecting a BI tool to the warehouse cannot accidentally land on the wrong model.
The simplest mechanism is folder structure: marts/certified/ and marts/exploratory/. BI tools connect only to marts/certified/. Access policies restrict direct warehouse access to the same boundary. The exploratory folder exists and is usable — it just cannot silently enter a dashboard.
Without this distinction, an exploratory model will inevitably appear in a board presentation. The number will be wrong in a way that is hard to explain. The person explaining it will blame the data platform. The person who built the exploratory model will have left the company.
Decision 7: When to split into multiple dbt projects
The most common premature optimisation in data platform design is splitting a dbt project before there is a good reason to do so. Multiple projects add meaningful overhead: separate CI pipelines, cross-project ref management, coordinated deployments, duplicated packages and macros.
The right trigger is not model count. It is ownership. Two domains need separate projects when they have different teams who need to release independently, who do not want to coordinate deployments, and who have sufficiently different schemas that cross-domain refs would be an exception rather than a norm.
A practical signal: if your team has never had a deployment conflict between two domains working in the same project, you do not need multiple projects yet. The pain that justifies splitting is real and specific — it arrives when two teams are regularly blocked waiting for each other's releases.
The intermediate step before splitting is dbt model groups and access policies, available since dbt Core 1.5. These let you enforce ownership and access boundaries within a single project, capturing most of the governance benefit without the operational overhead of separate deployments — splitting a project before you need to is the architectural equivalent of building a fence between roommates who get along fine. It's just paperwork nobody asked for.
The decision that underlies all of them
These seven choices look like separate decisions. They are actually one: the decision to treat the analytics layer as a product with an interface contract, not as a collection of queries that happen to live in the same repository.
A product has documented behaviour. It has owners. It has a distinction between stable interfaces and internal implementation details. It has a process for changing definitions. The dbt trust problem — multiple models for the same concept, conflicting numbers, dashboards nobody believes — is what happens when analytics is treated as a service request queue instead.
None of these decisions are technically difficult. The hard part is making them explicitly, writing them down, and enforcing them consistently as the organisation and the model count grow. That is the work that separates a data platform from a data warehouse.
Seven decisions
- Prioritise sources by business disagreement — start where the pain is loudest, not where the data is most interesting.
- Write the layer contract before the first model — staging, intermediate, mart: what each may and may not contain, in the README.
- Establish a materialisation policy, not a habit — views for staging, tables for marts, incremental only when the logic is stable.
- Force the metric ownership conversation — one definition, recorded in schema.yml with the date it was agreed.
- Document adjacent to code, not in a wiki — schema.yml descriptions stay current; Confluence does not.
- Make certified vs exploratory visible structurally — folder separation and access policies, not shared understanding.
- Split dbt projects on ownership, not model count — the trigger is deployment conflict between teams, not a number of models.