Platform Overview

Tech Stack

Service Port Map

Quick Start

Get the full platform running locally in about 5 minutes.

Prerequisites

Setup Steps

# 1. Clone the repository
git clone https://github.com/mail2ratnakar/finvault.git
cd finvault

# 2. Copy environment template and fill in values
cp .env.example .env
# Edit .env — minimum required values listed below

# 3. Install all workspace dependencies
npm install

# 4. Start infrastructure (Redis on :6379, Mailhog on :8025)
bash infra/scripts/start-dev.sh

# 5. Apply database migrations (first time only)
supabase link --project-ref YOUR_PROJECT_REF
supabase db push

# 6. Start all 15 services in development mode
npm run dev

# 7. Verify everything is running
curl http://localhost:4000/health

Minimum Required Environment Variables

Run Smoke Tests

# With all services running, run the 12-test smoke suite (~60s)
npx ts-node infra/scripts/smoke-tests.ts

# Expected: 12 / 12 tests passing
# Tests cover: register -> login -> KYC -> template -> batch -> approve
#              -> poll -> verify -> revoke -> verify-revoked -> payment -> health

System Diagram

FinVault is a microservices monorepo. All client traffic enters through a single API Gateway. Services communicate internally via HTTP with the X-Internal-Key header and via BullMQ job queues for async work.

Microservices Map

All 15 backend services. Each exposes GET /health returning {"status":"ok","version":"x.y.z"}.

Web Portals

All 8 portals are Next.js 14 applications using the App Router. They live in the web/ directory of the monorepo.

Data Flow

Flow 1 — Certificate Issuance

1. Issuer uploads CSV via issuer-portal → POST /credentials/batches → credential-service stores batch record and raw CSV in S3.
2. Admin approves batch → POST /credentials/batches/:id/approve → credential-service enqueues cert-issue BullMQ jobs (one per CSV row).
3. queue-worker processes jobs → for each job: reads recipient data, generates RSA-2048 signed cert JSON (RFC 8785 canonical form), stores in DB and S3, calls blockchain-service to anchor hash.
4. blockchain-service → calls FinVaultRegistry.sol anchorCertificate(certHash, issuerAddress) on Polygon → stores txHash and blockNumber in blockchain_records.
5. notification-service → sends branded email to recipient with cert ID, QR code, and download link.

Flow 2 — Certificate Verification

1. Verifier opens QR code or enters cert ID → verification-portal calls GET /verify/:certId.
2. verification-service → fetches cert from DB, reconstructs canonical JSON, verifies RSA-2048 signature against issuer's public key in key registry.
3. Blockchain cross-check → calls blockchain-service to confirm cert hash is anchored on Polygon and matches DB record.
4. Revocation check → confirms cert is not in revocation list.
5. Result returned → { valid: true, issuer, recipient, issuedAt, blockchainTx } or structured error.

Flow 3 — KYC Flow

1. Organisation submits KYC → POST /kyc/submit with CIN, incorporation docs → kyc-service stores submission, uploads docs to S3.
2. Admin review queue → staff-portal /kyc page shows all under_review submissions.
3. Admin approves or rejects → POST /admin/orgs/:id/approve-kyc or reject-kyc → updates organisations.kyc_status and kyc_submissions (with reviewer_id, reviewed_at, notes).
4. Notification sent → notification-service emails org admin with outcome and next steps.

Internal Communications

HTTP — createInternalClient

All synchronous inter-service calls use the shared createInternalClient helper from @finvault/utils. It automatically attaches the X-Internal-Key auth header and retries 3× with exponential backoff on 5xx errors.

import { createInternalClient } from '@finvault/utils';

// Create a typed client for a target service
const blockchainClient = createInternalClient(
  'blockchain-service',
  process.env.BLOCKCHAIN_SERVICE_URL  // e.g. http://localhost:4004
);

// All requests automatically include X-Internal-Key header
const result = await blockchainClient.post('/internal/anchor', {
  certHash: '0xabc...',
  issuerAddress: '0x123...'
});

