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)

Identify the actor (customer vs admin vs vendor vs POS device/webhook).
Open the matching module folder under src/modules/<name>/.
Find *.controller.ts whose @Controller prefix matches the URL you need.
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

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