Fondo Reference Architecture

Overview

Reference architecture for a startup's financial operations with Fondo at the center, connecting payroll, banking, payments, and internal reporting.

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Data Sources                         │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│  Mercury │  Gusto   │  Stripe  │  Brex    │  AWS/GCP    │
│  Banking │  Payroll │  Revenue │  Expense │  Cloud      │
├──────────┴──────────┴──────────┴──────────┴─────────────┤
│              Plaid / OAuth Connections                    │
├─────────────────────────────────────────────────────────┤
│                                                          │
│                   FONDO PLATFORM                         │
│  ┌──────────┐  ┌──────────┐  ┌────────────────┐        │
│  │ Monthly  │  │ Tax      │  │ R&D Tax Credit │        │
│  │ Close    │  │ Filing   │  │ Study (6765)   │        │
│  └──────────┘  └──────────┘  └────────────────┘        │
│                                                          │
├─────────────────────────────────────────────────────────┤
│                     Outputs                              │
├──────────┬──────────┬──────────┬────────────────────────┤
│  P&L     │  Balance │  Cash    │  R&D Credit            │
│  Report  │  Sheet   │  Flow    │  Certificate           │
├──────────┴──────────┴──────────┴────────────────────────┤
│              Internal Dashboard (optional)                │
│  Revenue metrics │ Burn rate │ Runway │ Board deck       │
└─────────────────────────────────────────────────────────┘

Recommended Stack

Data Flow

1. Transactions flow from banks/cards/payroll into Fondo via Plaid/OAuth
2. Fondo CPA team categorizes and reconciles monthly
3. Financial statements generated and delivered to Dashboard
4. R&D credit study prepared annually from same data
5. Tax returns filed using reconcile

Fondo SDK Patterns

Overview

Production-ready patterns for integrating with Fondo tax and accounting data. Fondo is a managed bookkeeping platform that syncs through QuickBooks Online and payroll providers. Integration uses the FONDOAPIKEY-authenticated REST endpoints for exports, the QuickBooks Online API for GL data, and structured CSV parsing with Zod validation for bulk imports.

Singleton Client

const FONDO_BASE = 'https://api.fondo.com/v1';
let _client: FondoClient | null = null;
export function getClient(): FondoClient {
  if (!_client) {
    const apiKey = process.env.FONDO_API_KEY;
    if (!apiKey) throw new Error('FONDO_API_KEY must be set — get it from your Fondo dashboard');
    _client = new FondoClient(apiKey);
  }
  return _client;
}
class FondoClient {
  private headers: Record<string, string>;
  constructor(apiKey: string) { this.headers = { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' }; }
  async getTransactions(start: string, end: string): Promise<FondoTransaction[]> {
    const res = await fetch(`${FONDO_BASE}/transactions?start=${start}&end=${end}`, { headers: this.headers });
    if (!res.ok) throw new FondoError(res.status, await res.text()); return res.json();
  }
  async getAccounts(): Promise<FondoAccount[]> {
    const res = await fetch(`${FONDO_BASE}/accounts`, { headers: this.headers });
    if (!res.ok) throw new FondoError(res.status, await res.text()); return res.json();
  }
}

Error Wrapper

export class FondoError extends Error {
  constructor(public status: number, message: string) { super(message); this.name = 'FondoError'; }
}
export async function safeCall<T>(operation: string, fn: () => Promise<T>): Promise<T> {
  try { return await fn(); }
  catch (err: any) {
    if (err instanceof FondoError && err.status === 429) { await new Promise(r => setTimeout(r, 5000)); return fn(); }
    if (err instanceof FondoError && err.status === 401) throw new FondoError(401, 'Invalid FONDO_API_KEY');
    throw new FondoError(err.status ?? 0, `${operation} failed: ${err.message}`);
  }
}

Request Builder

class FondoQuery {
  private params: Record<string, string> = {};
  dateRange(start: string, end: string) { this.params.start = start; this.params.end = end; return this; }
  category(cat: string) { this.params.category = cat; return this; }
  accountId(id: string) { this.params.account_id = id; return this; }
  rndOnly() { this.params.is_rnd = 'true'; return this; }
  limit(n: number) { this.params.limit = String(n); return this; }
  build() { return new URLSearchParams(this.params).toString(); }
}
// Usage: new FondoQuery().dateRange('2025-01-01','2025-03-

Fondo Upgrade & Migration

Overview

Migrate to Fondo from DIY bookkeeping, other accounting firms, or platforms like Pilot, Bench, or Kruze. Fondo handles the historical data import.

Migration Scenarios

Instructions

Step 1: Prepare Migration Data

Gather from your current provider:

• [ ] QuickBooks Online backup (or GL export as CSV)
• [ ] Bank statements (last 2 years for R&D credit)
• [ ] Payroll records (all W-2 and 1099 data)
• [ ] Prior tax returns (1120, state returns)
• [ ] R&D credit studies (Form 6765 if previously claimed)
• [ ] Cap table and equity event history

Step 2: Onboard with Fondo

1. Sign up at fondo.com and select plan
2. Upload historical data via Dashboard > Migration
3. Connect active integrations (bank, payroll, expense)
4. Fondo CPA team reviews and reconciles historical data
5. First month close produces baseline reports

Step 3: Transition from Previous Accountant

Timeline:
  Week 1: Sign Fondo engagement letter, connect integrations
  Week 2: Previous accountant provides data export and handoff notes
  Week 3: Fondo reviews historical data, catches up any gaps
  Week 4: First Fondo-managed month close complete

Plan Upgrades

Resources

• Fondo Pricing
• Fondo TaxPass

Next Steps

For CI integration, see fondo-ci-integration.

Fondo Webhooks & Events

Overview

Fondo itself does not send webhooks. Instead, build event-driven workflows using webhooks from the same providers Fondo connects to: Stripe (revenue), Gusto (payroll), Plaid (bank transactions), and Mercury (banking).

Provider Webhooks

Instructions

Stripe Revenue Webhook

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_API_KEY!);

app.post('/webhooks/stripe', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['stripe-signature'] as string;
  const event = stripe.webhooks.constructEvent(
    req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );

  switch (event.type) {
    case 'charge.succeeded':
      const amount = (event.data.object as Stripe.Charge).amount / 100;
      console.log(`Revenue: $${amount}`);
      // Update internal dashboard
      break;
    case 'invoice.paid':
      // MRR tracking
      break;
  }
  res.sendStatus(200);
});

Gusto Payroll Webhook

// Gusto sends webhooks when payroll is processed
app.post('/webhooks/gusto', express.json(), async (req, res) => {
  const { event_type, data } = req.body;

  if (event_type === 'payroll.processed') {
    const totalPayroll = data.totals.gross_pay;
    console.log(`Payroll processed: $${totalPayroll}`);
    // Alert if significantly different from budget
    if (totalPayroll > monthlyPayrollBudget * 1.1) {
      await sendAlert(`Payroll exceeded budget by ${((totalPayroll / monthlyPayrollBudget - 1) * 100).toFixed(0)}%`);
    }
  }
  res.sendStatus(200);
});

Resources

• Stripe Webhooks
• Gusto Webhooks
• Plaid Webhooks

Next Steps

For performance optimization, see fondo-performance-tuning.