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:

  1. 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.
  2. 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.
  3. A * NATS section 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.
  4. 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.org exists, describes NATS as a technology (subjects, queue groups, JetStream, security), and links to nats.io and github.com/nats-io.
  • [ ] doc/knowledge/external/external.org has a new "Messaging infrastructure" section linking to the NATS page.
  • [ ] System model has a * NATS section describing deployment topology, subject-naming convention, TLS/JWT security, and the transport/service-runner relationship.
  • [ ] Every service component whose overview lacks a * NATS section 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 from recipes.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 .org files carry #+version: 2 and were created via generate_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.

Emacs 29.1 (Org mode 9.6.6)