Fondo Local Dev Loop

Overview

Local development workflow for Fondo startup tax and bookkeeping integration. Provides a fast feedback loop using CSV exports and mock financial data so you can build dashboards, R&D credit calculators, and burn-rate tools without waiting on live Fondo reports. Toggle between mock mode for rapid iteration and real export parsing for production validation.

Prerequisites

• Fictional fixtures only, local directories excluded from version control, and a named finance owner for any approved export validation.
• Secrets supplied from an approved manager; local development must not access production financial data by default.

Instructions

1. Keep mock mode enabled for normal development and generate only synthetic account, vendor, and transaction values.
2. Validate schema and field mappings against an approved, access-controlled sample before any live workflow change.
3. Redact logs, avoid committing exports, and delete temporary local artifacts through the defined retention process.

Output

Produce a local validation receipt with fixture version, schema result, approved mapping, owner, and redacted failure reference. Do not include transactions, account details, payroll/tax data, or credentials.

Examples

Run a calculator against fictional monthly totals and confirm tests pass with network access disabled. Inspect the fixture for real names, account identifiers, or exports, then remove test artifacts after the schema validation is complete.

Environment Setup

cp .env.example .env
# Set your credentials:
# FONDO_API_KEY=fondo_xxxxxxxxxxxx
# FONDO_EXPORT_DIR=./exports
# MOCK_MODE=true
npm install express csv-parse dotenv tsx typescript @types/node
npm install -D vitest supertest
mkdir -p exports

Dev Server

// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (MOCK) {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
} else {
  const { mountExportRoutes } = require("./export-parser");
  mountExportRoutes(app, process.env.FONDO_EXPORT_DIR!);
}
app.listen(3002, () => console.log(`Fondo dev server on :3002 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic startup financial data
export function mountMockRoutes(app: any) {
  app.get("/api/transactions", (_req: any, res: any) => res.json([
    { date: "2025-03-01", description: "AWS Infrastructure", amount: -4200, category: "Cloud Hosting", account: "Operating", isRnD: true },
    { date: "2025-03-05", description: "Engineer Salary", amount: -12500, category: "Payroll", account: "Operating", isRnD: true },
    { date: "2025-03-10", description: "Stripe Revenue", amount: 8750, category: "Revenue", account: "Income", isRnD: false },
  ]));
  app.get("/api/reports/pnl", (_req: any, res: any) => res.json({
    period: "2025-Q1", revenue: 26250, expenses: 50100, netIncome: -23850,
  }));
  app.get("/api/reports/rnd-summary", (_req: any, res: any) => res.json({
    totalQualified: 38500, categories: ["Cloud Hosting", "Payroll", "Software Tools"],
  }));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
MOCK_MODE=false npm run test:integration  # Test against real Fondo CSV exports

Debug Tips

• Place sample CSVs in exports/ to test parsing without Fondo dashboard access
• Validate CSV column headers match Fondo's export format (Date, Description, Amount, Category, Account, R&D Qualified)
• Use --verbose flag with the parser to log skipped rows and type coercion warnings
• Check for locale-specific number formats ($1,234.56 vs 1234.56) in Amount column

Error Handling

Issue	Cause	Fix
CSV parse error	Malformed export file	Re-export from Fondo with UTF-8 encoding
NaN in amount	Currency symbols in Amount column	Strip $ and , before parseFloat
Missing R&D column	Older export format	Use Fondo's updated report template
ENOENT exports/	Export directory missing	Run mkdir -p exports
Empty dataset	Date range has no transactions	Widen the date range in Fondo dashboard

Resources

• Fondo Dashboard
• csv-parse docs

Next Steps

See fondo-debug-bundle.