Skip to content

Module Spec: FintraOS Connect

1. Overview

FintraOS Connect is designed to be the gateway for ingestion. It will handle the complexity of connecting to external financial institutions and normalising their diverse data formats into the FintraOS Core standard (see Domain-Model).

Key Strategy: - Phase 1: Wrap third-party aggregators (Plaid, Yapily, GoCardless, Truelayer) to achieve instant global coverage. - Phase 2: Build direct Open Banking / PSD2 integrations for high-volume markets to reduce costs. - Manual Entry: Provide API endpoints for users to manually push asset data (property, watches, art, cash).

2. Core Entities

2.1. Connection (The "Item")

Will represent a linked credential at a financial institution. 

{
  "connection_id": "conn_888",
  "tenant_id": "org_abc",
  "user_id": "usr_123",
  "provider": "PLAID_UK",
  "institution_id": "ins_barclays",
  "status": "ACTIVE", 
  "error_code": null,
  "last_synced_at": "2023-10-27T10:00:00Z",
  "consent_expires_at": "2024-01-25T10:00:00Z"
}

Status Enum: - ACTIVE: Healthy, syncing normally. - PENDING: User is in the auth flow. - ERROR: Sync failed (e.g., bank downtime). - EXPIRED: Consent token expired (requires user re-auth). - DISCONNECTED: User revoked access.

2.2. ManualAsset

Will represent user-entered data not backed by a live feed. 

{
  "asset_id": "ast_999",
  "type": "REAL_ESTATE",
  "name": "London Apartment",
  "currency": "GBP",
  "value": 450000.00,
  "valuation_date": "2023-09-01",
  "attributes": {
    "address": "123 Baker St",
    "purchase_date": "2015-05-20"
  }
}

3. Architecture

3.1. Provider Abstraction Layer (PAL)

Will consist of a set of adapters that translate provider-specific webhooks into FintraOS Internal Events.

  • Input: Plaid.TransactionsUpdate (Webhook)
  • Process: Fetch latest data -> Normalise -> Publish
  • Output: Connect.SyncCompleted (Event)

3.2. Manual Entry API

Will provide endpoints for clients to push data directly. - POST /v1/assets/manual - PUT /v1/assets/manual/{id}/value (Updates history in Vault)

3.3. Custom Data Ingestion (Platform Extensibility)

Will allow tenants to ingest platform-specific data points that fall outside the standard banking model, but should be stored and analyzed by the FintraOS engine. - Endpoint: POST /v1/ingest/custom - Use Case: A gig-economy platform ingesting "Number of Rides" or "Driver Rating" to correlate with income. - Payload: 

{
  "user_id": "usr_123",
  "event_type": "PLATFORM_METRIC_UPDATE",
  "timestamp": "2023-10-27T14:00:00Z",
  "data": {
    "metric_key": "completed_jobs",
    "value": 45,
    "context": { "service_type": "delivery" }
  }
}
- Flow: Ingest -> Validate against Tenant Schema -> Publish Connect.CustomDataReceived -> Core stores in Event Log.

3.4. Webhooks-as-Data-Sources

Instead of polling, tenants will be able to pipe their internal event streams directly into FintraOS. * Mechanism: Tenants register a Webhook Source in the Fintra Dashboard. * Configuration: * source_name: "Uber Driver Events" * mapping: Map json.body.driver_id -> fintra.user_id * Endpoint: POST /v1/ingest/webhook/{source_id} * Process: Connect receives the payload -> Transforms it using the Tenant's Mapping -> Emits Connect.CustomDataReceived.

3.5. Identity Bridge (The Passport Intake)

Connect will be responsible for gathering the raw identity data needed to form the "Financial Passport." - Source A (Partner Provided): The Client App sends KYC data (Name, DOB, Email) when initialising the session. - Source B (Bank Provided): Connect extracts account holder names (identity/get) from the banking provider to verify the user matches the account.

3.6. Global Context Providers (Reference Data)

To power "Intelligent" analysis, Connect will ingest external market and environmental data. - Purpose: Provides the "Denominator" for financial calculations (e.g., Real Wealth = Assets / Inflation). - Sources: 1. MarketStream: Real-time pricing for Equities, Crypto, Forex, and Commodities. 2. MacroStream: Economic indicators (CPI/Inflation, Central Bank Base Rates). 3. PropertyStream: Automated valuation models (AVM) for Real Estate (e.g., Land Registry, Zillow). 4. ComplianceStream: Tax brackets, Pension allowances, ISA limits. 5. GreenStream: ESG ratings and Carbon Impact factors for merchant categories.

4. Workflows

  1. Init: The client app will initialise Connect with user identity: 
    { "email": "jane@doe.com", "name": "Jane Doe", "dob": "1990-01-01" }
  2. Resolution: Connect calls Guard to check for an existing IdentityRecord.
  3. Match Found: Connect returns match_found: true. Client can show "Welcome back, Jane! Connect your Barclays account?"
  4. No Match: Proceed to standard linking.
  5. Token: FintraOS generates a link_token for the provider.
  6. Auth: User authenticates with their bank.
  7. Exchange: FintraOS swaps tokens and triggers Identity Verification (does Bank Name match App Name?).
  8. Sync: Account data is ingested.

If a user is matched to an existing Identity Record: 1. Prompt: User consents to "Link existing profile." 2. Hydrate: Connect emits Connect.ProfileLinked event. 3. Merge: FintraOS Core merges the historical data (categories, patterns, net worth history) from the global identity into this new tenant profile. 4. Result: The user starts Day 1 with a full financial history, not a blank slate.

4.3. Webhook Handling

  1. Provider sends WEBHOOK_SYNC_UPDATES.
  2. FintraOS Connect acknowledges (200 OK).
  3. Connect queues a SyncJob.
  4. SyncJob fetches data, diffs with existing state, and publishes Core.TransactionsImported events.