TMX Collateral — Backend API

NestJS REST API that powers the TMX Collateral AR financing platform. Manages the full accounts receivable lifecycle, settlement configuration, buyer email flows, and on-chain USDC repayment recording.

Introduction

The backend exposes a versioned REST API (/api/v1/) consumed by both the Financer and Merchant portals, plus a set of public endpoints (/api/public/) for buyer-facing flows that require no authentication.

It uses Prisma as the ORM against a PostgreSQL database, Resend for transactional email, and integrates with the Polygon network for USDC settlement tracking.

Features

• Full AR lifecycle management (26 stages, event-sourced history)
• Buyer email confirmation via one-time token
• Buyer payment link generation (USDC on Polygon via /pay/:token on the frontend)
• Settlement config — controlled payment routing or smart-contract escrow
• Financing disbursement and repayment recording
• Swagger API documentation at /api/v1/docs
• Docker support for local and production deployments

Installation

Prerequisites

• Node.js (v22 or higher)
• pnpm (recommended package manager)
• PostgreSQL (v12 or higher)
• Git

Setup Instructions

1. Clone the repository

git clone <repository-url>
cd tmx-collateral/backend

2. Install dependencies

pnpm install

3. Database setup

pnpm prisma generate
pnpm prisma migrate dev
pnpm prisma db seed        # seeds demo financer + merchant accounts

Configuration

Environment Setup

1. Copy the environment template

cp database.env.example .env

2. Fill in the environment variables

Variable	Required	Description
DATABASE_URL	✅	PostgreSQL connection string
APP_URL	✅	Backend base URL (e.g. http://localhost:8000)
FRONTEND_URL	✅	Frontend URL — used in buyer payment email links
RESEND_API_KEY	✅	Resend API key for transactional email
FROM_EMAIL	✅	Sender email address
FINGERPRINT	✅	HMAC secret for AR fingerprinting (openssl rand -base64 32)

Usage

Development Commands

Building

# Build the application
pnpm build

# Build and watch for changes
pnpm start:dev

Running the Application

# Development mode with hot reload
pnpm start:dev

# Debug mode
pnpm start:debug

# Production mode
pnpm start:prod

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:cov

# Run end-to-end tests
pnpm test:e2e

# Debug tests
pnpm test:debug

Database Operations

# Generate Prisma client
pnpm prisma generate

# Run database migrations
pnpm prisma migrate dev

# Reset database
pnpm prisma migrate reset

# Open Prisma Studio (database GUI)
pnpm prisma studio

# Check migration status
pnpm prisma migrate status

Code Quality

# Format code
pnpm format

# Lint code
pnpm lint

API Documentation

Once the application is running, the interactive Swagger UI is available at:

• Swagger UI: http://localhost:8000/api/v1/docs

Key endpoint groups:

Prefix	Description
GET/POST /api/v1/ar	AR lifecycle — create, list, advance stages
POST /api/v1/ar/:arId/approve-and-create-route	Approve financing + generate buyer payment link
POST /api/v1/ar/:arId/send-buyer-confirmation	Email buyer invoice confirmation
GET /api/public/pay/:token	Buyer payment details (no auth)
POST /api/public/pay/:token/submit	Record USDC repayment (no auth)
GET /api/public/buyer-confirm/:token	Buyer invoice confirmation page (no auth)

Testing

The project includes comprehensive testing with Jest:

Test Structure

• Unit Tests: Individual component testing (services, controllers)
• Integration Tests: Module integration testing
• E2E Tests: End-to-end application testing
• Coverage Reports: Detailed coverage analysis

Test Files

• *.spec.ts - Unit and integration tests
• *.e2e-spec.ts - End-to-end tests

Coverage Exclusions

The following files are excluded from coverage reports:

• Module files (.module.ts)
• DTOs (.dto.ts)
• Main entry point (main.ts)
• Prisma service
• Test files themselves
• Utility files

Development Tools

• NestJS: Backend framework with TypeScript support
• Prisma: Modern database toolkit and ORM
• Jest: Testing framework with coverage reporting
• ESLint: Code linting and quality enforcement
• Prettier: Code formatting
• Swagger: API documentation generation
• TypeScript: Type-safe development
• VS Code: Recommended IDE with extensions

Recommended VS Code Extensions

• NestJS Files
• Prisma
• TypeScript Importer
• ESLint
• Prettier
• REST Client

Development Guidelines

• Follow TypeScript and ESLint rules
• Write comprehensive tests for new features
• Update documentation as needed
• Use conventional commit messages
• Maintain test coverage above 80%

License

This project is licensed under the MIT License - see the package.json file for details.

---

TokenMinds Africa Strategy Backend - Built with ❤️ using NestJS