Chapter 3 of 8

How AtelierBID works — the end-to-end flow

The end-to-end flow: what you hand in and what lands, phase by phase.

One sentence: you describe what you want, and AtelierBID walks you from raw intent to a real, openable Power BI project — model → DAX → report → AI-readiness — emitting only file-first artefacts (PBIP / TMDL / PBIR / theme.json) that open directly in Power BI Desktop, offline, no backend, no per-call cost.

This document is the flow: what happens, in what order, what you hand in, and what you get back at each step. For plugin structure and data-flow diagrams, see Architecture.

The whole flow at a glance#

flowchart TB
    subgraph X["Cross-cutting spine — always on"]
        GC[Schema-grounding contract<br/>binds generation to real data]
        BP[Best-practice rule library<br/>every skill cites it]
        LC[Hybrid lifecycle + conformance harness<br/>offline floor · optional live · drift guard]
    end

    A["A · Start a project<br/>(New Project + PBIP scaffold)"] --> B["B · Discovery<br/>questions, KPIs, grain"]
    B --> Bq["B · Source query text<br/>SQL + Power Query/M"]
    Bq --> C["C · Model<br/>star schema → relationships → settings → partitions → optimise"]
    C --> D["D · Calculation<br/>DAX → time-intelligence → optimise → validate"]
    D --> E["E · Design & report<br/>tokens → theme → background → layout → mockup → PBIR"]
    E --> F["F · AI<br/>AI-readiness → Fabric data-agent runbook"]
    F --> G["G · Documentation<br/>regenerable data dictionary"]

    X -. grounds / guards / cites .-> A
    X -. grounds / guards / cites .-> C
    X -. grounds / guards / cites .-> D
    X -. grounds / guards / cites .-> E

    A -.->|writes| PBIP[(The PBIP project<br/>grows at every step)]
    C -.->|TMDL| PBIP
    D -.->|measures| PBIP
    E -.->|PBIR + theme.json| PBIP
    F -.->|metadata| PBIP
    G -.->|data dictionary| PBIP

Diagram — shown as source if the renderer is unavailable.

The phases are standalone (run any one on its own) and composable (chain them into one end-to-end build).

Every phase has a conversational entry point. Phase C is served by model-star-schema; phase D by author-dax and optimise-dax; phase E by design-report, build-theme, generate-background and prototype-report; phase F by update-metadata; phase G by document-model. Phases A and B are driven by their CLIs directly.

The cross-cutting spine — what's true at every step#

Before and beneath every phase, three things are always in play:

Spine element	What it does	Why it matters
Schema-grounding contract	A single authoritative schema-of-record. Generation binds to real columns/tables; anything off-schema is surfaced as a proposed addition, never silently invented.	You can trust that a generated measure references a column that actually exists.
Best-practice rule library	A per-project `_00-Best-Practice/` rule set (also emitted as BPA JSON) that the model, DAX, and settings skills cite by stable id.	Consistent, project-tuned guidance instead of ad-hoc opinions.
Hybrid lifecycle + conformance harness	An offline floor (default, zero auth/network) with optional Tier-1 live read/validate, a "bind live data?" gate, and a drift guard over canonical PBIR/TMDL fidelity. Publish/refresh stay manual.	You work offline by default, opt into live validation when useful, and never get silent format drift.

Step by step — what you hand in, what lands#

Phase	You provide	The plugin produces	Artefact written
A · Start a project	a report name	a project folder + conventions `CLAUDE.md`, seeded best-practice library, `_00-Artifacts/`, and an openable PBIP shell	project tree · `*.pbip`
B · Discovery	the questions/KPIs you must answer	a structured requirements spec (grain, dimensions, measures) with gaps flagged	requirements spec
B · Source text	source/connection intent	reviewable, dialect-aware SQL and folding-aware Power Query/M — text only, never executed	SQL / M into partition sources
C · Model	a description of your data	a valid star-schema TMDL model: fact/dim tables, safe relationships, deliberate settings, partitions, incremental-refresh definitions, a ranked optimisation pass	`*.SemanticModel` TMDL
D · Calculation	the metrics you need	correct, idiomatic DAX measures + a consistent time-intelligence family, ranked optimisations, and EVALUATE validation queries	measures in TMDL
E · Design & report	a brand palette + a layout brief	a unified token set → accessible theme.json → zoned background → a report mockup IR that converts into valid PBIR (and a shareable interactive prototype)	`theme.json` · PBIR report
F · AI	(uses the finished model)	metadata enrichment so Copilot/Q&A answer reliably, plus a Fabric data-agent config + provisioning runbook (offline, no live calls)	descriptions/synonyms in TMDL · runbook
G · Documentation	(uses the finished model)	a deterministic, regenerable data dictionary straight from the TMDL, with gaps flagged	data-dictionary markdown

The mockup → PBIR continuity (Phase E) is the part that removes the usual re-authoring gap: an HTML mockup you approve carries its structure straight into the real PBIR report.

How the project grows (the artefact accretes)#

flowchart LR
    P0["Empty PBIP shell<br/>(Phase A)"] --> P1["+ TMDL model<br/>(Phase C)"]
    P1 --> P2["+ DAX measures<br/>(Phase D)"]
    P2 --> P3["+ theme.json + PBIR report<br/>(Phase E)"]
    P3 --> P4["+ AI-ready metadata<br/>(Phase F)"]
    P4 --> P5["Openable, documented<br/>Power BI project"]

Diagram — shown as source if the renderer is unavailable.

One PBIP container is written into at every step — never a dead-end preview. At any point it opens in Power BI Desktop.

The offline-first lifecycle (in motion)#

stateDiagram-v2
    [*] --> Offline
    Offline --> Offline: generate / validate (file-first, zero network)
    Offline --> Tier1: user opts in — "bind live data?"
    Tier1 --> Offline: read live schema · validate · then drop back
    Tier1 --> Manual: publish / refresh
    Manual --> [*]: runs in the Power BI Service — instructions only, never via API

Diagram — shown as source if the renderer is unavailable.

Offline is the default and the floor. Live read/validate is opt-in. Publish and refresh are always a deliberate manual step (ADR-0002).

The principles that hold the whole flow together#

File-first — every step reads/writes Power BI Project text (PBIP/TMDL/PBIR/theme.json); no binary .pbix authoring.
Grounded, never invented — generation binds to the schema contract; off-schema = a proposal, not a fabrication.
Offline floor, optional connectivity — usable with zero auth/network/cost; live is opt-in; publish stays manual.
Broad-audience guardrails — safe defaults, plain-English "what & why", warn-don't-fail-silently.
Standalone + composable — each phase is its own skill and slots into one end-to-end run, reusing shared conventions (data/design-system.json, scripts/lib/, the best-practice library).

For the full plugin structure, the deterministic-vs-AI split, and the data-flow diagrams, see Architecture. For every script's flag reference, see Features.