Every service validates the X-Internal-Key header on /internal/* routes. The key is set via INTERNAL_SERVICE_KEY env var and is shared across all services.

Async — BullMQ Queues

All queues use Redis (configured via REDIS_URL). Jobs are retried 3× on failure. Failed jobs move to the failed state and can be inspected via Bull Board (not yet configured — add to production runbook).

Retry Policy

• HTTP retries: 3 attempts, exponential backoff starting at 250ms
• Retry on: 5xx errors, network timeouts
• No retry on: 4xx errors (client errors are not transient)
• BullMQ job retries: 3 attempts, configurable delay per queue

Schema Overview

FinVault uses Supabase (PostgreSQL 15) with Row Level Security enforced on all tenant data tables. The schema spans 53 migrations covering the full platform lifecycle.

Entity Groups

RLS Isolation Pattern

Every tenant table has an org_id foreign key. RLS policies use this pattern:

-- Standard RLS policy on tenant tables
CREATE POLICY "org_isolation" ON certificates
  FOR ALL USING (
    org_id IN (
      SELECT org_id FROM org_members
      WHERE user_id = auth.uid()
    )
  );

-- Superadmin bypass (platform_admin role)
CREATE POLICY "platform_admin_bypass" ON certificates
  FOR ALL USING (
    EXISTS (
      SELECT 1 FROM users
      WHERE id = auth.uid() AND role = 'platform_admin'
    )
  );

Key Relationships

• certificates → batches → templates → organisations
• certificates → blockchain_records (one-to-one, nullable until anchored)
• users → org_members → organisations (many-to-many, with role)
• credit_ledger → organisations (credit balance tracked via ledger entries)
• audit_logs → organisations, users (immutable append-only)

Migrations Reference

53 migrations in supabase/migrations/. Apply in order using supabase db push.

How to Apply

# Install Supabase CLI
npm install -g supabase

# Link to your project
supabase link --project-ref YOUR_PROJECT_REF

# Apply all pending migrations
supabase db push

# Verify which migrations have been applied
supabase migration list

Migration Table

Note: Migrations 0023–0034, 0041–0046, and 0049 are omitted from the table above for brevity. Run ls supabase/migrations/ to see the complete list.

RLS Policies

Row Level Security (RLS) is enabled on all tables containing tenant data. Supabase enforces policies at the database level — no data can leak between organisations even if application-level auth is bypassed.

RLS-Enabled Tables

All tables in the Core, Billing, Compliance, Multitenancy, and Support groups have RLS enabled. System tables (system_alerts, service_health_history) use admin-only policies.

Client Key vs Service Role Key

Edge Cases

• Public verification — certificates has a separate public_verification policy that allows unauthenticated SELECT on the cert ID and status fields only. Full cert data remains org-isolated.
• Platform admin bypass — Users with role = 'platform_admin' in the users table bypass org_id isolation policies for admin operations.
• Audit logs — audit_logs is append-only. No UPDATE or DELETE policies exist — logs are immutable by design.

Environment Variables

All services read configuration from environment variables. Copy .env.example to .env and fill in all Required values before starting services.

Authentication

Database

Cryptography & Blockchain

External Services

Service URLs (inter-service)

Infrastructure Setup

What Exists (Local Dev Only)

What Needs to Be Provisioned for Production

Minimum Server Requirements (per service)

With 15 services, total minimum RAM is ~3.75 GB. Recommended total: ~7.5 GB across the fleet. The queue-worker and blockchain-service may spike higher under load.

Docker & Redis

Local development uses Docker Compose to run Redis and Mailhog. No application services run in Docker — they run directly via npm run dev.

Start Infrastructure

# Start Redis (:6379) and Mailhog (:8025 web, :1025 SMTP)
bash infra/scripts/start-dev.sh

# Verify Redis is running
redis-cli ping  # Expected: PONG

# View Mailhog inbox (captured emails in local dev)
open http://localhost:8025

docker-compose.yml Services

Redis Configuration

Redis is used for three purposes:

• BullMQ queues — queue-worker processes all async jobs. Queue names: cert-issue, blockchain-anchor, email-send, kyc-notify
• Rate limiting state — api-gateway tracks per-IP and per-org request counts
• Session caching — optional session data for fast auth lookups

Set REDIS_URL=redis://localhost:6379 for local dev. For production, use a managed Redis service (Upstash, ElastiCache, Redis Cloud).

Supabase Setup

FinVault uses Supabase (managed PostgreSQL 15) for the database, file storage, and authentication infrastructure.

Initial Setup

# Install Supabase CLI
npm install -g supabase

# Log in
supabase login

# Link to your project (get ref from Supabase dashboard -> Settings -> General)
supabase link --project-ref YOUR_PROJECT_REF

# Apply all 53 migrations in order
supabase db push

# Confirm which migrations are applied
supabase migration list

Storage Buckets

The following storage buckets must exist (created by migrations, but verify):

Key Settings to Configure in Supabase Dashboard

• Email auth → disable (FinVault uses its own auth-service, not Supabase Auth)
• JWT expiry → not relevant (FinVault issues its own JWTs)
• Connection pooling → enable PgBouncer in transaction mode for production (prevents connection exhaustion with 15 services)
• Point-in-time recovery → enable for production data protection

Blockchain / Polygon

FinVault anchors certificate hashes on the Polygon network using the FinVaultRegistry Solidity smart contract.

Contract: FinVaultRegistry.sol

Located at contracts/FinVaultRegistry.sol. Key functions:

• anchorCertificate(bytes32 certHash, address issuerAddress) — records cert hash + issuer on-chain. Emits CertificateAnchored event.
• verifyCertificate(bytes32 certHash) — returns anchor data (issuerAddress, timestamp, blockNumber).
• revokeCertificate(bytes32 certHash) — marks cert as revoked on-chain. Only callable by original issuer.

Contract uses OpenZeppelin Ownable with two-step ownership transfer for security.

Deploy to Amoy Testnet

cd contracts

# Install Hardhat dependencies
npm install

# Deploy to Amoy testnet
npx hardhat deploy --network amoy

# Contract address is printed after deployment -- save to .env
# POLYGON_CONTRACT_ADDRESS=0x...

# Verify on Polygonscan (optional but recommended)
npx hardhat verify --network amoy CONTRACT_ADDRESS

Environment Variables

Production Runbook

Step-by-step sequence for the first production deployment. Complete the Pre-Production Checklist before starting.

Go-Live Sequence

1. 1
   Provision cloud infrastructure — ECS cluster + task definitions, ECR repositories, ALB with target groups, security groups, VPC. Estimated: 4–8h.
2. 2
   Provision managed Redis — Upstash (simplest) or ElastiCache. Note the Redis URL for env vars.
3. 3
   Create production Supabase project — New project in Supabase dashboard. Enable connection pooling (PgBouncer, transaction mode).
4. 4
   Set all environment variables — In ECS task definitions (or Railway/Render env settings). Reference the Environment Variables page.
5. 5
   Apply database migrations — supabase link --project-ref PROD_REF && supabase db push. Verify all 53 migrations applied: supabase migration list.
6. 6
   Deploy smart contract — After CertiK audit completion only. npx hardhat deploy --network polygon. Fund platform wallet with MATIC first. Update POLYGON_CONTRACT_ADDRESS.
7. 7
   Build and push Docker images — npm run build → build Dockerfile per service → push to ECR. Tag with git SHA.
8. 8
   Deploy all 15 services — Update ECS task definitions with new image tags. Force new deployment on each service. Verify health endpoints respond 200.
9. 9
   Deploy all 8 web portals — Build Next.js apps (npm run build) and deploy to Vercel, Cloudflare Pages, or serve static from S3+CloudFront.
10. 10
    Run smoke tests against production — API_BASE=https://api.finvault.in npx ts-node infra/scripts/smoke-tests.ts. Expect 12/12 passing.
11. 11
    Configure Cloudflare WAF — Point api.finvault.in DNS → ALB through Cloudflare. Enable WAF rules: rate limiting, bot protection, OWASP core rule set.
12. 12
    Configure email domain — Add SendGrid DMARC/SPF/DKIM DNS records for the finvault.in sending domain to prevent email spoofing.
13. 13
    Enable monitoring — Configure health check alarms, error rate alerts, and latency dashboards. Set up on-call rotation.
14. 14
    Complete go-live sign-off — Fill in the Pre-Production Checklist with owners and sign-off dates.

Health Check Endpoints

All 15 services expose GET /health returning {"status":"ok","version":"x.y.z","service":"name"}. Use these for load balancer health checks and monitoring.

Rollback Procedure

1. Identify the previous good Docker image tag (git SHA of last known-good commit)
2. Update ECS task definition to previous image tag for affected service(s)
3. Force new deployment: aws ecs update-service --force-new-deployment
4. Database migrations are additive — no DB rollback is needed for service rollbacks
5. If a migration must be rolled back, it requires a new forward migration (never delete applied migrations)

Authentication API

Base URL: http://localhost:4001 (proxied through API Gateway at localhost:4000/auth)
Auth: Most endpoints are unauthenticated. GET /auth/me requires Authorization: Bearer <token>.

{
  "org_name": "Acme University",
  "slug": "acme-university",
  "domain": "https://acme.edu",
  "email": "admin@acme.edu",
  "full_name": "Jane Smith",
  "password": "S3cur3P@ss"
}

{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "user": { "id": "uuid", "email": "admin@acme.edu", "role": "issuer" },
  "org": { "id": "uuid", "name": "Acme University", "slug": "acme-university" }
}

{ "email": "admin@acme.edu", "password": "S3cur3P@ss" }

{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "user": { "id": "uuid", "email": "admin@acme.edu", "role": "issuer" }
}

{ "totp_required": true, "totp_session_token": "tmp_token_..." }

{ "refresh_token": "eyJhbGci..." }

{ "access_token": "eyJhbGci...", "refresh_token": "new_token..." }

{
  "secret": "BASE32SECRET",
  "otpauth_url": "otpauth://totp/FinVault:user@email.com?secret=...",
  "backup_codes": ["abc123", "def456", "..."]
}

{ "totp_session_token": "tmp_token_...", "code": "123456" }

{ "access_token": "eyJhbGci...", "refresh_token": "eyJhbGci..." }

{
  "id": "uuid",
  "email": "admin@acme.edu",
  "full_name": "Jane Smith",
  "role": "issuer",
  "totp_enrolled": true,
  "org": { "id": "uuid", "name": "Acme University", "kyc_status": "approved" }
}

{ "refresh_token": "eyJhbGci..." }

{ "message": "Logged out" }

Credential API

Base URL: http://localhost:4002 (proxied via API Gateway)
Auth: All endpoints require Authorization: Bearer <token> or X-API-Key: fvk_live_...

{
  "data": [{ "id": "cert_uuid", "status": "issued", "recipient_email": "...", "issued_at": "..." }],
  "total": 150, "page": 1, "limit": 20
}

{
  "template_id": "template_uuid",
  "recipient": {
    "name": "John Doe",
    "email": "john@example.com",
    "metadata": { "course": "Data Science", "grade": "A" }
  }
}

{ "id": "cert_uuid", "status": "pending", "job_id": "bull_job_id" }

{ "batch_id": "batch_uuid", "status": "pending_approval", "row_count": 250 }

{ "batch_id": "batch_uuid", "status": "processing", "jobs_enqueued": 250 }

{
  "batch_id": "batch_uuid",
  "status": "processing",
  "total": 250,
  "issued": 180,
  "failed": 2,
  "pending": 68
}

Verification API

Base URL: http://localhost:4003 (proxied via API Gateway)
Auth: GET /verify/:certId is public (no auth required). Revocation requires issuer auth.

{
  "valid": true,
  "cert_id": "cert_uuid",
  "recipient_name": "John Doe",
  "issued_at": "2026-01-15T10:30:00Z",
  "issuer": { "name": "Acme University", "verified": true },
  "blockchain": { "tx_hash": "0xabc...", "block_number": 12345678, "anchored_at": "2026-01-15T10:31:00Z" },
  "revoked": false
}

{ "valid": false, "revoked": true, "revoked_at": "2026-03-01T09:00:00Z", "reason": "Issued in error" }

{ "cert_ids": ["cert_uuid_1", "cert_uuid_2"] }

{ "results": [{ "cert_id": "...", "valid": true }, { "cert_id": "...", "valid": false }] }

{ "reason": "Issued in error — recipient data incorrect" }

{ "cert_id": "cert_uuid", "revoked": true, "revoked_at": "2026-06-03T12:00:00Z" }

Blockchain API

Base URL: http://localhost:4004 — internal service only. Not proxied through the public API Gateway. Called by credential-service and queue-worker via X-Internal-Key.
Auth: X-Internal-Key: <INTERNAL_SERVICE_KEY> header required on all endpoints.

{ "cert_id": "cert_uuid", "cert_hash": "0xabc...", "issuer_address": "0x123..." }

{ "tx_hash": "0xdef...", "block_number": 12345678, "anchored_at": "2026-06-03T12:00:00Z" }

{ "anchored": true, "issuer_address": "0x123...", "timestamp": 1717416000, "block_number": 12345678 }

{
  "status": "ok", "version": "1.1.0",
  "blockchain": { "connected": true, "network": "amoy", "block": 12345678 }
}

KYC API

Base URL: http://localhost:4009 (proxied via API Gateway)
Auth: Issuer endpoints require issuer JWT. Admin review endpoints require platform_admin JWT.

{
  "cin": "U72200MH2020PTC123456",
  "company_name": "Acme University",
  "registered_address": "123 Main St, Mumbai",
  "contact_name": "Jane Smith",
  "contact_email": "kyc@acme.edu",
  "contact_phone": "+91-9876543210"
}

{ "submission_id": "kyc_uuid", "status": "under_review" }

{ "document_id": "doc_uuid", "document_type": "coi", "url": "https://storage/..." }

{ "kyc_status": "approved", "submitted_at": "2026-01-10T09:00:00Z", "reviewed_at": "2026-01-12T11:00:00Z" }

{ "data": [{ "submission_id": "...", "org_name": "...", "cin": "...", "submitted_at": "..." }], "total": 12 }

Payments API

Base URL: http://localhost:4007 (proxied via API Gateway)
Auth: All endpoints require Authorization: Bearer <token>

FinVault uses a credit pack model. Organisations buy credit packs (50 / 250 / 750 / 2000 certificate credits) via Razorpay. Each certificate issuance deducts 1 credit.

{ "pack": "250" }

{
  "order_id": "order_rzp_...",
  "razorpay_order_id": "order_rzp_...",
  "amount": 199900,
  "currency": "INR",
  "key_id": "rzp_live_..."
}

{
  "razorpay_order_id": "order_rzp_...",
  "razorpay_payment_id": "pay_rzp_...",
  "razorpay_signature": "hmac_sha256_signature"
}

{ "credits_added": 250, "new_balance": 312 }

{ "balance": 312, "lifetime_purchased": 500, "lifetime_used": 188 }

{ "data": [{ "id": "inv_uuid", "amount": 199900, "credits": 250, "paid_at": "2026-05-01T10:00:00Z" }] }

Admin API

Base URL: http://localhost:4008 (proxied via API Gateway)
Auth: All endpoints require Authorization: Bearer <platform_admin_token> unless noted.

Organisation Management

{ "org_id": "uuid", "kyc_status": "approved", "reviewed_by": "admin_uuid", "reviewed_at": "2026-06-03T12:00:00Z" }

{ "reason": "Provided CIN does not match company name in MCA records" }

{ "reason": "Policy violation — suspicious issuance pattern" }

CERT-In Compliance Endpoints

{
  "incident_type": "data_breach",
  "severity": "high",
  "description": "Unauthorised access attempt detected on admin portal",
  "detected_at": "2026-06-03T08:00:00Z",
  "affected_systems": ["admin-portal", "admin-service"]
}

{ "name": "FinVault Security Team", "email": "security@finvault.in", "phone": "+91-XXX-XXX-XXXX" }

Analytics API

Base URL: http://localhost:4006
Auth: All endpoints require Authorization: Bearer <token> (issuer or admin role).

{ "event_type": "cert_issued", "payload": { "cert_id": "uuid", "template_id": "uuid" } }

{ "event_id": "uuid", "recorded_at": "2026-06-03T12:00:00Z" }

{
  "certs_issued_total": 1250,
  "certs_issued_this_month": 180,
  "verifications_this_month": 430,
  "credit_balance": 312,
  "active_templates": 5
}

Marketplace API

Base URL: http://localhost:4013
Auth: Read endpoints are public. Write endpoints require issuer JWT.

{ "data": [{ "id": "moodle", "name": "Moodle LMS", "type": "lms", "active": true }] }

{ "config": { "moodle_url": "https://moodle.acme.edu", "api_token": "moodle_token" } }

Helpdesk API

Base URL: http://localhost:4014
Auth: Issuer endpoints require issuer JWT. Agent endpoints require CS agent or staff JWT (dual-token via AgentAuthGuard).

{ "subject": "Certificate not received", "description": "Batch 123 shows issued but recipient did not get email", "priority": "medium" }

{ "ticket_id": "TKT-0042", "status": "open", "sla_deadline": "2026-06-05T12:00:00Z" }

Notifications API

Base URL: http://localhost:4005
Auth: Internal endpoints use X-Internal-Key. Preference endpoints use Bearer JWT.

{
  "template": "cert_issued",
  "to": "john@example.com",
  "variables": { "recipient_name": "John Doe", "cert_id": "cert_uuid", "verify_url": "https://verify.finvault.in/cert_uuid" }
}

{ "cert_issued": true, "batch_complete": true, "kyc_update": true, "payment_receipt": true }

Webhooks Reference

FinVault sends webhook events to your registered endpoint URL for key platform events. Configure your webhook endpoint URL in the issuer portal settings.

Signature Verification

Every webhook delivery includes an X-FinVault-Signature header. Verify it before processing:

import * as crypto from 'crypto';

function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  if (signature.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express handler example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-finvault-signature'] as string;
  if (!verifyWebhookSignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // process event...
  res.sendStatus(200);
});

Delivery Policy

• POST to your endpoint with Content-Type: application/json
• 10 second timeout per attempt
• Retried 3 times on non-2xx response or timeout (exponential backoff: 1m, 5m, 30m)
• After 3 failures, event is marked failed and visible in webhook delivery log

Event Catalog

{
  "event": "cert.issued", "timestamp": "2026-06-03T12:00:00Z",
  "data": {
    "cert_id": "cert_uuid", "recipient_email": "john@example.com",
    "recipient_name": "John Doe", "template_id": "template_uuid",
    "blockchain_tx": "0xabc...", "verify_url": "https://verify.finvault.in/cert_uuid"
  }
}

{ "event": "cert.revoked", "timestamp": "2026-06-03T12:00:00Z", "data": { "cert_id": "cert_uuid", "reason": "Issued in error", "revoked_by": "issuer_uuid" } }

{ "event": "kyc.approved", "timestamp": "2026-06-03T12:00:00Z", "data": { "org_id": "uuid", "org_name": "Acme University" } }

{ "event": "payment.success", "timestamp": "2026-06-03T12:00:00Z", "data": { "org_id": "uuid", "credits_added": 250, "amount_inr": 1999 } }

{ "event": "batch.approved", "timestamp": "2026-06-03T12:00:00Z", "data": { "batch_id": "uuid", "row_count": 250, "template_id": "uuid" } }

Repo Structure

FinVault is a Turborepo monorepo with npm workspaces. All packages are TypeScript.

finvault/
├── apps/                        # Backend microservices
│   ├── admin-service/           # :4008 -- Platform admin
│   ├── analytics-service/       # :4006 -- Usage analytics
│   ├── api-gateway/             # :4000 -- Reverse proxy + rate limiter
│   ├── auth-service/            # :4001 -- Authentication + JWT
│   ├── blockchain-service/      # :4004 -- Polygon interaction
│   ├── credential-service/      # :4002 -- Certificate management
│   ├── crm-service/             # :4011 -- Lead management
│   ├── finance-service/         # :4012 -- Double-entry ledger
│   ├── helpdesk-service/        # :4014 -- Support tickets
│   ├── kyc-service/             # :4009 -- KYC submission
│   ├── marketplace-service/     # :4013 -- Integration connectors
│   ├── notification-service/    # :4005 -- Email + webhook delivery
│   ├── payment-service/         # :4007 -- Razorpay integration
│   ├── queue-worker/            # :4010 -- BullMQ job processor
│   └── verification-service/    # :4003 -- Public cert verification
│
├── web/                         # Frontend portals (Next.js 14)
│   ├── admin-portal/            # :3004 -- Platform admin dashboard
│   ├── ca-portal/               # :3005 -- Certificate Authority
│   ├── cs-portal/               # :3006 -- Customer support
│   ├── issuer-portal/           # :3001 -- Issuing organisations
│   ├── marketplace/             # :3008 -- Integration marketplace
│   ├── marketing-site/          # :3000 -- Public landing page
│   ├── recipient-wallet/        # :3002 -- Recipient credentials
│   ├── staff-portal/            # :3007 -- Internal staff ops
│   └── verification-portal/     # :3003 -- Public verification
│
├── packages/                    # Shared TypeScript packages
│   ├── abuse/                   # Rate limiting, lockout helpers
│   ├── config/                  # Env validation schemas
│   ├── crypto/                  # RSA, AES-256-GCM, canonical JSON
│   ├── db/                      # Supabase client factory
│   ├── lms-plugins/             # LMS integration adapters
│   ├── types/                   # Shared TypeScript types
│   ├── ui/                      # Shared React components
│   └── utils/                   # createInternalClient, logger, etc.
│
├── contracts/                   # Solidity smart contracts
│   ├── FinVaultRegistry.sol     # Main certificate registry contract
│   └── hardhat.config.ts        # Hardhat + Polygon network config
│
├── supabase/
│   └── migrations/              # 53 SQL migration files (apply in order)
│
├── infra/
│   ├── docker/                  # Dockerfiles per service
│   ├── scripts/                 # start-dev.sh, smoke-tests.ts, validate-env.ts
│   └── test-fixtures/           # test-batch.csv for smoke tests
│
├── docs/
│   ├── openapi/                 # finvault-api.yaml, webhooks.yaml
│   ├── superpowers/             # Design specs and implementation plans
│   ├── CHANGELOG.md
│   ├── BUILD_INFO.md
│   ├── SECURITY_CHECKLIST.md
│   └── finvault-handover.html   # ← This document
│
├── turbo.json                   # Turborepo pipeline config
├── package.json                 # Workspace root -- npm scripts
└── tsconfig.base.json           # Shared TypeScript config

Key npm Scripts (run from repo root)

Adding a New Service

Follow these steps to add a new NestJS microservice to the FinVault monorepo.

1. Scaffold the app:
   bashCopy

   cd apps
   mkdir my-service && cd my-service
   npm init -y
   # Standard NestJS directory structure:
   mkdir -p src/my-module
   # Create: src/main.ts, src/app.module.ts, src/my-module/my-module.module.ts
   # Create: src/my-module/my-module.controller.ts, src/my-module/my-module.service.ts

2. Add to turbo.json pipeline: Add "apps/my-service" to the workspaces array in package.json root.
3. Assign a port — next available after :4014. Update README.md service port map.
4. Add to docker-compose.yml for local dev (optional, services run natively in dev mode).
5. Implement health endpoint:
   typescriptCopy

   // src/health/health.controller.ts
   import { Controller, Get } from '@nestjs/common';
   @Controller()
   export class HealthController {
     @Get('health')
     health() {
       return { status: 'ok', version: process.env.npm_package_version, service: 'my-service' };
     }
   }

6. Register in api-gateway — add proxy route in apps/api-gateway/src/index.ts pointing to the new service.
7. Add env validation:
   typescriptCopy

   // src/config/env.validation.ts
   import { IsString, IsNotEmpty, validateSync } from 'class-validator';
   import { plainToInstance } from 'class-transformer';
   
   class EnvironmentVariables {
     @IsString() @IsNotEmpty() MY_REQUIRED_VAR: string;
   }
   
   export function validate(config: Record<string, unknown>) {
     const validated = plainToInstance(EnvironmentVariables, config, { enableImplicitConversion: true });
     const errors = validateSync(validated);
     if (errors.length > 0) throw new Error(errors.toString());
     return validated;
   }

8. Add to smoke tests — extend infra/scripts/smoke-tests.ts with a health check for the new service.

Shared Packages

All shared code lives in packages/ and is imported as @finvault/<name>.

@finvault/types

Shared TypeScript interfaces and enums: Certificate, Organisation, User, Batch, Template, CertStatus, KycStatus, OrgTier.

@finvault/crypto

All cryptographic operations. Never implement crypto outside this package.

import { signCertificate, verifyCertificate, canonicalJson, timingSafeEqual, encryptWithAES, decryptWithAES } from '@finvault/crypto';

// RSA-2048 sign cert JSON
const signature = await signCertificate(certJson, privateKeyPem);

// AES-256-GCM encrypt a private key for storage
const encrypted = encryptWithAES(privateKeyPem, process.env.KMS_ENCRYPTION_KEY);

@finvault/utils

Inter-service communication and request utilities.

import { createInternalClient, requestIdMiddleware, logger } from '@finvault/utils';

// HTTP client with automatic X-Internal-Key header and 3x retry
const client = createInternalClient('blockchain-service', process.env.BLOCKCHAIN_SERVICE_URL);
const result = await client.post('/internal/anchor', body);

@finvault/db

Supabase client factory. Always use this — never instantiate createClient directly in services.

import { getSupabaseAdmin, getSupabaseClient } from '@finvault/db';

// Service role client (bypasses RLS) -- use in backend services only
const adminClient = getSupabaseAdmin();

// Anon client (RLS enforced) -- use with user JWT for user-scoped queries
const userClient = getSupabaseClient(userJwt);

@finvault/abuse

Rate limiting and account security helpers: checkRateLimit, recordFailedLogin, checkAccountLocked, resetFailedLogins.

@finvault/config

Environment variable validation schemas for each service. Extend BaseEnvSchema for service-specific vars.

Testing Strategy

Test Layers

Current Test Status

Running Tests

# Run all tests across all services
npm run test

# Run tests for a single service
turbo run test --filter=auth-service

# Run tests in watch mode
turbo run test --filter=auth-service -- --watch

# Run smoke tests (requires all services running)
npx ts-node infra/scripts/smoke-tests.ts

# Run with coverage
turbo run test --filter=credential-service -- --coverage

Writing Tests for a New Endpoint

// apps/my-service/src/my-module/my-module.service.spec.ts
import { Test } from '@nestjs/testing';
import { MyModuleService } from './my-module.service';
import { getSupabaseAdmin } from '@finvault/db';

jest.mock('@finvault/db');

describe('MyModuleService', () => {
  let service: MyModuleService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [MyModuleService],
    }).compile();
    service = module.get(MyModuleService);
  });

  it('should create a record', async () => {
    (getSupabaseAdmin as jest.Mock).mockReturnValue({
      from: () => ({ insert: () => ({ select: () => ({ single: () => ({ data: { id: 'uuid' }, error: null }) }) }) })
    });
    const result = await service.create({ name: 'test' });
    expect(result.id).toBe('uuid');
  });
});

Coding Patterns

NestJS Module Structure

src/
├── main.ts                      # Bootstrap + global pipes + CORS
├── app.module.ts                # Root module -- imports all feature modules
└── certs/
    ├── certs.module.ts          # Feature module -- providers, imports
    ├── certs.controller.ts      # HTTP route handlers
    ├── certs.service.ts         # Business logic
    ├── dto/
    │   ├── create-cert.dto.ts   # class-validator decorated DTOs
    │   └── update-cert.dto.ts
    └── certs.service.spec.ts    # Unit tests co-located with service

DTO Validation Pattern

Always use class-validator decorators. The global ValidationPipe in main.ts handles rejection automatically.

import { IsString, IsEmail, IsNotEmpty, MaxLength } from 'class-validator';

export class IssueCertificateDto {
  @IsString() @IsNotEmpty() template_id: string;
  @IsEmail() recipient_email: string;
  @IsString() @IsNotEmpty() @MaxLength(200) recipient_name: string;
}

// In main.ts -- already configured, do not remove:
app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }));

Guard Composition

import { UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
import { RolesGuard } from '../auth/roles.guard';
import { Roles } from '../auth/roles.decorator';

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('issuer')
@Post('/issue')
async issue(@Body() dto: IssueCertificateDto, @Req() req) {
  return this.certsService.issue(req.user.orgId, dto);
}

Monetary Arithmetic

import Decimal from 'decimal.js';

// Correct -- use decimal.js for all monetary values
const total = new Decimal(price).times(quantity).toFixed(2);

// Wrong -- native float arithmetic causes precision errors
// const total = price * quantity; // Never use for INR amounts

Error Response Format

All services return errors in this format:

{
  "statusCode": 400,
  "message": "Validation failed: email must be a valid email address",
  "error": "VALIDATION_ERROR",
  "requestId": "req_abc123"
}

Audit Logging

Write to audit_logs on all state-changing admin operations:

await getSupabaseAdmin()
  .from('audit_logs')
  .insert({
    action: 'kyc.approved',
    actor_id: req.user.id,
    target_type: 'organisation',
    target_id: orgId,
    metadata: { reviewer_notes: notes },
    org_id: orgId,
  });

Security Architecture

JWT Token Security

• Algorithm: HS256 pinned on ALL 5 JWT guards — { algorithms: ['HS256'] } always specified
• Access token lifetime: 15 minutes
• Refresh token lifetime: 7 days, rotation on every refresh (old token invalidated)
• Refresh tokens stored: SHA-256 hashed in DB — raw token never stored
• Empty secret fallback removed: INTERNAL_JWT_SECRET="" now throws at startup

Cryptography

API Key Scopes

API keys (prefix fvk_live_) have explicit scopes: read, write, admin. Each endpoint declares its required scope. Keys without the required scope get 403.

Rate Limiting

Account Lockout

After 5 consecutive failed login attempts, the account is locked for 15 minutes. Tracked in failed_login_attempts table via @finvault/abuse.

CERT-In Compliance

FinVault implements CERT-In (Indian Computer Emergency Response Team) cybersecurity directives.

OWASP Hardening

The 2026-06-03 security repair run addressed all OWASP Top 10 findings. See docs/SECURITY_CHECKLIST.md and docs/PATCHES.md for full details.

Responsible Disclosure

Reporting a Vulnerability

Response SLAs

Out of Scope

• DoS via resource exhaustion
• Social engineering of staff
• Physical security issues

Coordination

We follow responsible disclosure: allow us to remediate before public disclosure. We will coordinate a disclosure timeline with you after a fix is available. See .well-known/security.txt (served from api.finvault.in/.well-known/security.txt) for the machine-readable security policy.

Pre-Production Checklist

Complete all 🔴 Critical items before any production traffic. Complete 🟡 High items before end of first week. 🟢 Done items are listed for confidence.

🔴 Critical — Block Go-Live

🟡 High — Fix Before First Users

🟢 Done — Security Hardening Complete

Go-Live Sign-Off