Platform Phase A Built
Status: Built · Owner: Platform / Signal squad · Phase: 2 · Last reviewed: 2026-06-15
Chain Link Roadmap Phase 2 URD URD PRD PRD-ACT-001 · PRD-AST-001 · PRD-IDX-001 Decisions (ADR) - Plan - Dev docs @nx/signal Runbook Operations Delivery log Traceability matrix
Platform is KICKO's cross-cutting realtime backbone. It turns a noteworthy domain activity - a payment clearing, an order completing - into a durable, per-person notification and pushes it to the right user's screen the instant it happens, over a private, end-to-end-encrypted channel. Services produce activities; the platform decides who hears about them and delivers them live.
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-16 |
| Tier | Core |
| Status | Built |
| Phase | P2 |
| Priority | HIGH |
| Primary users | Owner, Manager, Staff, Platform operator |
2. Purpose & Scope
| Included | Excluded |
|---|---|
| Event-driven activity-notification pipeline (consume → resolve → render → persist → push) | Email / SMS / push-notification channels |
| Recipient resolution by organization / merchant / explicit-user scope | Per-user notification preferences, mute, or subscriptions |
| Self-scoped notification read API (list, count, mark-one-read, mark-all-read) | The producing services' own activity logic |
| Authenticated, end-to-end-encrypted realtime WebSocket delivery | Notification bell / activity-feed UI styling |
| Stable per-recipient room + topic contract, cross-instance fan-out | Cross-tenant room authorization hardening (known follow-up) |
| Administrative transport controls (status, list, send, broadcast, disconnect) | - |
3. Capabilities
| Capability | What the user can do |
|---|---|
| Activity-notification pipeline | Turn an activity event into one durable notification per resolved recipient |
| Scoped recipient resolution | Fan one activity out to an organization, a merchant, or an explicit user list (actor fallback) |
| Self-scoped read API | List, count (incl. unread), mark-one-read and mark-all-read - only your own notifications |
| Live push | Receive a new notification on your private channel the instant it is created |
| Encrypted transport | Connect over an authenticated (JWT) socket with ECDH key exchange and end-to-end encryption |
| Cross-instance delivery | Be reached wherever your socket is connected, via Redis-backed fan-out |
| Resilient delivery | Keep every notification durably even if your socket is down; read it later via the API |
| Admin transport controls | Inspect connection status, list / get clients, broadcast, send-to-room / client, disconnect |
4. Module Dependencies
| Depends on | Why |
|---|---|
| Commerce | Organization / merchant membership drives recipient resolution |
| Permissions | Membership lookup for scope; admin transport controls are permission-gated |
| Payment & Transaction | First live activity source (PAYMENT_SUCCESS) |
| Device | Device monitoring surfaces activity over this same backbone |
5. Backend Packages
Implementation detail lives in the developer docs - this section only maps the module to the services that power it.
| Package | Role | Developer docs |
|---|---|---|
@nx/signal | The realtime edge - activity-notification consumer, worker, socket-event service, rooms / topics, REST read API, admin transport controls | signal |
@nx/core | Owns the ActivityNotification schema / model / repository, recognized event-type registry, activity-stream topic + message types, recipient resolution | core |
Engineering Mapping (Feature ⇄ Package)
The horizontal axis of the Feature Spine - each business feature (
<AREA>in the URD) maps to its engineering home. Reciprocal: the package docs link back here.
| Feature | Dev package | ADRs | Status |
|---|---|---|---|
ACT Activity Notifications | @nx/signal · @nx/core | - | Built |
WSS Realtime WebSocket Stream | @nx/signal | - | Built |
6. Key User Flows
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Owner / Manager | Receive and read their own notifications; see org / merchant activity live | Read another user's notifications |
| Staff / Cashier | Receive, list, count, and mark read their own notifications | Read or mutate another user's notifications |
| Platform operator | Inspect connection status, list / get clients, broadcast, send-to-room / client, disconnect (permission-gated) | - |
8. Status & Roadmap
| Phase | Capabilities |
|---|---|
| P2 | Activity-notification pipeline, scoped recipient resolution, self-scoped read API, encrypted realtime push, cross-instance delivery, admin transport controls |
| Future | Additional activity event types, room-authorization hardening, additional delivery channels (email / SMS / push) |
9. Related Pages
- URD
- PRDs - PRD-ACT-001
- Related: Device · Payment & Transaction
- Developer: @nx/signal · @nx/core