Jetstream Architecture

JetStream Architecture

Design NATS JetStream streams, subjects, and consumers for event streaming and worker queue architectures.

For deployment/clustering/Kubernetes questions, defer to the jetstream-deployment skill. For troubleshooting, monitoring, or performance tuning, defer to the jetstream-operations skill. If the user is building AI agents that discover and prompt each other over NATS (the Synadia Agent Protocol / Synadia Agents SDK, the agents.* subjects), defer to the nats-agent-fabric skill — that fabric runs on the NATS Services API, not core JetStream. JetStream and KV come back in only as the durable memory/handoff layer behind those agents; designing the streams or KV buckets that back agent state is this skill's job (see nats-agent-fabric/patterns/durable-state.md for the agent-specific shape).

Reference Files

Read these files when they're relevant to the user's question — don't load all of them upfront, just the ones you need:

• concepts/streams.md — stream config fields, retention policies, storage types, subject namespaces, mirroring/sourcing. Read when configuring a stream.
• concepts/consumers.md — pull vs push comparison, ack policies, deliver policies, consumer groups, ordered consumers, backoff. Read when designing consumers.
• concepts/server-features.md — which features need which server version, how to detect capability via api.level, per-message TTL, priority groups, atomic batch publish, and the 2.12 strict-mode breaking change. Read before recommending any feature newer than 2.10, and whenever a design depends on TTL, prioritised delivery, or multi-message atomicity.
• patterns/fanout.md — fanout pattern with multiple independent consumers, LimitsPolicy vs InterestPolicy, scaling. Read when the user needs multiple services consuming the same events.
• patterns/work-queue.md — work queue with competing consumers, DLQ, deduplication, priority queues. Read when the user needs task distribution or job processing.
• examples/go.md — complete Go examples using nats.go. Read when the user wants Go code.
• examples/python.md — complete Python examples using nats-py. Read when the user wants Python code.
• examples/javascript.md — complete JavaScript/TypeScript examples using the modular @nats-io/* v3 client (not the legacy nats package). Read when the user wants JavaScript or TypeScript code.

Workflow

Step 1: Gather requirements — what data is being produced, who consumes it, what are the durability and ordering needs.

Step 2: Design the subject namespace — use hierarchical subjects with wildcards for flexible routing.

Step 3: Configure the stream — choose retention policy, storage type, replicas, limits, and discard policy.

Step 4: Select consumer strategy — pull for worker queues, push for event listeners, ordered for replay.

Step 5: Configure delivery guarantees — ack policy, max deliver, ack wait, backoff, dead letter handling.

Step 6: Provide implementation code — working examples with proper error handling in the user's language.

Core Principles

• Use hierarchical subjects: {domain}.{entity}.{event} (e.g., orders.us-east.created)
• Prefer one stream per bounded context with multiple subjects over many single-subject streams
• Use pull consumers for worker queues — they allow backpressure and batch processing
• Use push consumers for real-time event listeners that need immediate delivery
• Always use AckExplicit in production — never rely on implicit acks
• Set MaxDeliver with a dead letter strategy — don't retry forever. NATS has no built-in DLQ, so "dead letter strategy" means consuming the MAX_DELIVERIES advisory yourself; MaxDeliver alone means "retry then silently drop"
• Use DuplicateWindow for publish-side deduplication (default 2 minutes). Size it against your slowest republish path: a transactional-outbox relay that retries hourly needs hours, not the default, or the dedup that prevents a double-book has already expired
• Set Replicas: 3 for production streams — R1 is only for development
• Prefer FileStorage for durability — use MemoryStorage only for ephemeral/cache streams
• Design for idempotent consumers — messages may be redelivered after ack timeout