Architecture

Monorepo

Furlpay is managed as a single, unified codebase with Turborepo and npm workspaces. One repository guarantees consistent types across the web app, desktop wrapper, browser extension, published SDKs, and the MCP server — every surface builds against the same shared domain logic.

Dependency graph

Compilation boundaries flow in one direction. Product surfaces and distributed clients depend on the shared foundation; the foundation depends on nothing above it. This keeps domain rules (ledger invariants, compliance routing, crypto schemas) defined exactly once.

Product surfaces — apps/user-facing

webNext.js + API

desktopTauri

extensionMV3

Distribution — sdks/ · mcp/published clients & agent tooling

@furlpay/node

@furlpay/cli

@furlpay/elements

mcp-server

Shared foundation — packages/single source of truth

types

ledger

security

compliance

account-kit

Everything above depends on the shared foundation below — never the reverse.

Directory layout

bash

.
├── apps/
│   ├── web         # Next.js app + serverless API (auth, x402, Solana Actions)
│   ├── desktop     # Tauri shell (Windows .msi / macOS .dmg / Linux .deb)
│   └── extension   # MV3 browser extension (checkout + autofill)
├── packages/
│   ├── types       # shared zod schemas & TS types (source of truth)
│   ├── ledger      # immutable double-entry ledger
│   ├── security    # 2-of-2 MPC, TOTP MFA, device/behavioural risk
│   ├── compliance  # KYC tiers, jurisdiction resolver, FATF Travel Rule
│   ├── account-kit # Safe / ERC-4337 accounts, paymaster, escrow bindings
│   ├── elements    # embeddable React checkout components
│   ├── cli         # stripe-cli-style developer CLI
│   └── ui          # design system, icons, brand assets
├── sdks/node       # @furlpay/node — official server SDK
├── mcp/            # Model Context Protocol server for AI agents
├── turbo.json      # task pipeline: build, lint, dev
└── package.json    # npm workspaces: apps/* packages/* sdks/node mcp

Applications (`apps/`)

webNext.js 14

The primary platform and backend service layer. Serves the responsive dashboard, exposes serverless REST endpoints, handles third-party webhooks (Stripe, Wise, Persona, Marqeta), and hosts the agentic x402 and Solana Actions surfaces.

desktopTauri (Rust)

A native desktop client that bundles the compiled web assets into a lightweight binary for Windows (.msi), macOS (.dmg), and Linux (.deb) with OS-keychain secure storage.

extensionManifest V3

A browser extension that autofills card credentials and executes checkout directly from the toolbar. Open-sourced so the credential-injection path can be audited.

Shared packages (`packages/`)

Shared modules are isolated with strict compilation boundaries so nothing leaks across concerns:

@furlpay/types

Shared TypeScript interfaces and zod schemas — the single source of truth for domain models, imported everywhere.

@furlpay/ledger

An immutable, double-entry ledger: balanced postings, derived balances, and reversals used to audit every financial movement.

@furlpay/security

The cryptographic layer — 2-of-2 MPC key shares, RFC 6238 TOTP MFA, step-up gating, and device/biometric risk scoring.

@furlpay/compliance

The geolocation and routing engine enforcing MiCA/GENIUS stablecoin rules, KYC tiers, and the FATF Travel Rule.

@furlpay/account-kit

Wrappers for Safe smart-contract accounts, ERC-4337 bundlers, gas-sponsorship paymasters, and time-locked escrow.

@furlpay/ui

The design system — visual tokens, animations, SVG brand assets, and shared primitives.

Build pipeline (`turbo.json`)

Turborepo compiles workspaces in parallel and caches task outputs. The ^build dependency means a package always builds before the apps that consume it (topological order); the .next/cache exclusion keeps the framework cache out of the artifact cache;dev is long-running and never cached.

json

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "stream",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "dev": { "cache": false, "persistent": true },
    "lint": {}
  }
}

bash

turbo run build      # topological, content-hashed cache
turbo run lint       # eslint across all workspaces
turbo run dev        # web + desktop + extension in parallel

Public surface

The SDKs, CLI, Elements, Account Kit, MCP server, and extension are mirrored to public repositories under github.com/FurlPay (MIT). The core application, database schemas, HSM signing policy, and fraud models stay private.

Why a monorepo

A single repo means one type-check gate covers the API, its SDKs, and its UI at once — a change to a zod schema in @furlpay/types fails the build everywhere it's misused, before it can ship. That guarantee is what makes shared financial logic safe to refactor.

← Previous

Quickstart

API Routes