Technical Architecture & Developer Portal

1. System Architecture Overview

FINLOG is engineered to reconcile high-performance financial management with absolute personal privacy. Our technical stack combines:

• Client Application: React Native 0.88, Expo SDK 58, TypeScript, Expo Router with strict file-based routing.
• State Management: Zustand persistence with serialized atomic writes and custom encrypted storage adapters.
• Local Cryptography: AES-256-GCM via Expo Crypto and hardware-backed Expo SecureStore (WHEN_UNLOCKED_THIS_DEVICE_ONLY).
• Online Identity: Clerk JWT authentication with verified public keys.
• AI Gateway: Cloudflare Worker & Node server with Grok (xAI) and Groq LLM pipelines, guarded by Supabase RLS quota RPCs.
• Cloud Distribution: Cloudflare Global Edge Network with static asset bindings and strict HTTP security headers.

2. Vault Storage & Cryptographic Architecture

Traditional mobile applications persist user data as unencrypted JSON in AsyncStorage or SQLite. FINLOG intercepts all write operations via src/services/vaultStorage.ts:

// Encrypted Envelope Schema (AES-256-GCM)
interface EncryptedVaultEnvelope {
  version: 4;
  cipher: "aes-256-gcm";
  iv: string;          // 96-bit unique IV per snapshot (Base64)
  ciphertext: string;  // AES-GCM ciphertext payload
  tag: string;         // 128-bit authentication tag
  checksum: string;    // SHA-256 digest of original plaintext
  owner: string;       // Verified Clerk user ID namespace
  currency: string;    // Active ISO currency code (e.g. "GHS")
}

Key Isolation: Decryption keys are stored strictly in the operating system's hardware keychain using the WHEN_UNLOCKED_THIS_DEVICE_ONLY accessibility flag. Even if a backup of the device is performed via desktop tooling, keychain keys are excluded unless restored to the exact same device.

3. Identity & Authentication Boundaries

To eliminate the risk of server compromise exposing financial accounts, identity and ledgers are completely decoupled:

• The online identity server (Clerk) knows your email and authentication method, but possesses zero financial records.
• The cloud storage server (Supabase) receives encrypted envelopes where Row-Level Security checks that owner_id = auth.jwt()->>'sub', but possesses no decryption keys.
• The local device requires a verified Clerk JWT to unlock and hydrate the owner's encrypted partition. Switching accounts triggers a complete memory sweep and store rehydration.

4. FINAI Context Synthesis & Token Grounding

FINAI achieves high contextual utility while preserving data minimization through a 3-stage sanitization pipeline:

1. Client-Side Aggregation: src/ai/financialContext.ts calculates 30-day totals, active space balances, and category sums into numerical facts. Raw transaction strings and payee phone numbers are excluded.
2. Grounding Tokens: Instead of asking the LLM to perform arithmetic, prompt templates instruct the model to output verified placeholder tokens (e.g. {{fact_key}}). The client substitutes actual numbers post-stream.
3. Authoritative Quota Enforcement: The backend handler (server/assistant.ts) executes the atomic PostgreSQL RPC finlog_ai.claim_request under a database row lock before any LLM API call is made.

5. Public API & Integration Availability Notice

All network communication currently occurs exclusively between the authenticated FINLOG mobile application and our internal serverless API endpoints using signed Clerk JWT tokens.

We are designing a read-only local export bridge for future v2.x releases. If you are a financial institution, fintech developer, or researcher interested in partnering with FINLOG, please register your interest via our technical inquiry channel below.

6. Open Data Export Formats

FINLOG is committed to open data portability. Users can export their complete ledger at any time in two standard formats:

RFC 4180 Compliant CSV Export

Date,Type,Amount,Currency,Category,Space,Reference,Notes
2026-10-18T14:22:10Z,expense,45.00,GHS,Transport,Main Stack,Trotro Ride,Circle to Ridge
2026-10-17T09:15:00Z,expense,120.00,GHS,Bills,Main Stack,MTN Fiber,October data plan
2026-10-16T18:00:00Z,income,500.00,GHS,Hustle,Business,Consulting,Mobile UI Design

Structured JSON Vault Snapshot

{
  "version": 4,
  "exportedAt": "2026-10-21T06:00:00Z",
  "currency": "GHS",
  "spaces": [
    { "id": "space_main", "name": "Main Stack", "balance": 425000, "color": "#005073" }
  ],
  "transactions": [
    { "id": "tx_01", "amount": 4500, "type": "expense", "category": "transport", "spaceId": "space_main" }
  ]
}

7. Responsible Vulnerability Disclosure

We welcome constructive reports from security researchers. If you believe you have discovered a vulnerability in FINLOG's mobile application, cryptographic routines, or API endpoints, please disclose it responsibly: