Skip to content

readme.md

Latest commit

 

History

History
245 lines (187 loc) · 8.04 KB

readme.md

File metadata and controls

245 lines (187 loc) · 8.04 KB
Raw

NovaPay — Rebuilt Transaction Backend

Postman Documentation - https://documenter.getpostman.com/view/50316638/2sBXirjUHD

Live - http://nova-pay-liart.vercel.app

Rebuilt from the ground up after the year-end payroll crisis. Every failure is now a feature.

Tech Stack

  • Runtime: Node.js 20 + TypeScript
  • Framework: Express.js (Modular Monolith)
  • ORM: Prisma + PostgreSQL 16
  • Queue: BullMQ + Redis 7
  • Auth: JWT + bcrypt
  • Logging: Winston (structured JSON)
  • Validation: Zod
  • Tests: Jest + ts-jest

Quick Start

# 1. Install
npm install

# 2. Start DB + Redis
docker-compose up postgres redis -d

# 3. Run migrations
npm run prisma:migrate

# 4. Seed test data
npx tsx prisma/seed.ts

# 5. Start dev server
npm run dev
# → http://localhost:3000

Run with Docker (full stack)

cp .env.example .env   # fill in values
docker-compose up --build

Run Tests

npm test

Test Credentials (after seed)

Role Email Password Balance
SUPER_ADMIN superadmin@novapay.com SuperAdmin@123! —
ADMIN admin@novapay.com Admin@123! —
CORPORATE corporate@acmecorp.com Corporate@123! $500,000 USD
CUSTOMER alice@example.com Customer@123! $1,000 + €500
CUSTOMER bob@example.com Customer@123! $1,000 + €500
EMPLOYEE emp1@acmecorp.com Employee@123! $0
EMPLOYEE emp2@acmecorp.com Employee@123! $0
EMPLOYEE emp3@acmecorp.com Employee@123! $0

API Endpoints

Auth

Method Endpoint Description
POST /api/auth/register Register new user
POST /api/auth/login Login, get JWT
POST /api/auth/logout Invalidate session

Login example:

POST /api/auth/login
{ "email": "alice@example.com", "password": "Customer@123!" }

→ { "success": true, "data": { "token": "eyJ...", "user": { ... } } }

Accounts

Method Endpoint Description
GET /api/accounts/me My profile
PATCH /api/accounts/me Update profile
GET /api/accounts/wallets My wallets
POST /api/accounts/wallets Create wallet
GET /api/accounts/wallets/:id/balance Get balance

Transactions

Method Endpoint Description
POST /api/transactions/transfer Send money (requires Idempotency-Key)
GET /api/transactions/history Paginated history (cursor-based)
GET /api/transactions/:id Get single transaction

Transfer example:

POST /api/transactions/transfer
Headers: Authorization: Bearer <token>, Idempotency-Key: unique-key-001
{ "receiverEmail": "bob@example.com", "amount": 100, "currency": "USD" }

→ Sender loses $102 ($100 + $2 fee). Bob gains $100.

FX

Method Endpoint Description
POST /api/fx/quote Get locked rate quote (60s TTL)
GET /api/fx/quote/:id Check quote validity
POST /api/fx/transfer Execute FX transfer (requires quoteId)

FX flow:

// Step 1: Get quote
POST /api/fx/quote
{ "fromCurrency": "USD", "toCurrency": "EUR", "sourceAmount": 200 }
→ { "quoteId": "abc-123", "rate": 0.92, "expiresAt": "...", "secondsRemaining": 60 }

// Step 2: Execute within 60 seconds
POST /api/fx/transfer
{ "quoteId": "abc-123", "receiverEmail": "bob@example.com" }
→ Transfer executed at locked rate. Quote marked USED. Cannot be reused.

Payroll

Method Endpoint Description
POST /api/payroll/disburse Submit bulk payroll job
GET /api/payroll/jobs/:id Check job progress

Payroll example:

POST /api/payroll/disburse
Headers: Authorization: Bearer <corporate-token>, Idempotency-Key: payroll-nov-2024-batch-001
{
  "employerWalletId": "<wallet-uuid>",
  "currency": "USD",
  "items": [
    { "employeeEmail": "emp1@acmecorp.com", "amount": 1500 },
    { "employeeEmail": "emp2@acmecorp.com", "amount": 2000 }
  ]
}
→ 202 Accepted. Job queued. Poll /api/payroll/jobs/:id for progress.

Admin (ADMIN / SUPER_ADMIN only)

Method Endpoint Description
GET /api/admin/users List all users
GET /api/admin/users/:id Get user detail
PATCH /api/admin/users/:id/status Suspend / activate user
GET /api/admin/transactions List all transactions
POST /api/admin/transactions/:id/reverse Reverse a completed transaction
GET /api/admin/ledger/verify Check double-entry invariant
GET /api/admin/stats Platform stats
GET /api/admin/audit-logs Audit trail

Five Idempotency Scenarios

See decisions.md for the full explanation. Summary:

Scenario What happens
A — Same key, sequential Second request returns cached response. No second debit.
B — Three requests in 100ms Postgres unique constraint ensures exactly one wins. Others poll and get cached response.
C — Crash mid-transfer prisma.$transaction rolls everything back. debitCompletedAt/creditCompletedAt timestamps enable recovery detection.
D — Key used 30hrs later (expired) Returns 410 GONE with IDEMPOTENCY_KEY_EXPIRED.
E — Same key, different payload SHA256 hash mismatch returns 409 CONFLICT with IDEMPOTENCY_KEY_MISMATCH.

Double-Entry Invariant

Every transfer creates exactly 2 ledger entries per movement:

Transfer $100 from Alice to Bob + $2 fee:
  DEBIT  alice_wallet   $102
  CREDIT bob_wallet     $100
  CREDIT fee_account    $2

SUM(DEBITs) = SUM(CREDITs) always. Check anytime: GET /api/admin/ledger/verify

FX Quote Strategy

  1. Client calls POST /api/fx/quote → rate fetched live from provider → locked quote issued with 60s TTL
  2. Client must call POST /api/fx/transfer within 60 seconds using the quoteId
  3. Quote is marked USED atomically inside the same DB transaction as the transfer — impossible to reuse
  4. If provider is unreachable → FX_PROVIDER_UNAVAILABLE error. Never silently applies a cached rate.
  5. If quote expired → FX_QUOTE_EXPIRED error. Client must request a new quote.

Payroll Resumability

The checkpoint pattern: each PayrollItem has a status field and itemIndex.

On crash/restart:

  • Worker re-queries only WHERE status = PENDING ORDER BY itemIndex ASC
  • Completed items are skipped automatically
  • Failed items are logged but do not stop the job
  • PayrollJob.lastProcessedIndex tracks the last successfully processed item

Audit Hash Chain

Each LedgerEntry.entryHash = SHA256(prevEntryHash + txId + amount + walletId + entryType).

If any record is tampered with, the hash chain breaks from that point forward — detectable by recomputing hashes and comparing.

Logging

Every log line includes: requestId, userId, timestamp, level, message. Sensitive fields (password, token, secret) are automatically redacted before logging.

Logs written to: logs/combined.log and logs/error.log

What I Would Add Before Production

  1. Email verification + OTP — users are auto-ACTIVE now
  2. Prometheus metrics — transaction throughput, p95/p99 latency, ledger invariant violation counter
  3. Jaeger tracing — OpenTelemetry spans per request
  4. Per-user rate limiting — Redis sliding window per userId
  5. Refresh tokens — short-lived access tokens + long-lived refresh
  6. Recovery worker — cron job to detect and resolve REQUIRES_RECOVERY transactions
  7. Multi-region read replicas — for transaction history queries
  8. Webhook system — notify clients of payroll completion
  9. KYC integration — verify identity before high-value transfers
  10. Secrets manager — AWS Secrets Manager / Vault instead of .env for keys