Story: Document NATS: technology overview, system integration, and recipes
Table of Contents
This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
NATS is the message bus underpinning every ORE Studio service, yet it is nowhere described in the knowledge base. A developer reading component code sees NATS subjects and JetStream streams but has to trace code to understand what they do. This story fixes that gap by adding four tiers of documentation:
- A general NATS technology page in External knowledge — what NATS is, its key concepts (subjects, queue groups, JetStream), and links to upstream resources. This mirrors what we do for ORE and QuantLib.
- A NATS section in the System model describing how ORE Studio uses NATS: deployment topology, subject-naming convention, security model (TLS + JWT), and the relationship between the transport library and service runners.
- A
* NATSsection in the component overview of every component that publishes or consumes NATS subjects, with a table of subjects (name, direction, pattern, description) org-roam-linked back to the central NATS page and the system model. - A
nats/recipe topic in Recipes covering operational how-tos: inspecting live subjects, monitoring JetStream streams, tracing request/reply flows, and checking connectivity.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | Complete. |
| Waiting on | Nothing. |
| Next | None. |
| Last touched | 2026-05-28 |
Acceptance
[ ]doc/knowledge/external/nats.orgexists, describes NATS as a technology (subjects, queue groups, JetStream, security), and links to nats.io and github.com/nats-io.[ ]doc/knowledge/external/external.orghas a new "Messaging infrastructure" section linking to the NATS page.[ ]System model has a* NATSsection describing deployment topology, subject-naming convention, TLS/JWT security, and the transport/service-runner relationship.[ ]Every service component whose overview lacks a* NATSsection gets one, with a table of subjects (name, direction, pattern, description) org-roam-linked to the NATS page and system model.[ ]doc/recipes/nats/nats.org(topic index) exists and is linked fromrecipes.org.[ ]At least four NATS how-to recipes exist covering: listing live subjects, monitoring a JetStream stream, tracing a request/reply exchange, and checking NATS connectivity.[ ]All new.orgfiles carry#+version: 2and were created viagenerate_v2_doc.sh/compass add.[ ]All cross-references use[[id:UUID]]links, never relative paths.
Tasks
| Task | State | Start | End | Description |
Decisions
- PR #870 (scaffolding) review round 1: accepted "three → four tiers"
fix from gemini-code-assist; thread resolved in commit
8e6e951ce.
Out of scope
- Protocol-level message schema documentation — already captured in ORE Studio Messaging Protocol Reference.
- NATS server administration (installation, clustering, account configuration) — use upstream docs.nats.io.
- Code changes to ores.nats or any service.