Fondo Reference Architecture

Overview

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

Prerequisites

• A data-flow inventory, authorized business purpose, system owners, access/retention policy, and professional-review boundary.
• Separate scoped identities for data sources, processing, storage, reporting, and support, plus synthetic integration fixtures.

Instructions

1. Enforce field allowlists, access checks, encryption, and retention requirements at every financial-data boundary.
2. Keep financial/tax conclusions under the designated finance professional’s review; integrations may prepare evidence but not replace that review.
3. Use idempotent queues, redacted telemetry, staged promotion, and a correction/rollback path for each downstream consumer.

Output

Maintain an architecture record describing sources, trust boundaries, approved destinations, access/retention controls, owners, professional-review points, and recovery mechanisms. Do not include finance data or secrets.

Error Handling

• Quarantine unknown fields, unapproved destinations, and reconciliation mismatches for finance review.
• Disable unsafe consumers and preserve only redacted evidence during recovery.
• Restore the prior mapping/configuration before replaying any financial workflow.

Examples

Route a fictional aggregate expense event through an approved staging pipeline, deny an unapproved reporting consumer, and verify a duplicate event is suppressed. Record only the opaque event ID and aggregate outcome.

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    │  Ce

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 FONDO_API_KEY-authenticated REST endpoints for exports, the QuickBooks Online API for GL data, and structured CSV parsing with Zod validation for bulk imports.

Prerequisites

• Scoped credentials, authorized source/destination mappings, synthetic fixtures, and a designated finance-data owner.
• Schema validation, idempotent import design, redacted diagnostics, and professional review for financial conclusions.

Instructions

1. Validate source schema and field allowlists before parsing or forwarding data.
2. Use opaque operation IDs, bounded retries, and reconciliation gates to prevent duplicate or partial imports.
3. Quarantine unknown fields and mismatches for finance review rather than broadening data access.

Output

Produce a client-validation receipt with contract/fixture version, aggregate schema and reconciliation outcome, operation ID, owner, and redacted failure reference. Do not log transactions, accounts, tax/payroll data, or tokens.

Examples

Import a fictional aggregate ledger fixture into staging, repeat it under the same operation ID, and verify duplicate suppression. Introduce an unexpected field and confirm the parser blocks it for review without revealing record contents.

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 safe

Fondo Security Basics

Prerequisites

A security owner, scoped secret manager, financial-data access policy, review cadence, and synthetic fixtures.

Instructions

Use least-privilege credentials per environment; verify signed events and idempotency; restrict financial and tax data to approved systems; redact diagnostics; rotate credentials on suspected exposure.

Output

Maintain a security receipt with scope, secret reference, access-review date, control result, owner, and redacted incident state. Do not include financial data or secrets.

Examples

Verify a fictional signed event is processed once, an invalid signature is rejected without payload logging, and revoking a staging credential blocks future requests.

Overview

Fondo handles startup tax preparation, bookkeeping, and R&D tax credits containing SSNs, EINs, bank account details, revenue figures, and complete tax returns. A breach exposes founder personal tax data, company financials, and IRS filing details. Protect OAuth connections to banking/payroll systems, exported financial documents, and team access controls with the same rigor as a CPA firm.

API Key Management

function createFondoClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.FONDO_API_KEY;
  if (!apiKey) {
    throw new Error("Missing FONDO_API_KEY — store in secrets manager, never in code");
  }
  // Fondo keys access tax returns and SSN/EIN data — treat as highest sensitivity
  console.log("Fondo client initialized (key suffix:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.fondo.com/v1" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyFondoWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-fondo-signature"] as string;
  const secret = process.env.FONDO_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const TaxFilingSchema = z.object({
  entity_id: z.string().uuid(),
  tax_year: z.number().int().min(2015).max(2030),
  filing_type: z.enum(["1120", "1120S", "1065", "941", "R&D_credit"]),
  ein: z.string().regex(/^\d{2}-\d{7}$/),
  revenue: z.number().nonnegative(),
  status: z.enum(["draft", "review", "filed", "amended"]),
});

function val

Fondo Upgrade & Migration

Prerequisites

Current provider change information, approved finance-data inventory, synthetic staging fixtures, a finance owner, and a tested correction/rollback path.

Output

Record versions and mappings reviewed, aggregate validation/reconciliation result, reviewer approval, and rollback state. Exclude financial records and credentials.

Error Handling

Stop promotion on schema, access, reconciliation, retention, or professional-review gaps; restore the prior mapping and quarantine opaque failures for review.

Examples

Compare old and proposed mappings using fictional aggregate data, deliberately introduce an unknown field, and verify the change remains pending until the finance reviewer approves it.

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

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 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 / monthlyPa