Backend modules

Executive summary

The API is organized into feature modules under apps/backend/src/modules/, imported by app.module.ts: auth, admin, vendor, point-of-sale (vendor POS v2 shell), pos, health, and a small read-only public surface for unauthenticated web clients. Each controller’s @Controller('…') path is served under the global prefix /api/v1. OpenAPI (Swagger) is the authoritative contract for request/response shapes; this page maps folders → HTTP prefixes so contributors land in the right module.

---

Goals and non-goals

Goals	Non-goals
Map modules to route prefixes and main controller files	Duplicate every DTO property from Swagger here — use the Backend API catalog for the exhaustive list
Show where admin vs vendor vs POS live in the tree	Document legacy Laravel tables column-by-column
Support onboarding and code review (“is this the right module?”)	Replace integration tests or staging verification

---

Current platform behavior

Module → route prefix (after /api/v1)

Module	Role	Primary HTTP prefixes
auth	Customer / shared Laravel-style envelope	auth
admin	Admin JWT + zone/module guards	auth/admin, admin/*
vendor	Vendor JWT, catalog, finance, POS data	auth/vendor, auth/vendor/context, vendor/*
point-of-sale	Vendor POS v2 shell (JWT bootstrap only; legacy checkout unchanged)	vendor/point-of-sale
pos	POS checkout, orders, terminal payment webhook	pos, pos/payments
health	Health probe	health
public-landing	Throttled public JSON for marketing UIs	public (e.g. GET …/public/landing-settings)

Controllers by area (representative — Swagger is exhaustive)

Auth (auth)

• auth.controller.ts → @Controller('auth')

Admin (admin)

• admin-auth.controller.ts → auth/admin
• admin-dashboard.controller.ts → admin/dashboard
• admin-products.controller.ts → admin/products
• admin-orders.controller.ts → admin/orders (platform B2B admin_orders; new row ids use AUTO_INCREMENT ≥ 100000 after migration 1782470000000-AdminOrdersAutoIncrementMin100000)
• admin-zones.controller.ts → admin/zones
• admin-stores.controller.ts → admin/stores
• admin-vendors.controller.ts → admin/vendors
• admin-warehouses.controller.ts → admin/warehouses
• admin-suppliers.controller.ts → admin/suppliers
• admin-managers.controller.ts → admin/managers
• admin-roles.controller.ts → admin/roles
• admin-modules.controller.ts → admin/modules
• admin-employee-roles.controller.ts → admin/employee-roles
• admin-vendor-employees.controller.ts → admin/vendor-employees
• admin-stocks.controller.ts → admin/stocks
• admin-lots.controller.ts → admin/lots
• admin-adjustments.controller.ts → admin/adjustments
• admin-business-settings.controller.ts → admin/settings/business (store/contact + SMTP mail_* + optional marketing landing_* + admin_orders_default_tax_percent for B2B admin orders in business_settings, POST …/test-smtp)
• public-landing.controller.ts → public/landing-settings (no auth; reads landing_* + business_name from business_settings for web landing pages)

Vendor (vendor)

• vendor-auth.controller.ts → auth/vendor (login, refresh, me, profile, notifications list)
• vendor-auth-context.controller.ts → auth/vendor/context
• vendor-dashboard.controller.ts → vendor/dashboard
• vendor-products.controller.ts → vendor/products
• vendor-orders.controller.ts → vendor/orders
• vendor-finance.controller.ts → vendor/finance
• vendor-stores.controller.ts → vendor/stores
• vendor-customers.controller.ts → vendor/customers
• vendor-inventory.controller.ts → vendor/inventory
• vendor-stocks.controller.ts → vendor/stocks
• vendor-warehouses.controller.ts → vendor/warehouses
• vendor-lots.controller.ts → vendor/lots
• vendor-adjustments.controller.ts → vendor/adjustments
• vendor-categories.controller.ts → vendor/categories
• vendor-units.controller.ts → vendor/units
• vendor-attributes.controller.ts → vendor/attributes
• vendor-tags.controller.ts → vendor/tags
• vendor-suppliers.controller.ts → vendor/suppliers
• vendor-coupons.controller.ts → vendor/coupons
• vendor-roles.controller.ts → vendor/roles
• vendor-employees.controller.ts → vendor/vendor-employees
• vendor-modules.controller.ts → vendor/modules
• vendor-settings.controller.ts / vendor-settings-context.controller.ts → vendor/settings

Point of Sale v2 shell (point-of-sale)

• point-of-sale.controller.ts → vendor/point-of-sale (e.g. GET …/bootstrap for workspace metadata; does not replace pos/* checkout routes)

POS (pos)

• pos.controller.ts → pos
• pos-payment-webhook.controller.ts → pos/payments

Health (health)

• health.controller.ts → health

Examples (non-exhaustive)

• Admin: GET/POST …/admin/products, …/admin/orders, …/admin/zones, …
• Vendor: …/vendor/products, …/vendor/orders, …/vendor/finance, …/vendor/point-of-sale/bootstrap, …
• Auth: …/auth/... for shared/customer flows; …/auth/admin/*, …/auth/vendor/* for JWT issuance and related actions.

---

Sequence: happy path (contributor)

1. Identify the actor (customer vs admin vs vendor vs POS device/webhook).
2. Open the matching module folder under src/modules/<name>/.
3. Find *.controller.ts whose @Controller prefix matches the URL you need.
4. Trace service → entities/repositories; add or extend *.spec.ts for behavior changes (Backend architecture for global concerns).

---

Security and operations

• Guards differ by module: admin module keys and zone checks, vendor store scoping, POS payment verification for webhooks—never bypass in the controller without a service-level check.
• Prefer parameterized queries (TypeORM) over string concatenation; validate and sanitize DTO inputs for search filters.
• For diagrams and runbooks where behavior is not obvious from OpenAPI (webhooks, idempotency, PSP retries), add or link sequence docs—see POS payments & webhooks.

---

Test scenarios (contributors / QA)

ID	Scenario	Expected
BM1	New route in correct module	Swagger shows path under /api/v1
BM2	Change to guarded admin route	Unit/integration tests cover allow/deny
BM3	Webhook endpoint	Signature + idempotency tests where applicable

---

Related

• System test cases (index) — cross-cutting TC- ids, unhappy paths, E2E notes
• Backend architecture (NestJS) — bootstrap, globals, Throttler, ValidationPipe
• API conventions — Swagger base URL and clients
• Authentication — JWT entrypoints