Module Spec: FintraOS Pulse

1. Overview

FintraOS Pulse is designed to be the "Nervous System" of the platform. It will be the real-time delivery mechanism that pushes critical financial events to Client Applications.

While Views (REST/GraphQL) requires the client to ask for data, Pulse will tell the client when something important happens. This enables Event-Driven UX (e.g., "Instant Notification: Salary Received").

Core Responsibilities: 1. Webhook Delivery: Reliable, retriable HTTP callbacks for server-to-server communication. 2. Streaming API: Server-Sent Events (SSE) or WebSockets for frontend real-time updates. 3. Subscription Management: Developers can subscribe only to the events they care about (e.g., risk.* or transaction.*).

---

2. Event Catalogue

Pulse will standardise all system outputs into a strict schema.

2.1. The Envelope

Every event sent to a client will follow this structure:

{
  "event_id": "evt_unique_123",
  "type": "brain.insight.low_balance_predicted",
  "api_version": "2023-11-01",
  "created_at": "2023-11-01T14:30:00Z",
  "data": { ...specific_payload... },
  "user": {
    "profile_id": "usr_123",
    "external_id": "client_user_abc" // The ID the client knows them by
  }
}

2.2. Critical Events

Topic	Event Type	Trigger	Payload
Connect	connect.sync.completed	Initial sync or daily refresh done.	{ new_transactions: 5 }
Connect	connect.identity.linked	Passport match confirmed.	{ source_profile_id: "..." }
Core	core.transaction.created	New spend detected.	{ amount: -50.00, merchant: "Uber" }
Brain	brain.insight.salary_received	Recurring income detected.	{ amount: 2500.00, confidence: 0.99 }
Brain	brain.risk.overdraft_warning	Forecast predicts < 0 balance.	{ days_until_zero: 5, amount: -20.00 }
Brain	brain.nudge.idle_cash	High balance + Low APY.	{ moveable_amount: 5000.00 }
Platform	platform.data.recorded	Custom data point ingested.	{ key: "rides_completed", value: 45 }
Market	market.price.alert	Asset price crossed threshold.	{ symbol: "BTC", price: 30000.00 }
Agent	agent.action.required	AI Agent needs user approval.	{ skill: "transfer", amount: 100.00 }

2.3. Agent Action Events

Will provide a dedicated stream for AI-driven actions requiring human-in-the-loop intervention. * Purpose: Bridges the gap between autonomous AI reasoning (Brain) and human authorisation (Guard). * Flow: 1. Brain decides a money transfer is optimal. 2. Guard flags it as "High Risk" (requires approval). 3. Pulse emits agent.action.required to the frontend. 4. User approves/rejects via UI. 5. Connect executes the approved action. * Payload Schema:

{
  "type": "agent.action.required",
  "action_id": "act_888",
  "skill": "cmd_transfer_funds",
  "reasoning": "Saves $50/month in fees",
  "expiry": "2023-11-01T15:00:00Z",
  "payload": {
    "amount": 500.00,
    "currency": "USD",
    "recipient": "Savings Account"
  }
}

---

3. Delivery Mechanisms

3.1. Webhooks (Server-to-Server)

Will be the primary integration for backend logic. - Security: HMAC-SHA256 signature header (X-Fintra-Signature) using the Client Secret. - Reliability: Exponential backoff retries (up to 3 days). - Batching: High-volume events (like initial sync) are batched to prevent DDOSing the client.

Configuration:

{
  "url": "https://api.neobank.com/webhooks/fintra",
  "secret": "whsec_...",
  "events": ["brain.*", "connect.sync.failed"]
}

3.2. Pulse Stream (Frontend / Mobile)

Will be a Server-Sent Events (SSE) endpoint for direct-to-client streaming. - Endpoint: GET /v1/pulse/stream - Auth: Client JWT (scoped to single user). - Use Case: - Updating the "Net Worth" number live as markets move. - Showing a "New Transaction" toast notification instantly.

---

4. Architecture

4.1. The "Fan-Out" Engine

Pulse will sit at the end of the internal Kafka pipeline. 1. Ingest: Consumes internal topics (core-events, brain-events). 2. Filter: Checks WebhookSubscription table (Does Tenant X care about this?). 3. Transform: Maps internal Proto/Avro format to public JSON schema. 4. Dispatch: - Pushes to SQS (Queue) for Webhook Workers. - Pushes to Redis Pub/Sub for SSE Gateways.

4.2. Rate Limiting & Protection

To protect Client Infrastructure, the system will include: - Circuit Breakers: If a client endpoint returns 500 errors > 10 times, we will pause delivery for 5 minutes. - Throttling: Max 100 events/sec per tenant (configurable).

---

5. Developer Experience

5.1. The "Event CLI"

Developers will be able to listen to events locally without setting up ngrok.

$ fintra listen --events "brain.*"
> Ready! Listening for events...
> [2023-11-01 14:30] brain.insight.salary_received: { amount: 2500.00 }

5.2. Replay API

"I missed the webhook because my server was down." - POST /v1/pulse/replay - Body: { "start_time": "2023-11-01T12:00:00Z", "end_time": "2023-11-01T13:00:00Z" } - Result: Pulse re-sends all events from that window with a replayed: true flag.