Configuration (Admin)

• Payment terms management
• Quotation template setup
• Product attribute definitions

Tech Stack

Architecture

System Diagram

flowchart LR
    User[Portal User] --> Web[apps/web - Vite React + Tailwind]
    Staff[Admin / Internal User] --> Web

    Web --> API[apps/api - Express REST API]
    API --> DB[(PostgreSQL)]
    API --> Redis[(Redis)]
    API --> Razorpay[Razorpay API]
    API --> SMTP[SMTP / MailHog]
    API --> Shared[packages/shared]
    Worker[apps/worker - BullMQ Worker] --> Redis
    Worker --> API

    API --> Prisma[Prisma ORM]
    Prisma --> DB

Business Workflow

flowchart TD
    A[Admin seeds system] --> B[Create products & plans]
    B --> C[Create taxes, discounts & quotation templates]

    F[Portal user signup] --> G[OTP email verification]
    G --> H[Browse product catalog]
    H --> I[Select product + recurring plan]
    I --> J[Add to cart]
    J --> K[Checkout: address]
    K --> L[Checkout: Razorpay payment]
    L --> M{Payment verified?}
    M -->|Yes| N[Subscription created & active]
    M -->|No| O[Payment failed screen]
    N --> P[Invoice auto-generated & marked paid]

    Q[Backoffice creates subscription] --> R[Draft subscription]
    R --> S{Next action}
    S -->|Send quotation| T[Quotation sent to portal user]
    S -->|Direct confirm| U[Confirmed]
    T --> U
    U --> V[Invoice generated]
    V --> W[Razorpay payment or manual mark paid]
    W --> N
    N --> X[Renew or upsell subscription]

Database Relationship Summary

erDiagram
    USERS ||--o{ CONTACTS : owns
    CONTACTS ||--o{ ADDRESSES : has
    PRODUCT_CATEGORIES ||--o{ PRODUCTS : groups
    PRODUCTS ||--o{ PRODUCT_VARIANTS : has
    PRODUCT_ATTRIBUTES ||--o{ PRODUCT_ATTRIBUTE_VALUES : has
    PRODUCTS ||--o{ PRODUCT_PLAN_PRICING : priced_with
    RECURRING_PLANS ||--o{ PRODUCT_PLAN_PRICING : applies_to
    QUOTATION_TEMPLATES ||--o{ QUOTATION_TEMPLATE_LINES : contains
    CONTACTS ||--o{ SUBSCRIPTION_ORDERS : places
    USERS ||--o{ SUBSCRIPTION_ORDERS : manages
    SUBSCRIPTION_ORDERS ||--o{ SUBSCRIPTION_ORDER_LINES : has
    SUBSCRIPTION_ORDERS ||--o{ INVOICES : generates
    INVOICES ||--o{ INVOICE_LINES : has
    INVOICES ||--o{ PAYMENTS : settled_by

Repo Map

.
|- apps/
|  |- api/               Express API, Prisma schema, business modules, tests
|  |  |- prisma/         Schema, migrations, seed
|  |  |- src/
|  |     |- config/      Environment config (Zod-validated)
|  |     |- lib/         Prisma client, error classes, logger, mailer, Razorpay helpers
|  |     |- middleware/   Auth guard, error handler
|  |     |- modules/
|  |        |- auth/             Login, signup, OTP, refresh, password reset
|  |        |- users/            User CRUD, role management
|  |        |- contacts/         Contact and address management
|  |        |- catalog/          Products, categories, attributes, variants, plans, discounts
|  |        |- billing/          Invoices, payments, Razorpay order + verify, checkout
|  |        |- subscriptions/    Subscription lifecycle, pricing engine, renewal/upsell
|  |        |- taxes/            Tax rule CRUD
|  |        |- configuration/    Payment terms, quotation templates
|  |        |- reports/          Dashboard KPIs and analytics
|  |     |- routes/      Root API router
|  |- web/               Vite React frontend, admin + portal routes, Tailwind UI
|  |  |- src/
|  |     |- app/         Router setup, query/session providers
|  |     |- components/  Shared layout, icons
|  |     |- features/
|  |        |- admin/    Dashboard, products, users, subscriptions, contacts, reports, config
|  |        |- auth/     Login, signup, OTP verify, password reset
|  |        |- portal/   Home, shop, cart, checkout, account, PDF generation
|  |     |- lib/         API client, session state, cart state, Razorpay loader, PDF utils
|  |- worker/            BullMQ worker, background job execution
|- packages/
|  |- shared/            Shared enums, Zod schemas, DTOs, cross-app contracts
|- infra/
|  |- docker/            Local Postgres + Redis + MailHog stack
|- docs/
|  |- architecture.md
|- .github/
|  |- workflows/         CI/CD pipelines (ci.yml, cd.yml)

Backend Modules

API is mounted under /api/v1:

Frontend Routes

Portal (public + authenticated)

Auth

Admin (role-protected)

Payment Integration (Razorpay)

Veltrix uses Razorpay as the payment gateway for both portal checkout and admin-triggered invoice payments.

How it works

1. Order Creation: When the user proceeds to pay, the frontend calls POST /payments/razorpay/create-order with the invoice ID. The API creates a Razorpay order via the Razorpay REST API using the configured key/secret and returns { orderId, amount, currency, keyId }.

2. Frontend Checkout: The web app dynamically loads the Razorpay Checkout.js SDK and opens the payment modal pre-filled with customer details, amount, and merchant branding.

3. Signature Verification: On payment success, Razorpay returns { razorpay_payment_id, razorpay_order_id, razorpay_signature }. The frontend sends these to POST /payments/razorpay/verify. The API verifies the HMAC-SHA256 signature using crypto.timingSafeEqual to prevent timing attacks.

4. Invoice Settlement: On successful verification, the invoice is marked paid, the payment record is created, and the associated subscription is set to active.

Configuration

Set these in apps/api/.env:

RAZORPAY_KEY_ID=rzp_test_your_key_id
RAZORPAY_KEY_SECRET=your_razorpay_secret

Use rzp_test_* keys for development. Get your keys from the Razorpay Dashboard.

For loca