Accounts Receivable & Collections

AI-native, self-hostable accounts receivable and collections platform for the mid-market.

Quick Start

Requires Node.js v22+, pnpm 9+, Docker, and Docker Compose.

# Install dependencies
pnpm install

# Start PostgreSQL 16, Redis 7, API, Web, and Worker
pnpm compose:up

# Generate Prisma client and run migrations
pnpm db:generate
pnpm db:migrate:dev

# Seed the development tenant, roles, and sample data
pnpm db:seed

# Run everything in dev mode
pnpm dev

API: http://localhost:3001
Web app: http://localhost:3000
OpenAPI docs: http://localhost:3001/docs
Prisma Studio: pnpm db:studio

To shut down the local stack:

pnpm compose:down

Architecture Overview

apps/
  api/       # Fastify API server (plugins, routes, services, repositories, Prisma)
  web/       # Next.js 15 App Router (internal dashboard + customer portal)
  worker/    # BullMQ background workers
packages/
  shared/    # Shared Zod schemas, types, and utilities
  ai-sdk/    # Provider-agnostic AI client abstraction
  ui/        # Shared React components and design tokens
docker/      # Docker Compose stack
specs/       # Feature specifications, plans, and contracts

Design Principles

Tenant isolation is enforced at the database layer via PostgreSQL RLS (app.current_tenant_id) and at the application layer through the tenant context plugin. Every tenant-scoped table carries tenantId.
Financial precision uses DECIMAL / NUMERIC types everywhere; floating-point arithmetic is forbidden for money.
Auditability: every material change is appended to AuditLog with actor, timestamp, and before/after snapshots.
AI inspectability: every AI-driven output stores confidence, model version, evidence, and timestamp.
Security: raw card data is never stored; only tokenized payment references are kept.
Role-based access control supports admin, ar_manager, collector, credit_analyst, and viewer roles via apps/api/src/plugins/rbac.ts.
ERP interoperability via pluggable connectors for ERPNext, NetSuite, and QuickBooks with configurable sync direction and conflict resolution per entity type.

Core Workflows

Collections worklist: predictive risk scoring and next-best-action recommendations.
Cash application: bank statement import, ISO 11649 remittance parsing, auto-matching with exception queue.
Customer portal: magic-link authentication, invoice viewing, payments, and dispute flagging.
Dunning campaigns: configurable schedules, channels, tone, and escalation paths.
Compliance: tamper-evident audit export, UBL 2.1 / EN 16931 invoice generation, and PEPPOL delivery stubs.
Reports: AR aging report with customer- and invoice-level drill-down and DSO calculation.
Credit administration: credit-limit management, automatic over-limit holds, and manual hold/release.

Common Commands

Command	Description
`pnpm dev`	Start all apps in development mode
`pnpm build`	Build all packages and apps
`pnpm lint`	Run ESLint across the monorepo
`pnpm typecheck`	Run TypeScript checks
`pnpm test`	Run unit tests
`pnpm test:integration`	Run integration tests (requires Docker)
`pnpm test:e2e`	Run Playwright E2E tests
`pnpm db:generate`	Generate Prisma client
`pnpm db:migrate:dev`	Run Prisma migrations in development
`pnpm db:seed`	Seed development tenant and sample data
`pnpm db:studio`	Open Prisma Studio

Environment

Copy .env.example to .env and adjust values before running locally. Key variables:

DATABASE_URL — PostgreSQL connection string
REDIS_URL — Redis connection string for BullMQ
PORTAL_JWT_SECRET — Secret for portal magic-link tokens
OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET — OIDC provider for internal users
NEXT_PUBLIC_API_URL — API origin used by the web app

Testing

Unit tests cover pure business logic (invoice totals, allocation math, ISO 11649 validation, risk scoring, Zod schemas).
Integration tests run against PostgreSQL and Redis via testcontainers and cover money-affecting status transitions and repository behavior.
E2E tests exercise primary user journeys with Playwright against the full Docker Compose stack.

Run the full validation suite:

pnpm typecheck
pnpm test
pnpm test:integration

License

MIT

kimi-base