Exchequer Platform

Real-time double-entry ledger systems for PSPs, Marketplaces, and anyone who needs to move and manage money at scale.

Why Exchequer?

• Kick-start your ledger — Get a production-ready ledger system running in minutes, not months
• Simple by design — Clean APIs, predictable patterns, no magic
• Real-time balances — Know exactly where your money is, right now
• By devs, for devs — Built with the developer experience you wish every financial tool had

Quick Start

# Prerequisites: Node.js 24, pnpm 11.18+, Docker
pnpm install
cp apps/api/.env.example apps/api/.env
pnpm run docker:up
pnpm run dev

API runs at http://localhost:3000 • Web dashboard at http://localhost:5173

What's Inside

Running Applications

# Start all apps
pnpm run dev
# Start specific app
pnpm run dev:api      # API only
pnpm run dev:web      # Web only
pnpm run dev:docs     # Docs only

Testing

Tests run through the repository's Vitest scripts.

Prerequisites: PostgreSQL and Valkey must be running for API tests.

# Run all tests across all apps (auto-starts PostgreSQL and Valkey, uses Vitest)
pnpm run test
# Test specific app (uses Vitest)
pnpm --filter=@exchequerio/api test    # Requires PostgreSQL and Valkey
pnpm --filter=@exchequerio/web test
# Start PostgreSQL and Valkey manually first (optional)
pnpm run docker:up
# Watch mode (from specific app directory)
pnpm --filter=@exchequerio/api test:watch

Performance Benchmarks

The API includes comprehensive benchmarks for transaction creation under various contention scenarios. Run benchmarks with:

cd apps/api
pnpm run bench

Benchmark Results (M1 Max, 32GB RAM)

Transaction creation throughput and latency across different contention levels:

Key Insights:

• Throughput degradation (high vs low contention): 52.25%
• P97.5 latency increase (high vs low contention): 10.92%
• Optimistic locking with exponential backoff retry (5 attempts, 50ms-1s jitter)
• Zero errors across all contention scenarios
• Hot account patterns demonstrate realistic production workloads

Test Configuration:

• Duration: 10 seconds per scenario
• Connections: 10 concurrent
• Pipelining: 1 request per connection
• Database: PostgreSQL 17 (local Docker)

Code Quality

# Run all quality checks (format + lint + types + benchmark collection)
pnpm run check
# Individual checks
pnpm run format         # Format all apps with Oxfmt
pnpm run format:check   # Check formatting without writing
pnpm run lint           # Lint all apps with Oxlint
pnpm run types          # Type check all apps with TypeScript 7

Build

# Build all apps for production
pnpm run build
# Build specific app
pnpm --filter=@exchequerio/web build
pnpm --filter=@exchequerio/docs build

Local Infrastructure

# Start PostgreSQL and Valkey
pnpm run docker:up
# Stop PostgreSQL and Valkey
pnpm run docker:down
# View PostgreSQL logs
pnpm run docker:logs

CI/CD

# Run complete CI pipeline
pnpm run ci
# Equivalent to: docker:up + build + format check + lint + types + benchmark collection + test

Documentation

• Getting Started — Full development guide
• API Architecture — Backend design patterns and principles
• API Guide — Backend development
• Web Guide — Frontend development

Contributing

pnpm run check   # Check formatting, lint, and types
pnpm run test    # Run all tests (requires Docker)

See AGENTS.md for the full development workflow.

License

MIT License - see LICENSE for details.