Skip to content

Module Spec: FintraOS Views

1. Overview

FintraOS Views is designed to be the "Consumption Layer" of the platform. It will provide the clean, product-ready APIs that developers use to build user interfaces.

While Core is normalised for data integrity (complex graph) and Pulse is for events (push), Views will be optimised for reading (pull). It will abstract away the complexity of the underlying Event Sourcing and Graph models into simple, domain-specific JSON objects.

Core Responsibilities: 1. Data Aggregation: Combining data from Profile, Vault, and Brain into single responses. 2. Denormalisation: serving pre-computed "Read Models" for high performance (sub-50ms). 3. Query Flexibility: Providing both REST (standard) and GraphQL (flexible) interfaces.

2. API Philosophy: "Product-First"

We will not just expose database tables. We will expose Product Concepts.

  • Bad API: GET /transactions?type=debit&category=12
  • FintraOS View: GET /views/spend-analysis?period=current_month
  • Returns: Total spent, top categories, comparison to last month, and relevant transactions.

3. Key Views (Read Models)

3.1. The "Unified 360" View

The "God Object" for a user. Will be used to hydrate the main dashboard of a PFM app. - Endpoint: GET /v1/views/profile/summary - Payload: 

{
  "net_worth": {
    "total": 154300.00,
    "currency": "GBP",
    "change_30d": 2.5
  },
  "cash_flow": {
    "status": "HEALTHY",
    "days_runway": 45,
    "safe_to_spend": 240.00
  },
  "alerts": [
    { "type": "bill_upcoming", "message": "Rent due in 3 days (£1,200)" }
  ],
  "insights": [
    { "type": "saving_opportunity", "value": "Switch energy provider to save £200/yr" }
  ],
  "platform_data": {
    "rides_completed": 45,
    "driver_tier": "GOLD",
    "custom_score": 850
  }
}

3.2. Wealth & Portfolio View

Will aggregate investments, pensions, crypto, and property. - Endpoint: GET /v1/views/wealth - Features: - Asset Allocation: Breakdown by asset class (Equity, Fixed Income, Cash, Crypto). - Performance: Time-weighted return calculations across all unconnected platforms. - Fees: Hidden fee analysis.

3.3. Debt & Liabilities View

  • Endpoint: GET /v1/views/debt
  • Features:
  • Snowball/Avalanche: Calculator pre-computed.
  • Refinancing: Opportunities to consolidate debt.
  • True Cost: Total interest payable over the lifetime of all loans.

3.4. Income & Tax View

  • Endpoint: GET /v1/views/income
  • Features:
  • Stability Score: How stable is the user's income?
  • Tax Estimation: Real-time tax liability estimation based on inflows.
  • Gig Economy: Separation of salary vs. freelance income.

3.5. Aggregate Analytics (B2B)

For tenants to understand their user base as a whole. - Endpoint: GET /v1/views/analytics/aggregate - Features: - Cohort Analysis: "What % of users have < £100 savings?" - Spending Trends: "Is 'Dining Out' increasing across my user base?" - Churn Signals: "List users with high 'Churn Probability' scores."

3.6. AI Agent Configuration

Will allow configuration of the persona and skills of the embedded AI. - Endpoint: PUT /v1/views/agent/config - Payload: 

{
  "persona": {
    "name": "Fintra Coach",
    "tone": "EMPATHETIC", // or PROFESSIONAL, STRICT
    "system_prompt_override": "You are a helpful financial assistant..."
  },
  "enabled_skills": ["transfer_money", "explain_fees"]
}

3.7. The "Simulation" View (Sales Tool)

Will visualise the results of a simulation run in Module-Vault. - Endpoint: GET /v1/views/simulation/{job_id} - Payload: 

{
  "scenario": "Auto-Save Rule",
  "historical_period": "2023",
  "results": {
    "total_saved": 450.00,
    "trigger_count": 12,
    "graph_data": [ ... ]
  }
}

4. GraphQL Schema

For complex, nested queries, we will offer a full Graph.

5. Technical Architecture

4.1. CQRS (Command Query Responsibility Segregation)

Views will be the Read side of our architecture. 1. Write Side (Core): Processes Commands -> Emits Events. 2. Projectors: Listen to Events -> Update Read DB (PostgreSQL). 3. Read Side (Views): Queries Read DB -> Serves JSON.

This ensures that heavy analytical queries (e.g., "Show me spending trends over 5 years") never slow down transaction processing.

4.2. Technology Stack

  • Database: PostgreSQL (JSONB) (for flexible document storage of Views).
  • API Layer: GraphQL Federation (combining sub-graphs).
  • Caching: Redis (Edge caching for instant mobile app load).

5. Developer Experience

5.1. The "Query Builder" SDK

const dashboard = await fintra.views.getDashboard({
  sections: ['net_worth', 'recent_transactions', 'forecast', 'platform_data'],
  period: '30d'
});

// Accessing dynamic metrics defined in Module-Brain
console.log(dashboard.platform_data.rides_completed);

5.2. UI Components (Optional Library)

We will provide "Headless UI" hooks for React/React Native. 

const { safeToSpend, loading } = useFintraCashflow();
return <Text>Safe to Spend: {safeToSpend}</Text>;