Integration

1. Sister Services

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

Sister	Direction	Surface	Contract	Auth	Failure Mode
@nx/identity	→	HTTP JWKS (/jw-certs)	JWKSVerifierTokenService	—	token rejected if JWKS fetch fails
@nx/sale / @nx/payment	←	Kafka signal.activity-notification	TActivityNotificationMessage	—	at-least-once; no retry on handler error
@nx/sale / @nx/payment	←	Redis pub/sub (WebSocketEmitter)	{ topic, data, destination }	—	best-effort; dropped if no instance subscribed
@nx/core	→	in-process repositories	ActivityNotificationRepository, PolicyDefinitionRepository	—	DB error propagates, message not committed

Producers (@nx/sale, @nx/payment) do not host a WebSocket server. They publish through a lightweight WebSocketEmitter; Signal is the only service that owns a WebSocketServerHelper and subscribes to the bus.

2. External Systems

System	Direction	Surface	Auth	Failure Mode
WebSocket clients (POS / Admin / Tauri)	↔	WSS /stream (ECDH + AES-256-GCM)	JWT in handshake	rejected without valid JWT + clientPublicKey
Redis	↔	pub/sub (single or cluster)	password (optional)	offline queue (cluster) / retry (single)
Kafka	←	consumer (SASL optional)	SCRAM/PLAIN	broker reconnect; missing brokers → fail-fast at boot

3. Critical Cross-Service Flows

3.1 Payment success → user notification

Step	Detail
1	Producer chooses recipientScope; org/merchant are resolved server-side via PolicyDefinitionRepository, users uses recipientIds
4	The same row is also retrievable via GET /notifications; the WS push is a live hint, not the source of truth

3.2 Cross-instance / cross-service direct push

4. Contract Stability

Surface	Stability	Versioning
WS /stream handshake (type, token, clientPublicKey)	stable	none — single protocol
Kafka signal.activity-notification payload	beta	TActivityNotificationMessage shape; no version field yet
WS topic observation/signal/notification/created	beta	path-based
REST /notifications, /socket/websocket/clients	stable	URL /v1/

5. Related Pages

• API Events
• Architecture
• Decisions