@luquimbo/bi-superpowers 1.0.0

package/library/templates/data-models/finance-model.md

@@ -0,0 +1,627 @@
+# Finance Data Model
+
+## Overview
+
+A comprehensive semantic model for financial reporting, budgeting, and analysis. Designed to support P&L statements, balance sheets, cash flow analysis, and budget variance tracking with proper account hierarchy handling.
+
+---
+
+## Business Context
+
+### Key Business Questions
+
+1. **Profit & Loss**
+   - What is revenue, COGS, and net income by period?
+   - How do expenses trend over time?
+   - What is the margin by product line or department?
+
+2. **Budget Analysis**
+   - How do actuals compare to budget?
+   - What are the key variance drivers?
+   - What is the forecast for year-end?
+
+3. **Balance Sheet**
+   - What are current assets and liabilities?
+   - How has working capital changed?
+   - What is the debt-to-equity ratio?
+
+4. **Cash Flow**
+   - What is cash from operations?
+   - How much was invested in CapEx?
+   - What is the cash runway?
+
+---
+
+## Schema Diagram
+
+```
+                    ┌─────────────┐
+                    │  DimDate    │
+                    │─────────────│
+                    │ DateKey (PK)│
+                    │ Date        │
+                    │ FiscalYear  │
+                    │ FiscalPeriod│
+                    │ IsActual    │
+                    └──────┬──────┘
+                           │
+                           │ 1:M
+                           │
+┌─────────────┐     ┌──────┴──────┐     ┌─────────────┐
+│ DimAccount  │     │   FactGL    │     │DimScenario  │
+│─────────────│     │─────────────│     │─────────────│
+│AccountKey PK│────>│ GLKey (PK)  │<────│ScenarioKey  │
+│ AccountID   │ M:1 │ DateKey (FK)│ 1:M │ ScenarioID  │
+│ AccountName │     │AccountKey FK│     │ScenarioName │
+│ AccountType │     │ScenarioKey  │     │ ScenarioType│
+│ AccountGroup│     │CostCenterKey│     └─────────────┘
+│ ParentAcct  │     │ EntityKey FK│
+│ L1-L5 Hier  │     │ Debit       │     ┌─────────────┐
+│ IsPL/IsBS   │     │ Credit      │     │DimCostCenter│
+│ SignConv    │     │ Amount      │     │─────────────│
+└─────────────┘     └──────┬──────┘     │CostCenterKey│
+                           │            │CostCenterID │
+          ┌────────────────┘            │ Name        │
+          │                             │ Department  │
+          │ M:1                         │ Division    │
+          ▼                             │ Manager     │
+┌─────────────┐                         └─────────────┘
+│ DimEntity   │
+│─────────────│     ┌─────────────┐
+│EntityKey PK │     │  FactBudget │
+│ EntityID    │     │─────────────│
+│ EntityName  │     │ BudgetKey   │
+│ Currency    │     │ DateKey     │
+│ ParentEntity│     │ AccountKey  │
+│ IsElim      │     │CostCenterKey│
+└─────────────┘     │ ScenarioKey │
+                    │ Amount      │
+                    └─────────────┘
+```
+
+---
+
+## Dimension Tables
+
+### DimDate (Financial Calendar)
+
+**Purpose:** Fiscal calendar with period close tracking
+
+| Column | Data Type | Description | Sample Values |
+|--------|-----------|-------------|---------------|
+| DateKey | INT | Surrogate key (YYYYMMDD) | 20240115 |
+| Date | DATE | Full date | 2024-01-15 |
+| CalendarYear | INT | Calendar year | 2024 |
+| CalendarMonth | INT | Calendar month | 1 |
+| CalendarQuarter | INT | Calendar quarter | 1 |
+| FiscalYear | INT | Fiscal year | 2024 |
+| FiscalPeriod | INT | Fiscal period (1-12 or 1-13) | 7 |
+| FiscalQuarter | INT | Fiscal quarter | 3 |
+| FiscalYearMonth | VARCHAR(10) | FY-Period label | FY24-P07 |
+| PeriodStartDate | DATE | First day of period | 2024-01-01 |
+| PeriodEndDate | DATE | Last day of period | 2024-01-31 |
+| IsActualPeriod | BIT | Has actual data | 1 |
+| IsClosed | BIT | Period is closed | 1 |
+| DaysInPeriod | INT | Days in fiscal period | 31 |
+| IsYearEnd | BIT | Year-end period | 0 |
+
+### DimAccount (Chart of Accounts)
+
+**Purpose:** Account hierarchy with financial statement mapping
+
+| Column | Data Type | Description | Sample Values |
+|--------|-----------|-------------|---------------|
+| AccountKey | INT | Surrogate key | 1001 |
+| AccountID | VARCHAR(20) | GL account number | 4010 |
+| AccountName | VARCHAR(100) | Account name | Product Revenue |
+| AccountDescription | VARCHAR(500) | Full description | Revenue from product sales |
+| AccountType | VARCHAR(30) | High-level type | Revenue |
+| AccountGroup | VARCHAR(50) | Grouping | Operating Revenue |
+| AccountClass | VARCHAR(30) | Class | Income Statement |
+| StatementLine | VARCHAR(50) | Financial statement line | Net Revenue |
+| L1_Category | VARCHAR(50) | Hierarchy Level 1 | Income Statement |
+| L2_Category | VARCHAR(50) | Hierarchy Level 2 | Revenue |
+| L3_Category | VARCHAR(50) | Hierarchy Level 3 | Operating Revenue |
+| L4_Category | VARCHAR(50) | Hierarchy Level 4 | Product Revenue |
+| L5_Account | VARCHAR(100) | Hierarchy Level 5 (Detail) | Product Revenue - Domestic |
+| ParentAccountKey | INT | Parent in hierarchy | 1000 |
+| IsBS | BIT | Balance Sheet account | 0 |
+| IsPL | BIT | P&L account | 1 |
+| IsCF | BIT | Cash Flow relevant | 0 |
+| NormalBalance | VARCHAR(10) | Debit or Credit | Credit |
+| SignConvention | INT | Sign for reporting (+1/-1) | -1 |
+| SortOrder | INT | Display order | 100 |
+| IsActive | BIT | Active account | 1 |
+| IsPostable | BIT | Can receive postings | 1 |
+
+**Account Types:**
+```
+Balance Sheet (IsBS = 1):
+  - Asset
+  - Liability
+  - Equity
+
+Income Statement (IsPL = 1):
+  - Revenue
+  - COGS
+  - Operating Expense
+  - Other Income/Expense
+  - Tax
+```
+
+**Sign Convention:**
+```
+Revenue accounts: SignConvention = -1
+  (Credit balance shows as positive)
+
+Expense accounts: SignConvention = 1
+  (Debit balance shows as positive)
+
+Asset accounts: SignConvention = 1
+  (Debit balance shows as positive)
+
+Liability/Equity: SignConvention = -1
+  (Credit balance shows as positive)
+```
+
+### DimScenario (Scenario Dimension)
+
+**Purpose:** Actual, Budget, Forecast versions
+
+| Column | Data Type | Description | Sample Values |
+|--------|-----------|-------------|---------------|
+| ScenarioKey | INT | Surrogate key | 1 |
+| ScenarioID | VARCHAR(20) | Scenario code | ACT |
+| ScenarioName | VARCHAR(50) | Display name | Actual |
+| ScenarioType | VARCHAR(30) | Type classification | Actual |
+| IsActual | BIT | Actual data flag | 1 |
+| IsBudget | BIT | Budget version flag | 0 |
+| IsForecast | BIT | Forecast version flag | 0 |
+| FiscalYear | INT | Applicable year | 2024 |
+| Version | VARCHAR(20) | Version number | v1.0 |
+| ApprovedDate | DATE | Approval date | 2023-12-15 |
+| IsActive | BIT | Current/active | 1 |
+
+**Common Scenarios:**
+```
+1. Actual (ACT) - Recorded transactions
+2. Budget (BUD) - Annual approved budget
+3. Forecast (FC1, FC2, FC3) - Quarterly reforecasts
+4. Prior Year (PY) - Last year actuals
+5. Plan (PLN) - Long-term plan
+```
+
+### DimCostCenter (Cost Center Dimension)
+
+**Purpose:** Organizational hierarchy for expenses
+
+| Column | Data Type | Description | Sample Values |
+|--------|-----------|-------------|---------------|
+| CostCenterKey | INT | Surrogate key | 501 |
+| CostCenterID | VARCHAR(20) | Cost center code | CC-100 |
+| CostCenterName | VARCHAR(100) | Name | Engineering |
+| Department | VARCHAR(50) | Department | Technology |
+| Division | VARCHAR(50) | Division | Product |
+| BusinessUnit | VARCHAR(50) | Business unit | Software |
+| ManagerName | VARCHAR(100) | Responsible manager | John Smith |
+| ManagerEmail | VARCHAR(100) | Manager email | john.smith@company.com |
+| ParentCostCenterKey | INT | Parent in hierarchy | 500 |
+| L1_Division | VARCHAR(50) | Hierarchy Level 1 | Product |
+| L2_Department | VARCHAR(50) | Hierarchy Level 2 | Technology |
+| L3_CostCenter | VARCHAR(50) | Hierarchy Level 3 | Engineering |
+| IsActive | BIT | Active cost center | 1 |
+
+### DimEntity (Legal Entity Dimension)
+
+**Purpose:** Multi-company consolidation
+
+| Column | Data Type | Description | Sample Values |
+|--------|-----------|-------------|---------------|
+| EntityKey | INT | Surrogate key | 1 |
+| EntityID | VARCHAR(20) | Entity code | US01 |
+| EntityName | VARCHAR(100) | Legal name | Company USA Inc. |
+| ShortName | VARCHAR(50) | Short name | USA |
+| Currency | VARCHAR(3) | Local currency | USD |
+| Country | VARCHAR(50) | Country | United States |
+| Region | VARCHAR(30) | Region | Americas |
+| EntityType | VARCHAR(30) | Type | Operating |
+| ParentEntityKey | INT | Parent entity | NULL |
+| ConsolidationPct | DECIMAL(5,2) | Ownership % | 100.00 |
+| IsElimination | BIT | Elimination entity | 0 |
+| IsConsolidated | BIT | Include in consolidation | 1 |
+| IsActive | BIT | Active entity | 1 |
+
+---
+
+## Fact Tables
+
+### FactGL (General Ledger)
+
+**Purpose:** Journal entry level detail
+
+| Column | Data Type | Description | Grain |
+|--------|-----------|-------------|-------|
+| GLKey | BIGINT | Surrogate key | One row per journal line |
+| DateKey | INT | Transaction date (FK) | |
+| AccountKey | INT | GL Account (FK) | |
+| ScenarioKey | INT | Scenario (FK) | |
+| CostCenterKey | INT | Cost Center (FK) | |
+| EntityKey | INT | Legal Entity (FK) | |
+| JournalID | VARCHAR(30) | Journal entry ID | |
+| LineNumber | INT | Line in journal | |
+| Debit | DECIMAL(18,2) | Debit amount | |
+| Credit | DECIMAL(18,2) | Credit amount | |
+| Amount | DECIMAL(18,2) | Net amount (Debit - Credit) | |
+| LocalAmount | DECIMAL(18,2) | Amount in local currency | |
+| FXRate | DECIMAL(12,6) | Exchange rate | |
+| Description | VARCHAR(500) | Transaction description | |
+| Reference | VARCHAR(50) | External reference | |
+| PostedBy | VARCHAR(50) | User who posted | |
+| PostedDate | DATETIME | Posting timestamp | |
+
+### FactBudget (Budget/Forecast)
+
+**Purpose:** Budget and forecast data at summary level
+
+| Column | Data Type | Description | Grain |
+|--------|-----------|-------------|-------|
+| BudgetKey | BIGINT | Surrogate key | One row per account/CC/period |
+| DateKey | INT | Period start date (FK) | |
+| AccountKey | INT | GL Account (FK) | |
+| ScenarioKey | INT | Scenario (FK) | |
+| CostCenterKey | INT | Cost Center (FK) | |
+| EntityKey | INT | Legal Entity (FK) | |
+| Amount | DECIMAL(18,2) | Budget amount | |
+| Units | INT | Budget units (optional) | |
+| Notes | VARCHAR(500) | Budget assumptions | |
+| VersionDate | DATE | Version date | |
+
+### FactBalance (Balance Sheet Snapshots - Optional)
+
+**Purpose:** Period-end balances for BS accounts
+
+| Column | Data Type | Description | Grain |
+|--------|-----------|-------------|-------|
+| BalanceKey | BIGINT | Surrogate key | One row per account/entity/period |
+| DateKey | INT | Period end date (FK) | |
+| AccountKey | INT | GL Account (FK) | |
+| EntityKey | INT | Legal Entity (FK) | |
+| ScenarioKey | INT | Scenario (FK) | |
+| BeginningBalance | DECIMAL(18,2) | Opening balance | |
+| Activity | DECIMAL(18,2) | Period activity | |
+| EndingBalance | DECIMAL(18,2) | Closing balance | |
+
+---
+
+## Recommended DAX Measures
+
+### Core Financial Measures
+
+```dax
+// Amount with Sign Convention
+Amount =
+SUMX(
+    FactGL,
+    FactGL[Amount] * RELATED(DimAccount[SignConvention])
+)
+
+// Or simpler if Amount already signed correctly
+Total Amount =
+SUM(FactGL[Amount])
+
+// Revenue
+Revenue =
+CALCULATE(
+    [Amount],
+    DimAccount[AccountType] = "Revenue"
+)
+
+// COGS
+COGS =
+CALCULATE(
+    [Amount],
+    DimAccount[AccountType] = "COGS"
+)
+
+// Gross Profit
+Gross Profit =
+[Revenue] - [COGS]
+
+// Gross Margin %
+Gross Margin % =
+DIVIDE([Gross Profit], [Revenue])
+
+// Operating Expenses
+Operating Expenses =
+CALCULATE(
+    [Amount],
+    DimAccount[AccountType] = "Operating Expense"
+)
+
+// EBITDA
+EBITDA =
+[Gross Profit] - [Operating Expenses] + [Depreciation & Amortization]
+
+// Net Income
+Net Income =
+CALCULATE(
+    [Amount],
+    DimAccount[IsPL] = TRUE
+)
+```
+
+### Budget Variance
+
+```dax
+// Budget Amount
+Budget Amount =
+CALCULATE(
+    [Amount],
+    DimScenario[ScenarioName] = "Budget"
+)
+
+// Actual Amount
+Actual Amount =
+CALCULATE(
+    [Amount],
+    DimScenario[ScenarioName] = "Actual"
+)
+
+// Variance
+Variance $ =
+[Actual Amount] - [Budget Amount]
+
+// Variance % (context-aware)
+Variance % =
+VAR _Actual = [Actual Amount]
+VAR _Budget = [Budget Amount]
+VAR _AccountType = SELECTEDVALUE(DimAccount[AccountType])
+VAR _IsExpense = _AccountType IN {"COGS", "Operating Expense", "Other Expense"}
+RETURN
+IF(
+    _IsExpense,
+    DIVIDE(_Budget - _Actual, ABS(_Budget)),  // Under budget is positive
+    DIVIDE(_Actual - _Budget, ABS(_Budget))   // Over revenue is positive
+)
+
+// Variance Status
+Variance Status =
+VAR _Var = [Variance %]
+RETURN
+SWITCH(
+    TRUE(),
+    _Var >= 0, "Favorable",
+    _Var >= -0.05, "On Track",
+    _Var >= -0.10, "At Risk",
+    "Unfavorable"
+)
+```
+
+### Period Intelligence
+
+```dax
+// YTD Amount
+YTD Amount =
+TOTALYTD(
+    [Amount],
+    DimDate[Date],
+    "6/30"  // Fiscal year end if not Dec 31
+)
+
+// Prior Year
+Prior Year =
+CALCULATE(
+    [Amount],
+    SAMEPERIODLASTYEAR(DimDate[Date])
+)
+
+// YoY Change
+YoY Change =
+[Amount] - [Prior Year]
+
+// YoY %
+YoY % =
+DIVIDE([YoY Change], ABS([Prior Year]))
+
+// MTD
+MTD Amount =
+TOTALMTD([Amount], DimDate[Date])
+
+// Full Year Run Rate
+Full Year Run Rate =
+VAR _YTD = [YTD Amount]
+VAR _MonthsElapsed = DISTINCTCOUNT(DimDate[FiscalPeriod])
+RETURN
+DIVIDE(_YTD * 12, _MonthsElapsed)
+```
+
+### Balance Sheet Measures
+
+```dax
+// Ending Balance (cumulative for BS)
+Ending Balance =
+CALCULATE(
+    [Amount],
+    FILTER(
+        ALL(DimDate),
+        DimDate[Date] <= MAX(DimDate[Date])
+    ),
+    DimAccount[IsBS] = TRUE
+)
+
+// Current Assets
+Current Assets =
+CALCULATE(
+    [Ending Balance],
+    DimAccount[AccountGroup] = "Current Assets"
+)
+
+// Current Liabilities
+Current Liabilities =
+CALCULATE(
+    [Ending Balance],
+    DimAccount[AccountGroup] = "Current Liabilities"
+)
+
+// Working Capital
+Working Capital =
+[Current Assets] + [Current Liabilities]  // Liabilities are negative
+
+// Current Ratio
+Current Ratio =
+DIVIDE([Current Assets], ABS([Current Liabilities]))
+```
+
+### Financial Ratios
+
+```dax
+// Operating Margin
+Operating Margin =
+DIVIDE([EBITDA], [Revenue])
+
+// Return on Assets
+ROA =
+DIVIDE(
+    [Net Income],
+    CALCULATE([Ending Balance], DimAccount[AccountType] = "Asset")
+)
+
+// Debt to Equity
+Debt to Equity =
+DIVIDE(
+    CALCULATE([Ending Balance], DimAccount[AccountType] = "Liability"),
+    CALCULATE([Ending Balance], DimAccount[AccountType] = "Equity")
+)
+```
+
+---
+
+## P&L Structure
+
+### Standard P&L Order
+
+```
+Revenue
+  Product Revenue
+  Service Revenue
+  Other Revenue
+─────────────────────
+Total Revenue
+
+Cost of Goods Sold
+  Direct Materials
+  Direct Labor
+  Manufacturing Overhead
+─────────────────────
+Total COGS
+
+GROSS PROFIT
+
+Operating Expenses
+  Sales & Marketing
+    Salaries - Sales
+    Advertising
+    Travel - Sales
+  Research & Development
+    Salaries - R&D
+    Software & Tools
+  General & Administrative
+    Executive Salaries
+    Legal & Professional
+    Rent & Facilities
+    Insurance
+    Depreciation
+─────────────────────
+Total Operating Expenses
+
+OPERATING INCOME (EBIT)
+
+Other Income/Expense
+  Interest Income
+  Interest Expense
+  FX Gains/Losses
+  Other
+─────────────────────
+Total Other
+
+INCOME BEFORE TAX
+
+Income Tax Expense
+─────────────────────
+NET INCOME
+```
+
+### DAX for P&L Matrix
+
+```dax
+// Sort Order for P&L display
+P&L Sort =
+SELECTEDVALUE(DimAccount[SortOrder])
+
+// P&L Amount with proper aggregation
+P&L Amount =
+IF(
+    HASONEVALUE(DimAccount[L5_Account]),
+    [Amount],
+    SUMX(
+        SUMMARIZE(DimAccount, DimAccount[L5_Account]),
+        [Amount]
+    )
+)
+```
+
+---
+
+## Security Considerations
+
+### Row-Level Security
+
+```dax
+// Cost Center RLS
+[CostCenterAccess] =
+VAR _UserEmail = USERPRINCIPALNAME()
+VAR _UserCCs =
+    CALCULATETABLE(
+        VALUES(SecurityCostCenter[CostCenterKey]),
+        SecurityCostCenter[UserEmail] = _UserEmail
+    )
+RETURN
+DimCostCenter[CostCenterKey] IN _UserCCs
+
+// Entity RLS
+[EntityAccess] =
+VAR _UserEmail = USERPRINCIPALNAME()
+VAR _UserEntities =
+    CALCULATETABLE(
+        VALUES(SecurityEntity[EntityKey]),
+        SecurityEntity[UserEmail] = _UserEmail
+    )
+RETURN
+DimEntity[EntityKey] IN _UserEntities
+```
+
+---
+
+## Implementation Checklist
+
+- [ ] Define fiscal calendar (year-end, periods)
+- [ ] Map Chart of Accounts with hierarchy levels
+- [ ] Set sign convention for each account type
+- [ ] Create scenario dimension with all versions
+- [ ] Build cost center hierarchy
+- [ ] Configure entity structure for consolidation
+- [ ] Load historical GL data
+- [ ] Import budget versions
+- [ ] Create core financial measures
+- [ ] Build variance calculations
+- [ ] Configure RLS for cost center/entity access
+- [ ] Test P&L, BS, and variance reports
+- [ ] Document calculation methodology
+
+---
+
+## Related Resources
+
+- [Finance Report Template](../power-bi/finance-report.md)
+- [DAX Patterns](../../snippets/dax/)
+- [Data Modeling Best Practices](../../skills/data-modeling/SKILL.md)