Financial Data Review

GET /api/v1/applications/app_20251222_143023_usr123/financial-summary
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

// Query Parameters (optional)
?include_transactions=true
&period_months=24

{
  "request_id": "req_cm02_20251222_143125",
  "status": "success",
  "data_quality_score": 0.98,
  "financial_summary": {
    "revenue": {
      "annual": 450000,
      "formatted": "£450,000",
      "yoy_growth": 0.18,
      "monthly_average": 37500,
      "source": "xero_uk",
      "verified": true
    },
    "expenses": {
      "annual": 312300,
      "formatted": "£312,300",
      "breakdown": {
        "operating": 285000,
        "capital": 27300
      },
      "flagged_items": [
        {
          "transaction_id": "txn_espresso_2500",
          "amount": 2500,
          "description": "Commercial espresso machine",
          "current_category": "operating_expense",
          "suggested_category": "capital_expenditure",
          "confidence": 0.94
        }
      ],
      "source": "xero_uk"
    },
    "profit": {
      "net": 137700,
      "formatted": "£137,700",
      "margin": 0.306,
      "trend": "increasing"
    },
    "cashflow": {
      "current_balance": 48200,
      "average_balance_12m": 42500,
      "source": "truelayer",
      "account_id": "acc_***4532"
    }
  },
  "data_sources": {
    "xero": {
      "last_sync": "2025-12-22T09:18:43Z",
      "records_pulled": 3487,
      "period_months": 36
    },
    "truelayer": {
      "last_sync": "2025-12-22T09:18:52Z",
      "transactions": 1847,
      "period_months": 24
    },
    "companies_house": {
      "company_number": "12345678",
      "company_name": "Smith's Artisan Café Ltd",
      "status": "active",
      "incorporation_date": "2022-03-15"
    }
  },
  "processing_time_ms": 2847,
  "timestamp": "2025-12-22T14:31:25Z"
}

PATCH /api/v1/applications/.../transactions/txn_espresso_2500/category

{
  "new_category": "capital_expenditure",
  "reason": "New espresso machine purchase - capital asset",
  "updated_by": "customer"
}

// Response: 200 OK with updated financial summary

// Data Aggregator Processing Steps

STEP 1: Parallel API Calls
├─ TrueLayer API    → Banking transactions (24 months)
├─ Xero API         → P&L, invoices, expenses (36 months)
└─ Companies House  → Company verification data

STEP 2: Data Normalization
├─ Standardize date formats (ISO 8601)
├─ Convert currencies to GBP
├─ Normalize account categories
└─ Remove duplicates across sources

STEP 3: Transaction Categorization
├─ ML model classifies each transaction
├─ Categories: Revenue, OpEx, CapEx, Cost of Goods, Taxes
├─ Confidence scoring per transaction
└─ Flag ambiguous items (confidence < 0.80)

STEP 4: Financial Metrics Calculation
├─ Annual revenue (sum all revenue transactions)
├─ Total expenses (OpEx + CapEx + COGS)
├─ Net profit (revenue - expenses)
├─ Profit margin (profit / revenue)
├─ YoY growth ((current - previous) / previous)
└─ Cashflow analysis (TrueLayer balance data)

STEP 5: Data Quality Scoring
├─ Completeness check (all required fields present?)
├─ Consistency check (Xero vs TrueLayer reconciliation)
├─ Recency check (data within last 90 days?)
└─ Overall score: 0.00 - 1.00

STEP 6: Anomaly Detection
├─ Flag unusual transactions (>3 std deviations)
├─ Identify potential miscategorizations
└─ Generate customer review suggestions

// Example: £2,500 espresso machine transaction

INPUT: {
  description: "Commercial espresso machine",
  amount: 2500,
  merchant: "CoffeeQuip Ltd",
  date: "2025-08-15"
}

ML ANALYSIS:
- Keywords: "commercial", "machine" → Equipment
- Amount: £2,500 → Above £1K threshold
- Merchant: Coffee equipment supplier
- Expected lifespan: >1 year (asset)
- Usage: Business operations (not resale)

PREDICTED CATEGORY: Capital Expenditure
CONFIDENCE: 0.94 (94%)

CURRENT XERO CATEGORY: Operating Expense
ACTION: Flag for customer review

// Olivia's café data quality assessment

Completeness: 1.00 (100% - all fields present)
Consistency:  0.97 (97% - £3K discrepancy in 36 months)
Recency:      1.00 (100% - synced today)
Accuracy:     0.95 (95% - 3 flagged transactions)

OVERALL SCORE:
(1.00 × 0.40) + (0.97 × 0.30) + (1.00 × 0.20) + (0.95 × 0.10) = 0.98 (98%)

KEY: financial_summary:app_20251222_143023_usr123
VALUE: // Full JSON response from aggregator
TTL: 300 seconds

// Cache invalidation triggers:
- Customer re-categorizes transaction
- Customer requests manual refresh
- External API data updated (webhook)

UPDATE applications
SET 
  status = 'data_reviewed',
  annual_revenue = 450000,
  annual_expenses = 312300,
  net_profit = 137700,
  profit_margin = 0.306,
  data_quality_score = 0.98,
  data_sources = 'xero_uk,truelayer,companies_house',
  last_data_sync = '2025-12-22 14:31:25',
  updated_at = '2025-12-22 14:31:25'
WHERE application_id = 'app_20251222_143023_usr123';

CREATE TABLE financial_transactions (
  transaction_id      VARCHAR(50) PRIMARY KEY,
  application_id      VARCHAR(50) REFERENCES applications,
  source              VARCHAR(20),  -- 'xero' or 'truelayer'
  transaction_date    DATE,
  amount              DECIMAL(12,2),
  description         TEXT,
  category            VARCHAR(50),
  ai_category         VARCHAR(50),  -- AI suggested category
  confidence_score    DECIMAL(3,2),
  flagged             BOOLEAN DEFAULT FALSE,
  customer_reviewed   BOOLEAN DEFAULT FALSE,
  created_at          TIMESTAMP
);

// Log 1: Data aggregation completed
{
  "log_id": "log_cm02_20251222_143125",
  "event_type": "financial_data_aggregated",
  "screen": "CM02",
  "user_id": "usr_olivia_thompson",
  "application_id": "app_20251222_143023_usr123",
  "timestamp": "2025-12-22T14:31:25Z",
  "details": {
    "sources": ["xero_uk", "truelayer", "companies_house"],
    "total_transactions": 5334,
    "data_quality_score": 0.98,
    "flagged_items": 1,
    "processing_time_ms": 2847
  }
}

// Log 2: Customer re-categorization
{
  "log_id": "log_cm02_20251222_143247",
  "event_type": "transaction_recategorized",
  "screen": "CM02",
  "user_id": "usr_olivia_thompson",
  "timestamp": "2025-12-22T14:32:47Z",
  "details": {
    "transaction_id": "txn_espresso_2500",
    "old_category": "operating_expense",
    "new_category": "capital_expenditure",
    "reason": "New espresso machine - capital asset",
    "amount": 2500
  }
}