Vault

Long-term archival and simulation engine. Run 'What-If' scenarios on historical data to demonstrate value or backtest strategies.

PostgreSQL

Read Documentation

v1.0

Overview

FintraOS Vault is designed to be the "Black Box" of the platform. It will be responsible for the long-term, immutable storage of all financial history and the operational observability of the system.

While Core manages the *current state*, Vault will manage the *history*. It answers the question: "What did this user's profile look like on January 1st, 2020?"

Core Responsibilities:

01. Immutable Event Store: The source of truth for every change in the system (see ADR-001).

02. Time Travel Debugging: Reconstructing past states for audit or support.

03. Data Lineage: Tracking *where* a data point came from (e.g., "Was this category set by Plaid, the ML Model, or the User?").

04. Feed Health: Monitoring the latency and quality of connections.

View technical specifications in documentation

Core Entities

`EventRecord`

Will be the atomic unit of storage.

Structure: Event ID, Stream ID (Aggregate ID), Event Type, Version, Timestamp, Causation/Correlation IDs, Actor, and Payload.

Payload: Encrypted by Guard Sidecar before writing (e.g., transaction details, old/new category, confidence score).

`Snapshot`

An optimisation to avoid replaying 1 million events.

Structure: Snapshot ID, Stream ID, Version, and Full State JSON.

`FeedHealthMetric`

Will track the reliability of external aggregators.

Attributes: Metric ID, Provider, Institution ID, Latency, Success Rate, Error Count, and Window Start.

Architecture

Storage Tiers

Vault will utilise a tiered storage architecture to balance cost and speed. * Hot Store (PostgreSQL): Recent events (last 90 days). Optimised for transactional writes and immediate reads. * Warm Store (TimescaleDB): Time-series data (balances, stock prices) for the last 2 years. * Cold Store (S3 / Parquet): Archived events older than 2 years. Cheap, immutable, used for training ML models.

The "Replay" Engine

Will allow developers to "Time Travel." * Input: profile_id, target_date. * Process:

01. Find the nearest Snapshot *before* target_date.

02. Load Snapshot.

03. Replay all EventRecords from Snapshot Version up to target_date.

* Output: The exact JSON state of the profile at that moment.

Lineage Tracker

Every field in the Read Model will include a "Source" tag derived from Vault. * category: "Groceries" * _meta.category.source: "MODEL_V2" * _meta.category.updated_at: "2023-10-01"

This is critical for debugging "Why did the AI tag this wrong?"

The Simulation Engine (What-If Scenarios)

Will be a powerful B2B sales tool allowing tenants to simulate logic on historical data. (Consumed by [[Specs/Module-Views#3.7. The "Simulation" View (Sales Tool)|Simulation View]]).

Process: Replays the user's history through a "Virtual Intelligence" running the new logic.

Example: "IF transaction.category == 'Coffee' AND amount > 3.00 THEN savings += (amount - 3.00)"

Result: Returns comparison of actual vs. simulated outcomes (e.g., "Simulated Savings: £450.50").

Value: "Show, don't just tell" value proposition for prospective customers.

Compliance & Audit

The "Audit Log" View

Will be a developer-facing API to show end-users *who* did *what*. * GET /v1/vault/audit?profile_id=usr_123 * Response: * "User logged in (IP 1.2.3.4)" * "User linked Barclays Account" * "System detected Salary" * "Support Agent X viewed Profile (Reason: Ticket #555)"

Crypto-Shredding Verification

When Guard deletes a key, Vault will:

01. Run a verification job.

02. Attempt to decrypt a random sample of events for that user.

03. If decryption fails (as expected), it logs a Compliance.ErasureVerified event.

Diagnostics API (Internal)

`GET /v1/vault/health/providers`

Will return the real-time status of bank connections. * "Chase US: Degraded (High Latency)" * "Revolut UK: Operational"

`POST /v1/vault/replay`

Will trigger a replay of events to fix corrupted state. * *Use Case:* We deployed a bug in the "Net Worth" calculator. We fix the bug, then ask Vault to "Replay all events for Tenant X" to repair their dashboards.

`POST /v1/vault/simulate`

Will allow tenants to run "What-If" scenarios on historical data to prove value to their users.

Use Case: "If you had used our 'Round-Up' feature last year, how much would you have saved?"

Process: Clone stream -> Inject Logic -> Replay -> Compare End State.

Ready to integrate Vault?

Get full access to the Vault SDK and start building the future of finance today.

View Full Specs