# Feature Specification: Messaging Layer Replacement with NATS

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

**Feature Branch**: `006-messaging-nats-replacement`  
**Created**: 2026-03-31  
**Status**: Planned  
**Input**: Transition delta from `005-postgres-database-replacement`

## User Stories

*   As a service developer, I want backend eventing to use a robust protocol-native broker instead of Socket.IO conventions.
*   As a frontend developer, I want real-time updates to keep working through ingress using a documented WebSocket path.
*   As a maintainer, I want messaging topics/contracts documented so cross-language implementations stay consistent.
*   As an operator, I want local and Compose startup for messaging to remain simple.

## Functional Requirements

*   FR-701: The architecture SHALL replace Socket.IO-based `trade-feed` with `nats-broker` as the messaging backbone.
*   FR-702: Trade submission flow SHALL continue publishing new-trade events consumed by trade-processor.
*   FR-703: Trade-processor SHALL continue publishing account-scoped updates consumed by frontend clients.
*   FR-704: Existing user-visible baseline flows from state `005` (trade submit, blotter/position updates, account workflows) SHALL remain behaviorally compatible.
*   FR-705: Subject naming and event payload contracts SHALL be documented in `system/messaging-subject-map.md`.
*   FR-706: Migration path SHALL document backend client replacement strategy and frontend `nats.ws` migration.
*   FR-707: Realtime position updates in the frontend SHALL preserve baseline aggregate blotter behavior by updating an existing row in place for the same security key.

## Non-Functional Requirements

*   NFR-701: Broker runtime SHALL use a lightweight NATS container image suitable for local Compose development.
*   NFR-702: Broker connectivity SHALL support Java, .NET, Node.js, and Python clients used in TraderX states.
*   NFR-703: Browser streaming SHALL be supported through NATS WebSocket endpoint via ingress proxying.
*   NFR-704: Messaging topology SHALL support wildcard subscription patterns for account-scoped streams.
*   NFR-705: Architecture SHALL remain incrementally extensible for optional JetStream durability in future states.
*   NFR-706: This state SHALL preserve state `005` ingress and compose simplicity constraints unless explicitly changed.
*   NFR-707: When replacing Socket.IO `trade-feed` with NATS, generation SHALL prune legacy `trade-feed` runtime/component artifacts from this and descendant states unless a later approved state spec explicitly restores them.
*   NFR-708: Post-prune state outputs SHALL not contain stale runtime harness references that imply `trade-feed` remains active (for example legacy component links under `generated/code/components`).

## Success Criteria

*   SC-701: Compose-level NATS service and ingress websocket proxy snippets are present in `system/`.
*   SC-702: Spec pack includes migration guidance for backend and frontend client cutover from Socket.IO.
*   SC-703: Conformance and smoke requirements for messaging replacement are documented.
*   SC-704: Generation hook and smoke script paths exist for state `006`.
*   SC-705: Frontend position blotter realtime updates do not create duplicate rows for the same security.
*   SC-706: Generated outputs for state `006+` exclude legacy `trade-feed` component directories/symlinks and fail generation if those artifacts persist post-prune.