System Documentation
Technical Blueprint
Platform architecture, scoring engine, and infrastructure reference
Introduction
Platform Overview
YieldStream is a Submission Intelligence Platform for MCA ISO owners. It replaces gut-feel lender routing with a deterministic scoring engine that learns from every funded and declined deal your organization processes.
What YieldStream does
The platform acts as a Digital Head of Submissions — ingesting bank statement PDFs, auto-underwriting merchants through a multi-stage AI pipeline, scoring every lender in your network against each deal, and returning a ranked recommendation set weighted by your ISO's specific pull-through history with each lender.
Where legacy CRMs store deal history, YieldStream interprets it. Every funded and declined outcome feeds back into the model, making predictions more accurate over time.
Architecture
| Layer | Technology |
|---|---|
| Frontend | Next.js 15, SCSS/BEM design system, shadcn/ui |
| Backend | Supabase (PostgreSQL + Auth + Storage), 19 API routes, TypeScript strict |
| Intelligence | Gemini 1.5 Flash via Inngest, three-layer scoring engine, 24h prediction cache |
| Background jobs | 13 Inngest functions — OCR, AI enrichment, predictions, outcomes, renewals |
| Security | RLS on 18+ tables, RBAC (Owner/Admin/Rep), AES-256 document storage |
| Deployment | Vercel (app.yieldstream.ai), Cloudflare DNS |
Core capabilities
| Capability | Description |
|---|---|
| AI Bank Statement Analysis | Multi-provider extraction pipeline with circuit breaker fallback. LlamaParse OCR feeds into Gemini 1.5 Flash enrichment — with automatic provider failover ensuring continuity. Extracts 20+ risk signals including revenue trends, NSF patterns, stacking detection, and anomaly flags. |
| Three-Layer Lender Scoring | Global market signals (25%) + your ISO's relationship history (50%) + merchant-to-buy-box attribute matching (25%). Composite score 0–100. |
| Outcome Learning Loop | Every funded or declined deal feeds back into the model. Decline penalties auto-expire after 30 days. Funded deals strengthen relationship scores. |
| Renewal Forecasting | Daily cron dispatches alerts 60 days before each funded merchant's estimated 50% paydown — the optimal MCA renewal window. |
| Multi-Tenant Isolation | Row-Level Security on every data table. Your lender relationships and submission history are never visible to other ISOs on the platform. |
Underwriting Engine
Document Ingestion & AI Enrichment
Bank statements trigger a five-stage pipeline from upload to scored risk signals. All AI inference is asynchronous — it runs via Inngest background jobs and never blocks the interface.
1
File validation
Client-side and server-side checks enforce allowed types (PDF, JPG, PNG) and a 50 MB size limit. Executable files are rejected at both layers.
2
Inngest event dispatch
Successful upload emits document/bank-statement.uploaded to the event bus with document ID and org_id.
3
LlamaParse OCR
Extracts structured markdown from the PDF. Output persisted to parsed_statements. Falls back to Gemini native document input if LlamaParse is unavailable — same output schema either way.
4
Gemini 1.5 Flash enrichment
Normalized markdown + merchant context (industry, state, FICO) sent to Gemini. Returns structured JSON populating all 12 AI signal columns. Raw bank statements, account numbers, and SSNs are never transmitted to external AI services.
5
Signal storage & audit
AI columns written to parsed_statements. Underwriting analysis updated. Append-only audit log entry created with action type AI_ENRICHMENT.
Extracted signal definitions
| Signal | Type | Definition |
|---|---|---|
| monthly_revenue_avg | DECIMAL | Mean gross monthly deposits, normalized for partial months. |
| monthly_revenue_trend | VARCHAR | growing (>5% MoM), stable (±5%), or declining. |
| average_daily_balance | DECIMAL | Time-weighted mean of daily closing balances. Weekend gaps use prior business day's balance. |
| stacking_burden_pct | DECIMAL | Total active MCA daily payments ÷ (monthly revenue / 21 business days). Percentage of daily revenue committed to existing MCA obligations. |
| active_mca_positions | JSONB[] | Detected advance positions. Each entry: lender name, daily debit (USD), estimated balance. |
| nsf_count | INTEGER | Non-Sufficient Funds events in the analysis window. Strongest single negative signal for lender approval. |
| flagged_anomalies | TEXT[] | AI-flagged patterns requiring human review: circular deposits, large one-time deposits, garnishment-pattern debits. |
| ai_confidence | 0.0–1.0 | Extraction quality score. Below 0.70 triggers a low-confidence flag and prompts human review before submission. |
Three-Layer Scoring
Composite Score Formula
Every lender recommendation is computed from three independent layers. The composite score (0–100) represents a specific lender's suitability for a specific merchant deal, weighted by your ISO's relationship history with that lender.
composite_score = (0.25 × global_score)
+ (0.50 × relationship_score)
+ (0.25 × attribute_score)
+ (0.50 × relationship_score)
+ (0.25 × attribute_score)
Layer A — Global score 25% weight
Market-level lender performance derived from anonymized, aggregate outcomes across all YieldStream organizations. No ISO-specific data is exposed in this layer.
global_score = 30 + (weighted_approval_rate × 70)
A floor of 30 preserves market-presence signal for lenders with zero recent approvals. Lenders with no recorded outcomes default to baseline 50.
Time-decay weighting
≤ 30 days
100%
31–90 days
40%
91–180 days
20%
> 180 days
5%
Layer B — Relationship score 50% weight
Your ISO's pull-through history with each lender, weighted by recency. Two ISOs submitting the same merchant to the same lender receive different composite scores based entirely on their individual track records. Your relationship data is never shared with competing ISOs.
Relationship multiplier
ISOs who have established a strong, consistent track record with a specific lender receive an automatic score boost. This reflects the model's recognition that proven relationships are the most reliable predictor of funding success — and it compounds the more deals you close.Layer C — Attribute score 25% weight
Deterministic rule-based calculation measuring the merchant's risk profile against the lender's published buy-box criteria. Operates independently of any historical data.
| Attribute | Signal | Logic |
|---|---|---|
| Revenue headroom | Positive | Merchant revenue above lender minimum. Greater headroom = stronger signal. |
| FICO headroom | Positive | Owner FICO above lender minimum. |
| NSF frequency | Negative | Each NSF event decrements the attribute score. |
| Position count | Negative | Active MCA positions approaching lender maximum reduces score. |
| ADB strength | Positive | Average daily balance relative to advance amount requested. |
Hard disqualification rules
Before scoring, lenders are permanently removed from the recommendation set if any of the following are true. These checks cannot be overridden by any score.
| Rule | Condition |
|---|---|
| State restriction | Merchant's state is in lender's restricted_states |
| Industry restriction | Merchant's industry is in lender's restricted_industries |
| Revenue minimum | Monthly revenue below lender's min_monthly_revenue |
| FICO minimum | Owner FICO below lender's min_fico |
| Position limit | Active MCA positions exceed lender's max_positions |
Metric Definitions
Authoritative Metric Reference
Canonical definitions for all metrics surfaced in the Analytics Dashboard and Deal Intelligence panels. These establish a common language between your ISO, YieldStream, and your lender network.
Submission pipeline
| Metric | Definition |
|---|---|
| Pull-through rate | Funded ÷ total submitted to a specific lender, within a time window. Primary measure of broker-lender relationship health. Displayed with time-decay weighting in Lender Intel. |
| Ghosting rate | Unresponsive submissions ÷ total submissions over a rolling 30-day window. Elevated ghosting signals misaligned submissions or a deteriorating lender relationship. |
| Composite score | Output of the three-layer model (0–100). Above 85 = high confidence. 70–84 = moderate. Below 70 = marginal match. |
| Prediction accuracy | Funded outcomes where the top-ranked lender was correct ÷ total top-ranked submissions. Surfaced only after minimum outcome volume is reached. |
| Approval rate | Funded deals ÷ total submitted across all lenders for the org, within a given period. |
Financial metrics
| Metric | Definition |
|---|---|
| ADB | Average Daily Balance. Time-weighted mean of daily closing balances. Formula: Σ(daily_balance × days_held) / total_days. Weekend gaps use prior business day's balance. |
| Stacking burden % | Total active MCA daily payments ÷ (monthly revenue / 21 business days). Above 25% is high-risk for most MCA lenders; above 40% triggers a hard flag. |
| Expected yield ($) | Projected broker commission in dollars — not percentage — enabling direct comparison across lenders with different commission structures. |
| Days to offer | Calendar days from submission to term sheet receipt. Tracked per lender, displayed as an average in the Lender Intel view. |
| Prediction variance % | Difference between predicted commission/factor rate at submission time and actual funded terms. Measures model accuracy per lender over time. |
Renewal metrics
| Metric | Definition |
|---|---|
| Estimated 50% paydown | Projected date a funded merchant repays 50% of their advance. Formula: funded_at + (term_days / 2). The YieldStream renewal trigger — alerts dispatch 60 days before this date. |
| Estimated payoff date | Projected full repayment: funded_at + term_days. Used for portfolio monitoring, not a contractual obligation. |
| Relationship health score | The Layer B score (0–100) for a specific ISO-lender pairing. Displayed with time-decay opacity encoding — lenders with older or fewer outcomes appear visually desaturated. |
Analytics Dashboard
Four-View Analytics System
The analytics dashboard is organized into four purpose-built views. Access is governed by role permissions and data-readiness thresholds — the system does not surface accuracy metrics until there is sufficient data to make them statistically meaningful.
| View | Primary audience | Content |
|---|---|---|
| Portfolio | Brokerage owners | Funded volume trends, pipeline stage breakdown (lead → funded → declined), period-over-period KPI deltas. |
| Industry | Growth-focused principals | Bubble chart mapping submission volume vs pull-through by industry vertical. Identifies underinvested verticals where your close rate is high but submission volume is low. |
| Lender Intel | Submission managers | Per-lender relationship health scores with time-decay opacity encoding, average days-to-offer, and pull-through trends. |
| AI Predictions | All roles | KPI row (approval rate, prediction accuracy, avg days to offer, decline rate) + approval trend, decline reasons, and per-lender pull-through charts. Progressive unlock only. |
Progressive intelligence unlock
New ISOs do not have access to the AI Predictions view at account creation. The system enforces a minimum data threshold before surfacing accuracy metrics. This prevents underpowered statistics from undermining trust in the scoring model.
10+
Recorded funded or declined outcomes
3+
Qualified lenders with buy-box data
30+
Days of historical data on the platform
Why thresholds matter
An approval rate derived from 4 outcomes is not a useful signal. YieldStream shows ISOs a data-accumulation progress indicator — not a locked or hidden state — so you always know exactly what data is needed to unlock the full predictions view.Intelligence
Outcome Learning Loop
Every funded and declined deal feeds back into the scoring model. This is the data flywheel that makes YieldStream more accurate over time — and creates compounding switching cost as your outcome history grows.
What happens when a submission is marked Funded
| Event | System response |
|---|---|
| Deal funded | Relationship score for that lender strengthens. Point-in-time snapshot (merchant, bank intelligence, predictions) written to funding_outcomes. Renewal tracking begins — estimated payoff and 50% paydown dates calculated. |
| Renewal alert window reached | Daily cron at 08:00 identifies funded deals within 60 days of estimated 50% paydown. Notification dispatched to all org members. renewal_alert_sent flag prevents duplicate alerts. |
What happens when a submission is marked Declined
| Decline category | Score adjustment | Duration |
|---|---|---|
| Max exposure | Significant penalty | 30 days — lender at portfolio capacity |
| Industry restriction | Moderate penalty | 30 days — likely deal-specific |
| Credit quality | Minor penalty | 30 days — criteria may have tightened |
| Stacking / position limit | Moderate penalty | 30 days — re-evaluate after paydown |
Penalties are org-scoped — a decline at your ISO does not affect another ISO's relationship score with that lender. Multiple declines from the same lender compound within the penalty window. Penalties expire automatically via a nightly SQL function.
The compounding advantage
An ISO with 6 months of recorded outcomes will have materially better predictions than a new user. This creates both a retention mechanic and a genuine data moat — your historical outcome record is not portable to any other platform.Infrastructure
Security & Data Isolation
Security and data isolation are foundational architecture decisions in YieldStream, not features added after the fact. The primary isolation mechanism is PostgreSQL Row-Level Security enforced at the database level — not application-level filtering.
Multi-tenant isolation
Every table containing org-scoped data has RLS policies enforced at the database level across 18+ tables. This means even if application code contained a bug, the database itself would reject any query attempting to return another organization's data.
Zero-trust data architecture
Traditional platforms rely on application code to add WHERE org_id = X to every query. If a developer omits it once, data leaks. YieldStream's RLS policies make that impossible — the database rejects unauthorized queries regardless of what the application requests.Document vault security
| Control | Specification |
|---|---|
| Encryption at rest | AES-256 via Supabase infrastructure-level encryption on all storage buckets. |
| Org-scoped policies | Storage policies enforced at the storage layer, independent of database RLS. Cross-tenant file access is blocked at two separate enforcement points. |
| Signed URLs | Document access requires a short-lived signed URL with a 15-minute expiry. Permanent or guessable URLs are never generated. |
| File validation | Allowed types: PDF, JPG, PNG, XLS/XLSX, DOC/DOCX. Enforced client-side and server-side. Executable files rejected at both layers. |
| Merchant upload links | Token-gated, single-use, 48-hour expiry. Merchants can upload without a platform account. |
| Audit trail | Every upload, view, and deletion written to the append-only audit_logs table. Cannot be modified or deleted by any user role. |
Authentication controls
| Control | Specification |
|---|---|
| Password policy | Minimum 12 characters. Uppercase, lowercase, numeric, and special characters required. |
| 2FA | TOTP-based (Google Authenticator, Authy, any RFC 6238-compatible app). |
| Brute-force protection | Account locked for 15 minutes after 5 failed attempts within 10 minutes. |
| Session timeout | Sessions expire after 7 days of inactivity. |
| Security headers | HSTS (HTTPS enforcement), X-Frame-Options, X-Content-Type-Options, Permissions-Policy. |
Data minimization for AI
When YieldStream sends data to external AI services, only normalized markdown representations of financial statements are transmitted. Raw PDFs, account numbers, SSNs, and EINs are never sent to third-party AI providers. The Gemini API receives only the structured text output from LlamaParse — not the original document.
Infrastructure
Role-Based Access Control
YieldStream enforces a three-tier permission model across all API routes and server actions. There are no unprotected privileged endpoints — every mutation is gated by the secureApiHandler middleware or requireRole server-action utility.
Permission matrix
| Action | Owner | Admin | Rep |
|---|---|---|---|
| Change organization name | ● | ● | ● |
| Delete org data (GDPR) | ● | ● | ● |
| Export compliance data | ● | ● | ● |
| Invite team members | ● | ● | ● |
| Manage lender buy-boxes | ● | ● | ● |
| Bulk CSV import | ● | ● | ● |
| Change submission status | ● | ● | ● |
| Create merchants | ● | ● | ● |
| Upload documents | ● | ● | ● |
| View AI predictions | ● | ● | ● |
Cross-tenant protection
Lender relationship scores, pull-through rates, and prediction accuracy data are derived exclusively from the authenticated session's org_id — never from user-supplied parameters. Cross-tenant failures return HTTP 404 rather than 403, preventing resource-existence enumeration by external actors.
Reference
Pricing
YieldStream is a flat monthly subscription — no per-seat pricing, no submission limits, no hidden overages. The 14-day trial includes full platform access with card on file; no charge until the trial period ends.
Recommended
Founder
$497/month
Team seatsUnlimited
AI credits / month50
Trial period14 days
BillingStripe, auto-charge
Pro
$697/month
Team seatsUp to 10
AI credits / month150
Trial period14 days
BillingStripe, auto-charge
AI credit system
AI credits govern consumption of the underwriting pipeline — specifically bank statement enrichment (OCR + Gemini analysis) and lender prediction generation. One credit is consumed per bank statement analysis cycle. Prediction re-runs against cached results do not consume credits.
Credit policy
Unused AI credits do not roll over between billing periods. Credits refresh on the monthly billing anniversary. High-volume ISOs processing above the included credit allotment should contact support to discuss an Enterprise arrangement.Reference
Glossary
Definitions for YieldStream-specific terminology used throughout this documentation and visible in the platform interface.
ADB — Average Daily Balance
Time-weighted mean of a merchant's daily closing bank balance. The primary liquidity metric used in lender attribute scoring.
Attribute Score (Layer C)
Rule-based component of the composite score. Measures merchant risk profile against lender buy-box criteria. Weight: 25%.
Buy-Box
A lender's published underwriting criteria: minimum revenue, minimum FICO, maximum positions, restricted industries and states.
Composite Score
The 0–100 output of the three-layer scoring model for a specific merchant-lender pairing. Reflects both market signals and your ISO's relationship history.
Digital Head of Submissions
YieldStream's positioning concept. The platform functions as an institutional-grade submissions function, replacing ad hoc lender routing with systematic, data-driven recommendations.
Global Pool (Layer A)
Cross-organization, anonymized lender performance signal. Computes time-decay weighted approval rates across all YieldStream ISOs without exposing any individual ISO's data. Weight: 25%.
Ghosting Rate
Ratio of submissions with no lender response within the expected window to total submissions, over a rolling 30-day period.
ISO — Independent Sales Organization
The primary YieldStream customer. An ISO is a licensed MCA broker organization that matches merchants with MCA lenders and earns commission on funded deals.
MCA — Merchant Cash Advance
A form of small business financing where a lender purchases a portion of future receivables at a discount, repaid via daily or weekly fixed debits.
NSF — Non-Sufficient Funds
A bank event indicating a payment was attempted with an insufficient balance. The strongest single negative signal in MCA underwriting.
Outcome Learning Loop
The feedback mechanism feeding every funded and declined deal back into the scoring model. The primary driver of model improvement over time.
Pull-Through Rate
Funded deals ÷ total deals submitted to a specific lender. An ISO's most important metric of lender relationship quality.
Relationship Score (Layer B)
ISO-specific, time-decay weighted pull-through history with each lender. Weight: 50%. Never shared with competing ISOs.
Stacking
Having multiple simultaneous MCA advances from different lenders. Detected from bank statement debit patterns and expressed as stacking_burden_pct.
Time-Decay Weighting
Mechanism that reduces the influence of older outcomes on current scores. Data older than 180 days contributes only 5% weight, preventing stale signals from distorting recommendations.
Underwriter's Note
A human-readable sentence generated by Gemini 1.5 Flash explaining the structural reason for a lender recommendation. Provides broker-facing transparency for AI-driven scores.