Stadium — Enterprise Wallet Ledger & Bulk Financial Document Export

01 — Context & Product Setting

Stadium's corporate clients manage organization-wide digital wallets to fund employee recognition, corporate gifting, and event orders. A single enterprise account can process tens of thousands of dollars in monthly transactions across multiple department administrators.

Finance teams require precise, auditable transaction histories, including itemized monthly statements, tax receipts, and exportable financial reports compatible with ERP accounting software (NetSuite, QuickBooks).

02 — Problem Analysis: The Financial Audit Gap

As corporate transaction volumes scaled, the legacy wallet interface suffered from three systemic vulnerabilities:

03 — Architecture: Append-Only Ledger & Export Pipeline

The wallet platform was re-architected around an Immutable Append-Only Ledger Pattern paired with an Asynchronous Document Export Pipeline:

[ 3-Endpoint Wallet API Contract ]
(Transactions, Documents, Balances)
                 │
                 ▼
[ Ledger Normalization & Invariant Layer ]
  ├── Cents Integer Normalization (Zero float drift)
  ├── Uniform Timestamp Parsing & Localization
  └── Canonical Transaction Classification
                 │
                 ├──────────────────────────────┐
                 ▼                              ▼
[ Virtualized Ledger UI ]         [ Bulk Financial Export Engine ]
  ├── Instant balance summary       ├── Chunked pagination fetch
  ├── Real-time search & filters    ├── In-memory CSV streaming
  └── Category breakdown            └── Presigned document ZIP packager

Financial Ledger Invariants

The client and server maintain four non-negotiable financial guarantees:

1. Append-Only Immutability: Ledger records are write-once. Transactions are never updated or deleted in place. Reversals and corrections appear as explicit opposite-signed delta transactions with bidirectional reference IDs.
2. Integer Arithmetic (Cents Principle): Monetary amounts are transmitted and computed strictly as integer cents ($10.50 = 1050). Formatting into currency strings is deferred to the presentation boundary, eliminating floating-point rounding errors.
3. Running Balance Verification: Each transaction entry carries its resulting snapshot balance. The client validates that PreviousBalance + Delta === CurrentBalance, raising a telemetry alert if ledger drift is detected.

04 — Transaction Classification & Normalization

Enterprise statements group raw ledger events into standardized financial buckets:

interface NormalizedTransaction {
  id: string;
  referenceNumber: string;
  amountInCents: number;
  balanceAfterInCents: number;
  category: "funding" | "disbursement" | "adjustment" | "expiration";
  timestamp: string; // Uniform ISO-8601
  downloadableDocuments: {
    type: "invoice" | "receipt" | "statement";
    url: string;
  }[];
}

05 — Bulk Financial Document Export Architecture

Corporate accountants regularly download full-year ledger dumps comprising thousands of rows and hundreds of accompanying PDF invoices.

Chunked Client-Side Export vs. Heavy Server Jobs

Rather than initiating heavy background worker jobs for mid-volume queries (under 5,000 entries), the system uses a Streamed Chunking Pipeline:

[ Accountant Selects Date Range & Format (CSV / PDF ZIP) ]
                             │
                             ▼
[ Windowed Cursor Pagination (500 records / chunk) ]
                             │
                             ▼
[ Client-Side Stream Assembler ]
   ├── In-memory CSV formatting with RFC-4180 escaping
   └── Concurrent pre-signed URL fetching for invoice PDFs
                             │
                             ▼
[ Client-Side ZIP Packaging (`JSZip` in Web Worker) ]
                             │
                             ▼
[ Deterministic File Download: `stadium-statement-{year}-{month}.zip` ]

Invariant Safeguards

• Memory-Safe Worker Packaging: ZIP archive compression runs inside a dedicated Web Worker to avoid blocking the main UI thread during compression of multi-megabyte invoice batches.
• Presigned URL Expiry Resilience: Documents are fetched using short-lived pre-signed S3 URLs. If an export spans multiple minutes, URLs are refreshed in batches to prevent 403 Forbidden errors mid-download.
• Audit-Proof CSV Generation: Special characters, formulas (=, +, -), and commas are sanitized according to RFC-4180 standards to prevent CSV injection vulnerabilities when files open in Microsoft Excel.

06 — Backward Compatibility & Version Migration

During the migration to the unified integer-based ledger API, legacy accounts contained historical records with ambiguous categories.

• Dual-Mode Normalization: The serializer detects historical transaction shapes and backfills canonical categories based on transaction metadata.
• Audit Transparency Banner: If an account views records predating the ledger upgrade, a non-intrusive notification clarifies that historical entries reflect archival statements.

07 — Technical Accounting: Architecture Choices

08 — Verified Business & Operational Outcomes

• 100% Elimination of Sub-Cent Accounting Inconsistencies: Integer-cents normalization completely resolved floating-point rounding errors across enterprise ledger summaries.
• Zero Statement Crash Reports: The defensive normalizer absorbed all legacy backend date variances without a single client-side runtime exception.
• 90% Drop in Finance Support Tickets: Self-service bulk CSV and invoice ZIP exports allowed corporate clients to close monthly books independently without engineering intervention.
• SOC-2 & Enterprise Audit Compliance: Deterministic append-only transaction tracking satisfied external financial auditors for Fortune 500 client accounts.