Why Code-First?

If you've used Power BI Desktop, you know the workflow: open the app, click visuals, drag fields, format in the pane. It works. So why does TAMU's AggieViz system generate reports from code instead?

Key Insight

Click-and-drag doesn't scale to 20 reports with 1,149 visuals that need to look identical

The Problem at Scale

One report with 5 visuals? Desktop is perfect. Twenty reports with 48 pages and 1,149 visuals that all need to:

Use the same exact maroon (#500000) header bar at y=0, width=1280, height=50
Place a gold accent line at y=50, height=3, color=#A08035
Position navigation pills at x=400 with 108px spacing
Apply the same theme-responsive colors that switch between light and dark mode
Maintain pixel-perfect alignment across every page

Doing this by hand means clicking through 1,149 formatting panes. Missing one visual means one page looks different. Updating the brand color means touching every report, every page, every visual.

What Code-First Gives You

Benefit	Manual (Desktop)	Code-First (PBIR/TMDL)
Consistency	Human-dependent	Guaranteed by template
Brand update	Touch every visual	Change one variable, regenerate
Audit trail	"Who changed this?" → unknown	Git blame → exact commit
Review	Compare .pbix files (impossible)	PR diff on JSON text
Rollback	"Undo" in Desktop (limited)	`git revert` to any point
Automation	One report at a time	Script generates 20 reports in minutes
Collaboration	Last-save-wins	Git merge + PR review

When Desktop Is Still Right

Code-first doesn't replace Desktop — it replaces the production pipeline:

Task	Use Desktop	Use Code-First
Exploring data, prototyping visuals	Yes	No
One-off ad hoc analysis	Yes	No
Designing a new page layout	Yes	No
Producing 20 standardized reports	No	Yes
Updating brand colors across all reports	No	Yes
Deploying to staging → production	No	Yes
Reviewing changes before publishing	No	Yes (PR review)

The workflow: Prototype in Desktop → codify the pattern → generate production reports from code → deploy via CI/CD.

What "Code-First" Actually Looks Like

You're editing JSON files in VS Code instead of clicking in the formatting pane:

Visual Editor (Desktop):

Open formatting pane → Background → Color → #500000 → Border → On → Width → 1 → Radius → 8 → ...

Code-First (PBIR JSON):

{
  "visual": {
    "visualContainerObjects": {
      "background": [{
        "properties": {
          "color": { "solid": { "color": "#500000" } }
        }
      }],
      "border": [{
        "properties": {
          "show": { "expr": { "Literal": { "Value": "true" } } },
          "width": { "expr": { "Literal": { "Value": "1D" } } },
          "radius": { "expr": { "Literal": { "Value": "8L" } } }
        }
      }]
    }
  }
}

The JSON is more verbose — but it's diffable, reviewable, and scriptable. When you need to change that #500000 to #4A0000, you change it in one place and regenerate.

The AggieViz Pipeline

Template (JSON patterns)
    │
    ├── Shell (header, footer, nav pills, theme slicer)
    ├── Visual defaults (fonts, colors, spacing)
    └── Page templates (KPI page, table page, trend page)
    │
    └── Generator script
            │
            ├── Report 1 (20 pages, 57 visuals)
            ├── Report 2 (20 pages, 57 visuals)
            ├── ...
            └── Report 20 (20 pages, 57 visuals)
                    │
                    └── Git commit → CI validation → Deploy to Fabric

See the AggieViz documentation for the full system.

Getting Started with Code-First

Start at Level 1 — build reports in Desktop first. Understand visuals, DAX, and data modeling.
At Level 3, learn Git Sync — see how Desktop work serializes to TMDL/PBIR.
Start reading PBIR files — open the Git-synced JSON and find your visuals.
Make small edits in VS Code — change a color, commit, see the result in the workspace.
At Level 4, study the Shell Visual System and PBIP Property Reference for full automation.