Integration

Helpdesk has an unusually thin integration surface: it makes no synchronous outbound HTTP calls to sister microservices and consumes/produces no Kafka. Cross-domain data is read via repositories shipped inside @nx/core, and authentication trusts the identity issuer's JWKS.

1. Sister Services

Direction: → calls / ← called by / ↔ bidir.

Sister	Direction	Surface	Contract	Auth	Notes
@nx/identity	→	JWKS endpoint	JWT verification (VerifierApplication)	—	Verifies access tokens; never issues
@nx/core (library)	→	ProductRepository, SaleOrderRepository	in-process Drizzle reads	DB	Context enrichment reads product & sale-order rows directly from shared DB schemas

There is no Kafka topic exchange and no REST client to @nx/sale, @nx/payment, etc. The dependencies.services list in app-info.json (identity, payment, commerce, inventory, signal) is declarative metadata, not wired runtime calls.

2. External Systems

System	Direction	Surface	Auth	Failure Mode
SMTP server	→	NodemailerComponent	SMTP user/password (env)	Notification job retries (BullMQ, up to 5 attempts)
Object/file storage	↔	FileStorageHelper	per deployment	Attachment upload/fetch

3. Critical Cross-Service Flows

3.1 Ticket context enrichment (read from core repositories)

Step	Detail
2-5	No network hop — @nx/core repositories read the shared DB
6	Enriched JSON stored on Ticket.context so agents see order/product without querying other services

4. Contract Stability

Surface	Stability	Versioning
REST /v1/api/helpdesk/*	beta	URL /v1/
WebSocket observation/helpdesk	beta	topic path
In-process events (TicketEventTypes)	internal	not externally versioned
@nx/core repository reads	follows core	workspace:*

5. Related Pages

• API Events
• Architecture
• Decisions