Financial Reporting SSOT

SSOT Key: reporting Core Definition: Financial report generation logic, report types, and calculation rules.

---

1. Source of Truth

Dimension	Physical Location (SSOT)	Description
Report Logic	apps/backend/src/services/reporting.py	Report generation
Report Templates	apps/frontend/src/app/reports/	Report pages and layouts
Visual Components	apps/frontend/src/components/charts/	Chart components

---

2. Report Types

2.1 Balance Sheet (Statement of Financial Position)

Shows assets, liabilities, and equity at a specific point in time.

┌─────────────────────────────────────────────┐
│              BALANCE SHEET                   │
│              As of YYYY-MM-DD                │
├─────────────────────────────────────────────┤
│ ASSETS                                       │
│   Current Assets                             │
│     Cash & Bank              $XX,XXX         │
│     Investments              $XX,XXX         │
│   Non-Current Assets                         │
│     Real Estate              $XX,XXX         │
│   ─────────────────────────────────          │
│   Total Assets               $XXX,XXX        │
├─────────────────────────────────────────────┤
│ LIABILITIES                                  │
│   Current Liabilities                        │
│     Credit Cards             $X,XXX          │
│   Non-Current Liabilities                    │
│     Mortgage                 $XX,XXX         │
│   ─────────────────────────────────          │
│   Total Liabilities          $XX,XXX         │
├─────────────────────────────────────────────┤
│ EQUITY                                       │
│   Net Worth                  $XXX,XXX        │
├─────────────────────────────────────────────┤
│ Total Liab + Equity          $XXX,XXX        │
│ (Must equal Total Assets)                    │
└─────────────────────────────────────────────┘

Validation: Total Assets = Total Liabilities + Total Equity

2.2 Income Statement (Profit & Loss)

Shows income and expenses over a period.

┌─────────────────────────────────────────────┐
│            INCOME STATEMENT                  │
│            Period: YYYY-MM to YYYY-MM        │
├─────────────────────────────────────────────┤
│ INCOME                                       │
│   Salary                     $XX,XXX         │
│   Investment Income          $X,XXX          │
│   ─────────────────────────────────          │
│   Total Income               $XX,XXX         │
├─────────────────────────────────────────────┤
│ EXPENSES                                     │
│   Housing                    $X,XXX          │
│   Transportation             $X,XXX          │
│   Food & Dining              $X,XXX          │
│   ─────────────────────────────────          │
│   Total Expenses             $XX,XXX         │
├─────────────────────────────────────────────┤
│ NET INCOME                   $X,XXX          │
└─────────────────────────────────────────────┘

2.3 Cash Flow Statement

Shows cash movements by category.

┌─────────────────────────────────────────────┐
│           CASH FLOW STATEMENT                │
│           Period: YYYY-MM to YYYY-MM         │
├─────────────────────────────────────────────┤
│ Operating Activities                         │
│   Net Income                 $X,XXX          │
│   (Adjustments)              ($XXX)          │
│   ─────────────────────────────────          │
│   Net Operating Cash         $X,XXX          │
├─────────────────────────────────────────────┤
│ Investing Activities                         │
│   Investment Purchases       ($X,XXX)        │
│   Investment Sales           $X,XXX          │
│   ─────────────────────────────────          │
│   Net Investing Cash         ($XXX)          │
├─────────────────────────────────────────────┤
│ Financing Activities                         │
│   Loan Payments              ($X,XXX)        │
│   ─────────────────────────────────          │
│   Net Financing Cash         ($X,XXX)        │
├─────────────────────────────────────────────┤
│ NET CASH CHANGE              $X,XXX          │
└─────────────────────────────────────────────┘

---

3. Multi-Currency Consolidation

Base Currency

Reports are generated in a single base currency (user configurable, default: SGD).

FX Rate Application

• Use period-end rate for balance sheet items
• Use average rate for income statement items
• Record unrealized FX gains/losses separately

def consolidate_amount(amount: Decimal, currency: str, target: str, date: date) -> Decimal:
    if currency == target:
        return amount
    rate = get_fx_rate(currency, target, date)
    return (amount * rate).quantize(Decimal("0.01"))

---

4. Design Constraints

✅ Recommended Patterns

• Pattern A: Report generation is read-only, never modifies ledger
• Pattern B: Always validate accounting equation before rendering
• Pattern C: Cache report results with date-based invalidation
• Pattern D (Performance): Pre-fetch all necessary FX rates in bulk before starting report calculation to avoid N+1 queries.
• Pattern E (Reliability): Cap trend data points at 366 (one year of daily data) to prevent memory issues with unbounded queries.

⛔ Prohibited Patterns

• Anti-pattern A: NEVER hardcode account codes in report logic
• Anti-pattern B: NEVER generate reports without FX rate data

---

5. Verification

Behavior	Test Method	Status
Balance sheet balances	test_balance_sheet_equation	✅ Implemented
Income statement period	test_income_statement_calculation	✅ Implemented
Multi-currency consolidation	test_fx_consolidation	⏳ Pending
Account trend	test_account_trend_monthly	✅ Implemented
Category breakdown	test_category_breakdown_quarterly	✅ Implemented
Cash flow statement	test_cash_flow_statement	✅ Implemented
Tag filtering	test_income_statement_with_tags_filter	✅ Implemented
Account type filtering	test_income_statement_with_account_type_filter	✅ Implemented

---

Used by

• schema.md
• accounting.md