Platform Overview

Table of Contents

1. What Is FoxCalc
2. How It Works
3. Integration Path
4. The Calculator Experience
5. The Funder Portal
6. API Reference Summary
7. Customization & Configuration
8. Formula Engine
9. Prepayment Models
10. Fee Configurability
11. Webhooks & Notifications
12. Attachment Handling
13. Security Architecture
14. Roles & Permissions
15. Audit & Compliance
16. Infrastructure & Reliability

What Is FoxCalc

FoxCalc is a multi-tenant MCA pricing calculator platform. Funders send deal parameters via API, FoxCalc hosts a branded calculator experience for ISOs (Independent Sales Organizations), and delivers the ISO's configured terms back to the funder via webhooks.

Key distinction: FoxCalc is a platform, not a single-client tool. Every funder gets their own isolated environment — their own brands, their own field labels, their own fee structures, their own callback endpoints, their own user roles. Nothing in the system is hardcoded to any single funder. Funder-specific behavior lives entirely in an adapter layer.

What Problem It Solves

Funders approve MCA deals with ranges — a purchase price between $20K and $50K, a term between 6 and 18 months, an upsell up to 5%. Today, communicating those ranges to ISOs is manual: spreadsheets, PDFs, phone calls. ISOs configure terms by guessing, back-and-forth emails follow, deals slow down.

FoxCalc replaces that with a live, interactive calculator the ISO opens in their browser. They drag sliders, see every number update in real time, and submit their configured terms with one click. The funder gets a structured callback within seconds.

Who Uses It

How It Works

The Deal Lifecycle

Funder sends deal via API
        ↓
    Offer created (draft or active)
        ↓
    Underwriter reviews in Portal (optional)
        ↓
    Deal released → signed calculator URL generated
        ↓
    ISO opens calculator → configures terms interactively
        ↓
    ISO submits → FoxCalc computes final terms
        ↓
    Webhook fires → funder receives structured callback
        ↓
    Offer status → submitted (terminal)

Offer Statuses

Valid transitions: draft → active → submitted, draft → revoked, active → expired, active → revoked

Integration Path

Phase 1 — Platform Setup (~1 day, FoxCalc team)

1. Create funder record with slug (e.g., fox, forward)
2. Create first admin user (sends invite email)
3. Configure SendGrid email infrastructure

Phase 2 — Funder Self-Service (~1–3 days)

