Helpdesk Service

@nx/helpdesk is the customer-support microservice for the BANA platform. It owns the ticket lifecycle, SLA tracking and auto-escalation, rule-based agent assignment, a knowledge base, satisfaction surveys, and templated multi-channel notifications. It is a VerifierApplication that depends only on @nx/core and processes background work via BullMQ workers and an in-process event bus.

1. Quick Reference

Property	Value
Package	@nx/helpdesk
Code	SVC-00120-HELPDESK
Type	Microservice
Runtime	Bun
Base Class	VerifierApplication
Location	packages/helpdesk
Base Path	/v1/api/helpdesk
Dev Port	31130
Container Port	3000 (external 31130)
Snowflake ID	12
DB Schema	helpdesk (30 tables)
Roles	api, worker (RUN_MODE=worker)
Binding Namespace	@nx/helpdesk
Owner	support-team

Identity source of truth: src/resources/app-info.json (returned by getAppInfo()). The values above come from there. .env.development now carries the matching APP_ENV_APPLICATION_CODE=SVC-00120-HELPDESK (the earlier SVC-00030-HELPDESK collision with sale is resolved). Remaining drift to reconcile: APP_ENV_SERVER_PORT=31032 and APP_ENV_SNOWFLAKE_WORKER_ID=0. See Configuration.

Known issue: this package's TypeScript build currently fails (dead assignTicketUseCase reference path). See Operations → Known Issues.

2. Purpose & Scope

Included	Excluded
Ticket management (lifecycle, messages, attachments, events)	Issuing JWTs / identity (handled by @nx/identity)
SLA tracking, warning, breach, auto-escalation	Order/payment processing (read-only context from @nx/core)
Rule-based auto-assignment (agents, agent groups)	Inventory and pricing logic
Knowledge base (articles, categories, views, feedback)	Cross-service event bus (no Kafka wiring; in-process only)
Satisfaction surveys + feature-request voting	—
Templated, batched notifications (email + WebSocket)	—

3. Tech Stack

External:

Library	Purpose
@venizia/ignis	IoC container, DI, base application/controller/service, components
@venizia/ignis-helpers	Redis helper, TConstValue, TNullable, shared utilities
hono	HTTP server framework (via IGNIS)
drizzle-orm	DB access via PostgresCoreDataSource
pg	PostgreSQL driver
bullmq	Background job queues + workers
ioredis	Redis client (cache + BullMQ connection)
eventemitter3	In-process event bus
xstate	Ticket-status state machine
nodemailer	Email delivery
slugify	Article/category slug generation
zod	Request/response schema validation
lodash	Utilities

@platformatic/kafka is declared in package.json but dead — there is no Kafka producer/consumer in src/. See API Events.

Internal:

