Skip to main content

Monorepo design

This document outlines the core architecture principles of the Payofy codebase.

Five system boundaries​

  1. Only @payofy/kurv communicates with Kurv. Server modules interact with an abstract payment rail interface. If upstream gateway details change, changes stay confined to one package.
  2. Only the ledger module writes money state. Payments, refunds, payouts, and residuals write journal postings to the ledger. Current balances are always computed from ledger rows.
  3. Contracts first. Developers define schemas in @payofy/contracts before writing endpoints. Both the OpenAPI specification and SDK types derive directly from these schemas.
  4. Packages never import apps. SDKs never import server code. Turborepo build graphs and ESLint enforce this separation in continuous integration.
  5. Every database query runs with tenant context. The server assigns the tenant context per transaction, and PostgreSQL row-level security isolates tenant records.

Project segregation​

Each deployable component has its own dedicated folder:

  • apps/api: Runs payofy-api on Fastify.
  • apps/worker: Runs payofy-worker on BullMQ.
  • packages/core: Houses shared backend domain modules and services.
  • examples/budofy-integration/backend: Demonstrates server-to-server integration.
  • examples/budofy-integration/frontend: Demonstrates embedded client widgets.

Build order​

Development follows an incremental path where each step produces a verifiable milestone:

  1. Skeleton: config, ui, contracts, db, CI, and dev infrastructure.
  2. Kurv adapter: kurv and testing packages with sandbox verification.
  3. Money core: tenants, merchants, customers, payments, webhooks-in, and ledger modules.
  4. SDKs: node, js, react, and budofy-integration example.
  5. Recurring billing: billing, dunning, webhooks-out, and notifications on the worker.
  6. Operations: payouts, reconciliation, residuals, reports, audit, and payofy-admin.
  7. Budofy pilot: run live traffic for an initial school.
  8. Phase 2: Tap to Pay mobile bridge, partner portal, and documentation site.