Skip to content

Domain Model: Unified Financial Profile (Personal Finance)

0. Representation Rules (Canonical)

FintraOS is designed so the same inputs always produce the same outputs. That requires stable representation choices:

  • Timestamps: ISO‑8601 UTC (YYYY-MM-DDTHH:MM:SSZ).
  • Money: represented as minor units for computation and event payloads (*_minor as integers), and as decimal strings (or structured { value, currency }) at API boundaries where human readability matters.
  • Provenance: derived outputs (metrics, valuations, explanations) carry provenance to the underlying stream position (for example a source_event_id and source_version) so any number can be traced and reproduced.

1. Core Entities

1.1. Profile (The "Financial Twin")

The root aggregate for a user. 

{
  "profile_id": "usr_123",
  "tenant_id": "org_neobank_abc",
  "created_at": "2023-10-01T12:00:00Z",
  "base_currency": "GBP",
  "risk_score": 750,
  "segments": ["high_earner", "crypto_active"],
  "identity": {
    "legal_name": { "first": "Jane", "last": "Doe" },
    "dob": "1990-01-01",
    "email": "jane.doe@example.com",
    "phone": "+447700900000",
    "citizenship": "GB",
    "national_id": "AB123456C" // Stored encrypted in Vault.
  }
}

1.2. Account

A container for value. Supports connected feeds and manual entry. - Types: CHECKING, SAVINGS, CREDIT_CARD, LOAN, MORTGAGE, INVESTMENT, CRYPTO_WALLET, PROPERTY, OTHER_ASSET. - Source: PLAID, YAPILY, MANUAL.

1.3. Transaction

An atomic movement of value. - Standardised Fields: - amount: Signed decimal (negative = outflow). - currency: ISO code. - status: PENDING, POSTED. - balance_after (optional): The running balance after this transaction posts (when provided by the source). This enables deterministic reconciliation and supports balance derivation without requiring separate balance snapshots. - enrichment: - merchant_name: Cleaned name (e.g., "Starbucks"). - category: Hierarchical (e.g., Food & Drink > Coffee). - recurrence: WEEKLY, MONTHLY, SUBSCRIPTION.

See also: FintraOS Open Standard (FOS) for schema details.

1.4. Position

A representation of a holding inside an investment or crypto account.

  • Core fields: symbol, name, asset_class, quantity, market_value, currency, as_of.
  • Pricing fields (optional):
  • quote_symbol: canonical provider symbol used for pricing lookups when the display symbol is not sufficient (for example exchange-qualified tickers).
  • quote_currency: the instrument quote currency used for base-currency valuation and FX conversion when required.

2. Intelligence Models

2.1. CashflowStream

A detected recurring pattern. - type: INCOME | EXPENSE - frequency: MONTHLY - next_expected_date: 2023-11-01 - confidence_score: 0.95

2.2. Forecast

Probabilistic future states. - target_date: 2023-12-01 - predicted_balance: 1500.00 - lower_bound: 1200.00 - upper_bound: 1800.00

2.3. Provenance & Explanations

Any derived intelligence (for example “safe‑to‑spend”, “runway days”, or valuation totals) should be explainable and attributable:

  • Explainability: return the inputs and assumptions used (for example the accounts, transactions, and recurring streams that contributed).
  • Provenance: include the stream position used to compute the result (for example source_event_id and source_version), allowing deterministic replay and audit.

3. Configuration (Client Controlled)

3.1. RuleSet

Client-defined logic for "FintraOS Brain". 

{
  "rule_id": "rule_low_balance",
  "trigger": "transaction.created",
  "condition": {
    "and": [
      { "<": ["account.balance", 100] },
      { "==": ["account.type", "CHECKING"] }
    ]
  },
  "action": "emit_event:low_balance_warning"
}

4. Extensibility Models

4.1. PlatformData

External data points ingested from tenant platforms. - key: "rides_completed" - value: 45 - context: { "region": "london" }

4.2. AgentSkill

Capabilities exposed to the AI Agent (e.g., "transfer_money", "update_budget"). - skill_id: Unique identifier (e.g., "cmd_transfer_funds"). - name: Human-readable name. - description: Instructions for the LLM on when/how to use this skill. - webhook_url: The internal endpoint to call when this skill is invoked. - required_scopes: List of permissions required (e.g., ["money:move", "account:read"]). - governance: - risk_level: LOW | MEDIUM | HIGH | CRITICAL. - requires_human_approval: Boolean. - max_daily_limit: Monetary amount (if applicable).

See also: FintraOS Open Standard (FOS) for full schemas.