Documentation

Architecture

A developer-oriented map of SaleX: how a request travels through the app, where business logic lives, and how the main subsystems fit together.

On this page

Stack

Next.js 16 (App Router) with React 19 and TypeScript, Tailwind CSS, Prisma on PostgreSQL (Supabase, Neon or self-hosted), NextAuth credentials sign-in, Nodemailer SMTP, Sharp for images. Details are in Project Overview.

Request flow

Browser
  │
  ▼
Next.js (src/app)  ── pages, layouts, route handlers (API)
  │
  ▼
Feature modules (src/modules/<feature>)  ── validation, business rules
  │
  ▼
Prisma client (src/generated)  ──►  PostgreSQL (Supabase)
  │
  └─► External: payment gateways, SMTP, AI provider, optional Redis

Pages and API routes stay thin; rules such as shipping precedence, auction bidding increments or commission maths live in the matching module so they can be tested (Vitest) independently of the UI.

Folder responsibilities

PathResponsibilityEdit?
src/appRoutes: storefront, /admin, /vendor, /account, /pos, /ai, API handlersYes — layout and copy
src/componentsReusable UIYes
src/modulesFeature logic, one folder per feature (about 77)Carefully
src/libShared helpers: currency formatting, CSRF and similarCarefully
prisma/Schema and ordered migrationsSchema only, via db:migrate in development
src/generatedGenerated Prisma clientNever
storage/Uploaded media (local mode)Back up, do not commit

Roles and access

Operating mode (MULTI_VENDOR or SINGLE_VENDOR) is a platform setting that hides vendor-specific UI without changing the data model.

Multi-vendor order model

  1. The cart can hold items from many vendors.
  2. At checkout, items are grouped per vendor. The shipping engine matches the address to a zone and quotes each vendor separately.
  3. One customer order is created with per-vendor sub-orders and shipments. Shipping charges are stored as immutable snapshots.
  4. Vendor earnings = sub-order total minus commission; refunds reduce earnings.
  5. Shipment status changes are validated and logged with the actor.

Prices are stored as integer minor units in the platform currency and are not auto-converted.

Payments and webhooks

Gateways are configurable providers (Stripe, PayPal, SSLCOMMERZ, bKash, Nagad, Razorpay, Cash on Delivery). Redirect flows return the customer to the store, but webhooks are the source of truth for marking an order paid. Credentials can come from the admin panel (database, wins) or .env (fallback). Payment credentials in the database are stored encrypted and never sent to the browser.

Configuration layers

LayerHoldsChange needs
.envDatabase URLs, AUTH_SECRET, infrastructure and fallback credentialsRestart
Admin settings (database)Store identity, currency, gateways, shipping, taxes, commissionNothing, immediate
CodeLayout, copy, new behaviorRebuild and restart

Extending SaleX safely