4. Admin logs in, sets password via invite link
5. Creates brand(s) — logo, colors, display name
6. Adds DNS records for email domain (SPF/DKIM/DMARC)
7. Generates API key(s) with scopes
8. Configures field mapping (funder's field names → FoxCalc canonical schema)
9. Sets organization defaults — fees, stipulations, prepayment model, guardrails, terminology
10. Configures callback URL + secret
11. Subscribes to webhook events
12. Invites underwriter users

Phase 3 — Integration Testing (~1–5 days)

13. Funder sends test deals via API (draft status)
14. Underwriter reviews drafts, configures guardrails, previews calculator
15. End-to-end validation — release, open calculator, submit, verify callback
16. Funder confirms integration

Phase 4 — Go Live

17. Funder starts sending production deals
18. FoxCalc team monitors first batch

The Calculator Experience

The calculator is a React single-page application served from a signed URL. No login, no accounts, no sessions. The ISO clicks the link and starts configuring.

What the ISO Sees

Header:

• Funder's brand logo and name
• Merchant name, ISO name
• Deal type badge, approval date
• Expiration countdown (red when approaching)
• Funder notes (expandable)

Left Panel — Interactive Controls:

• Purchase price slider + text input (within funder-defined floor/ceiling)
• Estimated payments slider + text input (within funder-defined range)
• Frequency toggle — daily, weekly, monthly (available options set by funder)
• Upsell slider (0% to funder's max)
• Adjustable fees — each fee the funder marks as adjustable gets its own slider with floor/ceiling
• ISO notes — free text field (when enabled by funder)

Right Panel — Computed Terms (read-only, updates in real time):

• Purchase price, buy rate, total factor rate, amount sold
• Payment amount with frequency label (e.g., "$3,650/week")
• Number of payments, estimated term
• Commission (rate + dollar amount)
• Total fees, existing funding balance, net to merchant
• Holdback percentage, position
• Prepayment schedule table (when enabled)
• Stipulations list with file upload

Three Dynamic Constraints

The calculator enforces three constraints simultaneously via slider range adjustments — no error modals, no blocked states:

Submission Flow

1. ISO clicks "Request Contracts"
2. Confirmation modal shows all configured terms (layout and visible fields customizable by funder)
3. Pending file uploads complete automatically
4. ISO clicks "Confirm & Submit"
5. Server validates version (optimistic concurrency), computes final terms, stores submission
6. Webhook fires to funder with complete structured data
7. ISO sees success screen

Calculator States

Brand Theming

Every calculator renders with the funder's brand identity:

• Logo in header
• Primary color on CTAs, slider accents, active states
• Accent color on highlights
• Custom field labels via terminology overrides
• All applied as CSS custom properties at runtime — same layout, different skin

The Funder Portal

A Next.js admin application where funders manage everything. JWT session auth with role-based access control.

Deal Management

Deal List:

• Paginated with search (merchant name, ISO name, deal ID)
• Filter by status, brand, date range
• Sort by created date, merchant name, status, expiration
• Click through to deal detail

Deal Detail:

• Full deal parameters — all editable while in draft/active status
• Three-card layout: payment structure, pricing constraints, merchant data
• Fee editor with adjustability toggles and ranges
• Stipulations, notification emails, assigned users
• Preview button (opens calculator in new tab with submit disabled)
• Release button (draft → active, generates signed URL)
• Revoke button (cancels deal)
• Activity timeline — every lifecycle event with timestamps
• Webhook delivery logs — every callback attempt with status codes
• Submission details (if submitted) — all ISO selections, computed terms, attachments with download links

Manual Deal Creation:

• Full form pre-populated with funder defaults
• Create as draft or active
• All fields from the canonical offer schema

API Simulator:

• Build a deal payload using the same form
• Live JSON preview (snake_case, ready to paste)
• Copy as JSON or cURL
• "Simulate" button — validates, shows defaults that would be applied, shows final payload
• "Create This Deal" button — creates from simulation

Settings (13 Pages)

User Management

• Invite by email (sends branded invite with 7-day expiration)
• Bulk invite via CSV upload (up to 50 users, validation preview)
• Six roles with 20 permissions across 7 categories
• Per-user permission overrides (grants/revokes on top of role)
• Login history per user (timestamp, IP, event type, success/failure)

API Reference Summary

Three Route Namespaces

Funder API (/api/v1/{funder}/...) — HMAC signature auth

Calculator API (/api/v1/offers/...) — Signed URL auth

Portal API (/portal/api/...) — JWT session auth, ~38 endpoints

Covers: authentication, deal CRUD, brand management, API keys, user management, webhook subscriptions, audit log, roles & permissions, callbacks, field mapping, funder config.

Authentication Mechanisms

Optimistic Concurrency

Every offer has a version integer. ISO includes version in submission. Portal includes version in edits. Version mismatch → 409 Conflict with instruction to reload.

Customization & Configuration

Per-Funder Configuration

Every funder can customize:

Defaults Hierarchy

Funder defaults apply when offer-level data is missing:

Offer data (highest priority)
    ↓
Brand defaults
    ↓
Funder defaults (lowest priority)

Five default categories: fees, stipulations, prepayment config, guardrails, display config. Offer-level always wins. Arrays merge only when offer array is empty.

Formula Engine

All calculations live in @foxcalc/shared — imported by both calculator (client-side) and portal (server-side) to guarantee identical math.

12 Computed Fields

Two Constant Sets

Term estimation (PAYMENTS_PER_MONTH):

• Daily: 21.67 (260/12), Weekly: 4.33 (52/12), Monthly: 1

Display grouping (FREQUENCY_DIVISOR):

• Daily: 1, Weekly: 5, Monthly: 22.5

Frequency switching regroups payments without changing economics. Total repayment and term stay identical.

Prepayment Models

Three models supported simultaneously. Funder chooses per deal.

Model A — Step-Per-Month

Auto-generates a tier for every month from base term down to a floor. Factor rate steps down by a fixed amount per month.

Example: Base term 12 months, factor rate 1.38, rate step 0.02, floor 3 months → generates 10 tiers, each month earlier saves 2 points on the factor rate.

Tiers regenerate when ISO adjusts term or upsell. Number of tiers changes with term.

Model B — Fixed Windows

Fixed prepayment windows measured in months after funding. Each window has a specific discount in factor rate points.

Example: Month 1: 10pts off, Month 2: 7pts off, Month 3: 5pts off. Windows don't change when ISO adjusts term — they're relative to funding date.

Model C — Funder-Provided

Pre-computed table from funder's system. Dollar amounts are static; factor rates recalculate with ISO adjustments.

Uniform Output

All models produce the same PrepaymentTier structure: label, term/window, factor rate, amount sold, savings, discount points. The calculator renders them identically regardless of model.

Fee Configurability

Each deal can have unlimited fees. Each fee has independent configuration:

Dynamic ceiling enforcement: At low purchase prices, adjustable fee ceilings automatically tighten to prevent net-to-merchant going negative. The ISO never sees an error — the slider range adjusts.

Webhooks & Notifications

13 Webhook Event Types

Subscription Management

• Per-brand or funder-wide subscriptions
• Event type filtering (subscribe to any subset)
• Active/paused toggle
• HMAC-SHA256 signed payloads (X-Signature, X-Webhook-Event, X-Webhook-ID, X-Timestamp)
• Portal UI for full CRUD

Callback Delivery

When an ISO submits, the primary callback fires immediately:

Payload includes: deal ID, offer version, timestamp, all ISO selections, all computed terms, prepayment schedule, attachment download URLs (presigned, 72-hour expiration).

Retry strategy (8 attempts):

After 8 failures: marked as failed, notification email sent to all deal recipients.

Email Notifications

Five email templates, all programmatically generated with brand theming:

Submission emails include a JSON summary attachment and (if under 10 MB total) all stipulation files.

Attachment Handling

Upload Flow

1. ISO selects files in calculator (drag-and-drop or file picker)
2. Calculator requests presigned S3 upload URLs from API
3. Files upload directly from browser → S3 (never through API server)
4. Calculator confirms each upload
5. On submission, attachment metadata is included in the callback

Constraints

MIME type validated on upload (extensions are not trusted).

Delivery to Funder

Pull model: Callback includes presigned download URLs (72-hour default expiration, configurable per funder). Funder downloads at their pace.

Push model (planned): Platform pushes files to funder's system — multipart POST, SFTP, or S3-to-S3 copy.

Storage

S3, encrypted at rest (AES-256). Bucket structure: {funder_id}/{deal_id}/{stipulation_id}/{filename}. Retention configurable per funder.

Security Architecture

Four Authentication Boundaries

Input Validation

• All API inputs validated via Zod schemas
• SQL injection prevented via Drizzle ORM (parameterized queries)
• XSS prevented via React auto-escaping
• File upload MIME validation (content-based, not extension-based)
• Webhook URLs validated against private IP ranges (SSRF protection)

Security Headers

Every API response includes:

• Strict-Transport-Security (HSTS with preload)
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Content-Security-Policy (dynamic, scoped to allowed origins)
• Referrer-Policy: strict-origin-when-cross-origin

Secrets Management

• AWS Secrets Manager for production credentials
• No secrets in environment variables, config files, or code
• API key secrets stored as SHA-256 hashes (never in plaintext)
• Full key shown exactly once at creation

Rate Limiting

Per-funder overrides via rateLimits JSONB. Redis sliding windows with graceful degradation.

Roles & Permissions

Six Roles

20 Permission Atoms

Organized across 7 categories: Deals (9), Settings (2), Users (3), API Keys (3), Webhooks (1), Audit (1), Reports (1).

Three-Layer Resolution

1. Baseline — hardcoded per-role defaults
2. Funder customization — editable matrix in portal (per funder)
3. User overrides — per-user grants/revokes on top of role

Audit & Compliance

Audit Log

Every administrative action logged with:

• Actor (portal user, API key, or system)
• Action type (CRUD operations on any resource)
• Resource type and ID
• Request metadata (IP, user agent)
• Sanitized payload (13 sensitive patterns scrubbed)
• Timestamp (UTC)

Portal UI: paginated, filterable by action, actor, resource, date range.

Deal Activity Log

Every deal lifecycle event:

• Calculator opened (IP, user agent)
• Offer created, replaced, patched, revoked, expired
• Submission received
• Callback attempts and results

Login History

Per-user login tracking:

• Login, logout, token refresh, failed login
• IP address, user agent, session ID
• Success/failure with reason
• Portal UI with pagination and filters

Offer History

Full version history with before/after snapshots:

• Every create, replace, patch, revoke
• Changed field lists
• Actor tracking (API key or portal user)

Compliance Engine (Planned)

Stubbed for V2: APR calculation, state-specific disclosures (NYDFS, CA SB 1235, Virginia, Utah). Funder-computed compliance data passthrough supported in V1.

Infrastructure & Reliability

Tech Stack

Architecture

Monorepo with 4 packages sharing a single formula engine:

• @foxcalc/shared — types, formulas, constants (imported by all)
• @foxcalc/api — Fastify backend
• @foxcalc/calculator — React SPA
• @foxcalc/portal — Next.js admin app

Calculator and API share a domain via CloudFront path-based routing: /* → S3 (calculator), /api/* → ALB (API). Zero CORS anywhere.

Database

15 tables, 19 migrations, optimistic concurrency via version integers. All timestamps UTC (ISO 8601). JSONB for flexible payloads alongside structured columns.

Background Workers

• Callback delivery — BullMQ, 5 concurrent, 8 retries with exponential backoff
• Webhook dispatch — BullMQ, 10 concurrent, fire-and-forget
• Expiration cron — every 5 minutes, flips active offers past expiration date
• Expiry warnings — every 5 minutes, emails for deals expiring within 24 hours

Testing

Adapter Pattern

All funder-specific behavior is isolated in three adapter boundaries:

Adding a new funder means writing three adapter files. Zero changes to core platform code. "That's a config change" is the right answer to every funder request.