@luquimbo/bi-superpowers 1.0.0

package/library/examples/retail-analytics/README.md

@@ -0,0 +1,439 @@
+# Retail Analytics - Complete Example
+
+A complete, end-to-end example demonstrating BI Agent Superpowers patterns for a retail analytics solution.
+
+---
+
+## Overview
+
+This example shows how to build a professional retail analytics solution using:
+
+- **Star schema data model** with fact and dimension tables
+- **DAX measures** for KPIs, time intelligence, and rankings
+- **Power Query** patterns for data transformation
+- **Power BI theme** for consistent styling
+
+---
+
+## Business Requirements
+
+### Stakeholders
+- Store managers: Daily sales performance
+- Regional directors: Cross-store comparisons
+- Finance team: Revenue and margin analysis
+- Operations: Inventory and category insights
+
+### Key Questions
+1. What are our sales trends over time?
+2. Which products and categories drive revenue?
+3. How do stores compare in performance?
+4. What's our margin by product category?
+5. Who are our top customers?
+
+---
+
+## Data Model
+
+### Star Schema Design
+
+```
+                    ┌─────────────────┐
+                    │   DimDate       │
+                    │─────────────────│
+                    │ DateKey (PK)    │
+                    │ Date            │
+                    │ Year            │
+                    │ Quarter         │
+                    │ Month           │
+                    │ MonthName       │
+                    │ Week            │
+                    │ DayOfWeek       │
+                    │ IsWeekend       │
+                    └────────┬────────┘
+                             │
+┌─────────────────┐          │          ┌─────────────────┐
+│   DimProduct    │          │          │   DimCustomer   │
+│─────────────────│          │          │─────────────────│
+│ ProductKey (PK) │          │          │ CustomerKey (PK)│
+│ ProductID       │          │          │ CustomerID      │
+│ ProductName     │          │          │ CustomerName    │
+│ Category        │          │          │ Email           │
+│ SubCategory     │          │          │ City            │
+│ Brand           │          │          │ State           │
+│ UnitCost        │          │          │ Region          │
+│ UnitPrice       │          │          │ JoinDate        │
+│ IsActive        │          │          │ Tier            │
+└────────┬────────┘          │          └────────┬────────┘
+         │                   │                   │
+         │     ┌─────────────┴───────────────┐   │
+         │     │        FactSales            │   │
+         │     │─────────────────────────────│   │
+         └────>│ SalesKey (PK)               │<──┘
+               │ DateKey (FK)                │
+               │ ProductKey (FK)             │
+               │ CustomerKey (FK)            │
+               │ StoreKey (FK)               │
+               │ Quantity                    │
+               │ UnitPrice                   │
+               │ Discount                    │
+               │ Amount                      │
+               │ Cost                        │
+               └─────────────┬───────────────┘
+                             │
+                    ┌────────┴────────┐
+                    │   DimStore      │
+                    │─────────────────│
+                    │ StoreKey (PK)   │
+                    │ StoreID         │
+                    │ StoreName       │
+                    │ StoreType       │
+                    │ City            │
+                    │ State           │
+                    │ Region          │
+                    │ OpenDate        │
+                    │ SquareFeet      │
+                    └─────────────────┘
+```
+
+### Table Details
+
+See [data-model.md](./data-model.md) for complete column definitions and data types.
+
+---
+
+## Power Query Transformations
+
+### Source Data Preparation
+
+```m
+// FactSales transformation
+let
+    Source = Sql.Database("server", "RetailDB"),
+    Sales = Source{[Schema="dbo", Item="SalesTransactions"]}[Data],
+
+    // 1. Filter to current fiscal year (folds to WHERE)
+    FilteredByDate = Table.SelectRows(Sales, each
+        [TransactionDate] >= #date(2024, 1, 1)
+    ),
+
+    // 2. Select only needed columns (folds to SELECT)
+    SelectedColumns = Table.SelectColumns(FilteredByDate, {
+        "TransactionID", "TransactionDate", "ProductID",
+        "CustomerID", "StoreID", "Quantity", "UnitPrice",
+        "DiscountAmount"
+    }),
+
+    // 3. Add calculated columns
+    WithCalculations = Table.AddColumn(
+        Table.AddColumn(
+            Table.AddColumn(SelectedColumns, "Amount",
+                each [Quantity] * [UnitPrice] - [DiscountAmount], Currency.Type
+            ),
+            "DateKey", each Date.ToText([TransactionDate], "yyyyMMdd"), type text
+        ),
+        "SalesKey", each Text.From([TransactionID]), type text
+    ),
+
+    // 4. Set final types
+    TypedTable = Table.TransformColumnTypes(WithCalculations, {
+        {"Quantity", Int64.Type},
+        {"UnitPrice", Currency.Type},
+        {"DiscountAmount", Currency.Type}
+    })
+in
+    TypedTable
+```
+
+See [power-query.md](./power-query.md) for all table transformations.
+
+---
+
+## DAX Measures
+
+### Base Measures
+
+```dax
+// Revenue
+Revenue =
+SUM(FactSales[Amount])
+
+// Cost
+Cost =
+SUMX(
+    FactSales,
+    FactSales[Quantity] * RELATED(DimProduct[UnitCost])
+)
+
+// Profit
+Profit =
+[Revenue] - [Cost]
+
+// Profit Margin
+Profit Margin % =
+DIVIDE([Profit], [Revenue])
+
+// Transaction Count
+Transactions =
+COUNTROWS(FactSales)
+
+// Average Order Value
+AOV =
+DIVIDE([Revenue], [Transactions])
+```
+
+### Time Intelligence
+
+```dax
+// Revenue YTD
+Revenue YTD =
+TOTALYTD([Revenue], DimDate[Date])
+
+// Revenue Prior Year
+Revenue PY =
+CALCULATE([Revenue], SAMEPERIODLASTYEAR(DimDate[Date]))
+
+// Revenue YoY Growth %
+Revenue YoY % =
+VAR _Current = [Revenue]
+VAR _PY = [Revenue PY]
+RETURN
+    DIVIDE(_Current - _PY, _PY)
+
+// Revenue Rolling 3 Months
+Revenue R3M =
+CALCULATE(
+    [Revenue],
+    DATESINPERIOD(DimDate[Date], MAX(DimDate[Date]), -3, MONTH)
+)
+```
+
+### Rankings
+
+```dax
+// Product Rank by Revenue
+Product Rank =
+IF(
+    HASONEVALUE(DimProduct[ProductName]),
+    RANKX(
+        ALL(DimProduct[ProductName]),
+        [Revenue],
+        ,
+        DESC,
+        DENSE
+    )
+)
+
+// Store Rank by Revenue
+Store Rank =
+IF(
+    HASONEVALUE(DimStore[StoreName]),
+    RANKX(
+        ALL(DimStore[StoreName]),
+        [Revenue],
+        ,
+        DESC,
+        DENSE
+    )
+)
+
+// Top 10 Products Revenue
+Revenue Top 10 Products =
+CALCULATE(
+    [Revenue],
+    TOPN(10, ALL(DimProduct[ProductName]), [Revenue], DESC)
+)
+```
+
+### KPI Formatting
+
+```dax
+// Revenue with conditional color
+Revenue Color =
+VAR _YoY = [Revenue YoY %]
+RETURN
+    SWITCH(
+        TRUE(),
+        _YoY >= 0.1, "#166534",   // Dark green - exceeds
+        _YoY >= 0, "#22C55E",      // Green - positive
+        _YoY >= -0.1, "#EAB308",   // Yellow - slightly down
+        "#991B1B"                   // Dark red - significantly down
+    )
+
+// Trend indicator
+Revenue Trend =
+VAR _YoY = [Revenue YoY %]
+RETURN
+    SWITCH(
+        TRUE(),
+        _YoY >= 0.1, "▲▲",
+        _YoY >= 0, "▲",
+        _YoY >= -0.1, "▼",
+        "▼▼"
+    )
+```
+
+See [measures.dax](./measures.dax) for the complete measure library.
+
+---
+
+## Visualizations
+
+### Dashboard Layout
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  RETAIL ANALYTICS                          [Date Range Slicer]   │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
+│  │  Revenue    │ │   Profit    │ │  Margin %   │ │    AOV      ││
+│  │  $2.4M      │ │   $480K     │ │   20.1%     │ │   $45.20    ││
+│  │   ▲ 12.3%   │ │   ▲ 8.1%    │ │   ▼ 0.3pp   │ │   ▲ 5.2%    ││
+│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
+│                                                                  │
+│  ┌───────────────────────────────┐ ┌───────────────────────────┐│
+│  │   Revenue Trend               │ │   Revenue by Category     ││
+│  │   [Line Chart - R12M]         │ │   [Bar Chart]             ││
+│  │                               │ │                           ││
+│  │                               │ │                           ││
+│  └───────────────────────────────┘ └───────────────────────────┘│
+│                                                                  │
+│  ┌───────────────────────────────┐ ┌───────────────────────────┐│
+│  │   Top 10 Products             │ │   Store Performance       ││
+│  │   [Table with bars]           │ │   [Map or Bar Chart]      ││
+│  │                               │ │                           ││
+│  │                               │ │                           ││
+│  └───────────────────────────────┘ └───────────────────────────┘│
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Recommended Visuals
+
+| Visual | Measures | Purpose |
+|--------|----------|---------|
+| Card | Revenue, Profit, Margin %, AOV | KPI summary |
+| Line chart | Revenue by Month | Trend analysis |
+| Clustered bar | Revenue by Category | Category comparison |
+| Table | Top Products with Revenue, YoY % | Detailed ranking |
+| Map | Revenue by Region/State | Geographic analysis |
+| Slicer | Date, Category, Region | Filtering |
+
+---
+
+## Theme
+
+Use the `bi-superpowers-default.json` theme for this report.
+
+### Key Theme Settings
+
+| Element | Setting |
+|---------|---------|
+| Background | #FAFAFA (page), #FFFFFF (cards) |
+| Primary text | #171717 |
+| Data colors | IBCS grayscale (#000000, #737373, #A3A3A3) |
+| Good | #166534 (dark green) |
+| Bad | #991B1B (dark red) |
+| Border radius | 10px |
+| Font | Segoe UI |
+
+See [theme.json](./theme.json) for the complete theme file.
+
+---
+
+## Implementation Checklist
+
+### Data Model
+- [ ] Create DimDate table with all date attributes
+- [ ] Load DimProduct with Category/SubCategory hierarchy
+- [ ] Load DimCustomer with Region hierarchy
+- [ ] Load DimStore with geographic attributes
+- [ ] Load FactSales with surrogate keys
+- [ ] Create relationships (all 1:*)
+- [ ] Mark DimDate as Date Table
+- [ ] Hide foreign key columns
+
+### Measures
+- [ ] Create base measures (Revenue, Cost, Profit)
+- [ ] Create time intelligence measures (YTD, PY, YoY %)
+- [ ] Create ranking measures
+- [ ] Create conditional formatting measures
+- [ ] Organize measures in folders
+
+### Visualizations
+- [ ] Apply theme
+- [ ] Create KPI cards row
+- [ ] Add trend line chart
+- [ ] Add category comparison
+- [ ] Add Top N table
+- [ ] Add geographic visual
+- [ ] Configure slicers
+- [ ] Add tooltips
+- [ ] Test all interactions
+
+### Polish
+- [ ] Add report title
+- [ ] Add last refresh date
+- [ ] Configure mobile layout
+- [ ] Test filter interactions
+- [ ] Optimize performance (DAX Studio)
+- [ ] Document assumptions
+
+---
+
+## Files in This Example
+
+| File | Description |
+|------|-------------|
+| [README.md](./README.md) | This overview |
+| [data-model.md](./data-model.md) | Complete table definitions |
+| [power-query.md](./power-query.md) | All M code transformations |
+| [measures.dax](./measures.dax) | Complete DAX measure library |
+| [theme.json](./theme.json) | Power BI theme file |
+
+---
+
+## Extending This Example
+
+### Add Customer Segmentation
+
+```dax
+Customer Segment =
+VAR _CustomerRevenue = [Revenue]
+VAR _AvgCustomerRevenue =
+    CALCULATE(
+        AVERAGEX(VALUES(DimCustomer[CustomerKey]), [Revenue]),
+        ALL(DimCustomer)
+    )
+RETURN
+    SWITCH(
+        TRUE(),
+        _CustomerRevenue >= _AvgCustomerRevenue * 2, "VIP",
+        _CustomerRevenue >= _AvgCustomerRevenue, "Regular",
+        "Occasional"
+    )
+```
+
+### Add Inventory Analysis
+
+Create a FactInventory table and add measures like:
+
+```dax
+Stock Days =
+DIVIDE([Current Stock], [Daily Sales Rate])
+
+Reorder Alert =
+IF([Stock Days] < 14, "Reorder", "OK")
+```
+
+### Add Forecast Comparison
+
+If you have budget/forecast data:
+
+```dax
+Revenue vs Budget % =
+DIVIDE([Revenue] - [Budget], [Budget])
+
+Budget Variance =
+[Revenue] - [Budget]
+```