Server modules

Backend business logic resides in @payofy/core under packages/core/src/modules/. Each module manages its domain logic and database tables. Modules communicate with each other through TypeScript service interfaces rather than raw table access.

Two execution applications

• apps/api: Starts the HTTP server on Fastify. It handles external requests at /v1 and receives incoming Kurv webhooks.
• apps/worker: Starts worker processes without an HTTP listener. It consumes BullMQ queues and handles scheduled tasks.

Module index

• tenants: Stores registered tenant applications, API credentials, and webhook endpoints.
• merchants: Manages school accounts, fee schedules, and Kurv merchant IDs.
• onboarding: Coordinates merchant application submission and document collection.
• customers: Stores payer profiles and vaulted payment method tokens.
• payments: Coordinates one-off card transactions, voids, and authorization states.
• billing: Manages recurring subscription plans, proration, and invoices.
• dunning: Controls retry intervals and payment recovery routines.
• refunds-disputes: Handles chargebacks, dispute evidence, and customer refunds.
• ledger: Enforces balanced double-entry accounting. It is the sole authority for monetary state.
• payouts: Tracks merchant deposit batches and settlement matching.
• reconciliation: Matches daily Kurv settlement reports against internal ledger records.
• residuals: Imports monthly Kurv residual data and calculates revenue.
• webhooks-in: Validates Kurv webhook signatures and routes events to target modules.
• webhooks-out: Delivers signed event notifications to Budofy and Voiceyfy endpoints.
• reports: Computes summary metrics for dashboards and financial reviews.
• notifications: Sends receipts and payment reminders via email and SMS.
• audit: Maintains an append-only log of admin actions and sensitive API calls.
• partners: Handles revenue share calculations and partner management for phase 2.