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
| Path | Responsibility | Edit? |
|---|---|---|
src/app | Routes: storefront, /admin, /vendor, /account, /pos, /ai, API handlers | Yes — layout and copy |
src/components | Reusable UI | Yes |
src/modules | Feature logic, one folder per feature (about 77) | Carefully |
src/lib | Shared helpers: currency formatting, CSRF and similar | Carefully |
prisma/ | Schema and ordered migrations | Schema only, via db:migrate in development |
src/generated | Generated Prisma client | Never |
storage/ | Uploaded media (local mode) | Back up, do not commit |
Roles and access
- Customer — storefront and
/account. - Vendor —
/vendor, after admin approval. The server restricts them to their own products and orders regardless of what the UI shows. - Admin / staff —
/admin, gated by granular RBAC permissions.
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
- The cart can hold items from many vendors.
- At checkout, items are grouped per vendor. The shipping engine matches the address to a zone and quotes each vendor separately.
- One customer order is created with per-vendor sub-orders and shipments. Shipping charges are stored as immutable snapshots.
- Vendor earnings = sub-order total minus commission; refunds reduce earnings.
- 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
| Layer | Holds | Change needs |
|---|---|---|
.env | Database URLs, AUTH_SECRET, infrastructure and fallback credentials | Restart |
| Admin settings (database) | Store identity, currency, gateways, shipping, taxes, commission | Nothing, immediate |
| Code | Layout, copy, new behavior | Rebuild and restart |
Extending SaleX safely
- Change the schema in development with
npm run db:migrate, commit the generated migration, and ship it withnpm run db:deployin production. Never edit existing migration files. - Add new features as a new folder under
src/modulesso updates from the author merge cleanly. - Keep your customizations in a Git repository, so you can diff against a new SaleX release. See Updates & Upgrading.
- Courier integrations implement the provider adapter interface (serviceability, quotes, booking, labels, tracking, webhooks).
- Media on serverless hosts requires replacing the upload handler with an object-storage one. See Supabase Setup.