Package	Purpose
@nx/core	Only @nx/* dependency. Provides VerifierApplication, PostgresCoreDataSource, createAppConfig, bootstrapApplication, centralized Drizzle schemas/models, ProductRepository + SaleOrderRepository (for context enrichment), assertMerchantAccess, useRequestContext, ActorTypes, WebSocket/topic builders, ticket enums (TicketStatuses, TicketEventTypes, TicketPriorities).

4. Project Structure

packages/helpdesk/
├── src/
│   ├── application.ts            # HelpdeskApplication (VerifierApplication)
│   ├── index.ts                  # Entry → bootstrapApplication()
│   ├── migrate.ts                # Migration entry → bootstrapMigration()
│   ├── application/
│   │   ├── use-cases/            # Business logic (DI-registered services)
│   │   ├── services/             # Plain services (notification, compensation, …)
│   │   ├── events/               # In-process emitters + listeners
│   │   └── validators/           # AgentValidator
│   ├── components/
│   │   ├── event-bus/            # EventBusComponent (eventemitter3)
│   │   ├── queue.component.ts    # BullMQ queues + SLA cron scheduler
│   │   ├── workers/              # 6 BullMQ workers
│   │   ├── mail/                 # NodemailerComponent
│   │   └── websocket/            # ApplicationWebSocketComponent
│   ├── controllers/              # 11 REST controllers
│   ├── datasources/              # PostgresCoreDataSource binding
│   ├── models/requests/          # Zod request schemas
│   ├── repositories/             # Repository classes (schemas live in @nx/core)
│   ├── migrations/processes/     # Migration processes
│   ├── resources/                # app-info.json + email templates
│   └── shared/                   # common (keys, paths, constants), helpers, utils
├── package.json
└── tsconfig.json

5. Architecture

Detail: see Architecture.

6. Domain Snapshot

Full ERD + per-entity tables: see Domain Model.

7. Surface Summary

REST controllers (full reference rendered live from /v1/api/helpdesk/doc/openapi.json):

Controller	Base path (RestPaths)	Notes
TicketController	/tickets	Full ticket lifecycle, messages, assignment
AgentController	/agents	Support agent management
AgentGroupController	/agent-groups	Agent groups + members
TicketCategoryController	/ticket-categories	Ticket categories
TicketTagController	/ticket-tags	Tags + ticket-tag mappings
SlaController	/sla-policies	SLA policies
ArticleController	(articles)	Knowledge base articles
ArticleCategoryController	(article categories)	Article categories
AssignmentRuleController	/assignment-rules	Auto-assignment rules
FeatureRequestController	(feature requests)	Feature requests + voting
SurveyController	(surveys)	Satisfaction surveys

Live spec: /v1/api/helpdesk/doc/openapi.json. REST tables are intentionally not hand-maintained.

Async surface (full reference in API Events):

Channel	Count
Kafka in/out	0 (dead dep)
In-process events (EventBus)	ticket created / status-changed / assigned / message-created
BullMQ queues	6 (SLA monitor, escalation, assignment, notification, context-enrichment, survey-trigger)
WebSocket emissions	helpdesk observation topic

8. Components

Component	File	Purpose
Cache Redis	useCacheRedis() → BindingKeys.APPLICATION_REDIS_CACHE	Redis for cache + BullMQ connection
QueueComponent	src/components/queue.component.ts	Creates 6 BullMQ queues; schedules SLA-monitor cron
EventBusComponent	src/components/event-bus/component.ts	In-process eventemitter3 bus + handler registry
NodemailerComponent	src/components/mail/component.ts	SMTP email delivery
WorkerComponent	src/components/workers/worker.component.ts	Registers and runs the 6 BullMQ workers
ApplicationWebSocketComponent	src/components/websocket/component.ts	Real-time WebSocket delivery

9. Services

Business logic lives in use-cases (src/application/use-cases/*, registered as DI services). Plain services below provide shared cross-cutting helpers.

Service	File	One-liner
FileStorageHelper	src/shared/helpers/file-storage.helper.ts	Attachment storage helper
PermissionService	src/application/services/permission.service.ts	Helpdesk permission checks
CompensationCalculatorService	src/application/services/compensation-calculator.service.ts	SLA-breach compensation matrix
EscalationJobManagerService	src/application/services/escalation-job-manager.service.ts	Schedules/manages escalation jobs
ProcessNotificationService	src/application/services/notification/process-notification.service.ts	Resolves + dispatches notifications
NotificationBatchService	src/application/services/notification/notification-batch.service.ts	Batches/digests notifications
AgentValidator	src/application/validators/agent.validator.ts	Agent input validation

Use-cases are grouped by domain: Agent, Agent Group, Assignment, Assignment Rule, Article, Article Category, Feature Request, SLA, SLA Policy, Survey, Survey Question, Ticket, Ticket Category, Ticket Tag, plus HandleDeadLetterUseCase. See src/application.ts configureServices() for the registered set.

10. Repositories

All Drizzle schemas/models are centralized in @nx/core (packages/core/src/models/schemas/helpdesk/). This package declares repository classes only.

Group	Repositories
Ticket	TicketRepository, TicketMessageRepository, TicketEventRepository, TicketAssignmentRepository, TicketCategoryRepository, TicketTagRepository, TicketTagMappingRepository
Agent	AgentRepository, AgentGroupRepository, AgentGroupMemberRepository
SLA	SlaPolicyRepository, SlaTrackerRepository, SlaEscalationRepository
Knowledge base	ArticleRepository, ArticleCategoryRepository, ArticleViewRepository, ArticleFeedbackRepository
Survey & feature	SurveyRepository, SurveyQuestionRepository, SurveyResponseRepository, FeatureRequestRepository, FeatureVoteRepository
Notification	NotificationRepository, NotificationTemplateRepository, NotificationPreferenceRepository, NotificationDeliveryLogRepository, NotificationBatchRepository
Other	AssignmentRuleRepository, CompensationRepository, MetaLinkRepository, JobExecutionLogRepository, UserRepository, OrganizerRepository
From @nx/core	ProductRepository, SaleOrderRepository (read-only context enrichment)

11. Entry Points

File	Purpose
src/index.ts	Service entry → bootstrapApplication({ ApplicationClass: HelpdeskApplication })
src/migrate.ts	Migration entry → bootstrapMigration()
src/application.ts	HelpdeskApplication extending VerifierApplication

Run mode selected via RUN_MODE (startup API / worker / migrate).

12. Configuration

Env vars + feature flags + seeded data: see Configuration.

13. Operations

Deployment + observability + security + runbook + known issues: see Operations.

14. Related Pages

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Decisions
• REST endpoints — live OpenAPI at /v1/api/helpdesk/doc/openapi.json
• Features: Ticket System · Agent & Assignment · SLA & Escalation · Knowledge Base · Notifications