Backend architecture

Clients
  pnxt-admin
  pnxt-warehouse
  marketplace, courier, and Meta webhooks
        |
        v
HTTP + WebSocket
  controllers, guards, pipes, interceptors
  default URI version v1
        |
        v
Feature services inside area modules
  identity | commerce | operations | finance | automation
        |
        +--> Prisma via DatabaseService and the tenancy extension
        +--> OutboxEvent rows inside the same DB transaction
        +--> Bull queues in Redis
        |
        v
Worker
  Bull processors
  OutboxDispatcherService (SKIP LOCKED, then EventEmitter2)
        |
        v
src/integrations
  marketplace and courier adapters
  credential vault on IntegrationConnection

HTTP shell

Configured in src/main.ts:

• Global ValidationPipe with transform, whitelist, and forbidNonWhitelisted.
• Helmet. Content-Security-Policy is skipped for /mcp/playground.
• Compression is off unless app.http.enableCompression is set.
• CORS from config. trust proxy is 1.
• Body parser limit from config (API_HTTP_BODY_LIMIT, example 10mb).

Global guards, in order, from src/common/request: ThrottlerGuard, JwtAccessGuard, RolesGuard, WarehouseGuard, PermissionsGuard. TenantScopeGuard runs when @TenantScoped is present. The audit interceptor emits audit.log when @AuditLog is present.

Shared infrastructure

Folder	Role
src/common/config	validateEnvironment. Domain code uses ConfigService
src/common/database	DatabaseService wraps Prisma
src/common/auth	Passport JWT access and refresh, permissions, platform roles
src/common/outbox	Writer and dispatcher
src/common/cache	Redis cache and import checkpoints
src/common/aws	S3 client
src/common/file	Presigned upload and download
src/common/logger	nestjs-pino
src/common/monitoring	Prometheus, Terminus, Bull Board
src/common/mcp	@hmake98/nest-mcp. Compose sets MCP_WS_PORT=3002
src/common/response	ResponseExceptionFilter
src/instrument.ts	Sentry initialization

Integration discovery

IntegrationAutoRegistrationService discovers courier strategies by duck typing (integrationCode, ship, cancel, track) and marketplace capabilities by class-name regex:

Shopify|WooCommerce|Amazon|Flipkart|BigCommerce|Meesho plus Order|Catalog|Customer|Settlement|OutboundOrder|Inventory|WebhookHealth.

A marketplace is registered only when both an order service and a catalog service were discovered. Incomplete handlers are logged and skipped. WHATSAPP and CUSTOM are seeded channel types. WhatsApp ordering is implemented under the WhatsApp agent, not by that regex.

Workspace README versus the code

The workspace README says asynchronous events are dispatched via Bull workers. The outbox dispatcher is a poller on the worker (OutboxDispatcherService), separate from Bull. Bull is the second async mechanism. Both exist. See Async processing.