# Resources — NATS JetStream

High-trust sources only. In-repo anchors are the ground truth for *how this repo does it*; external
links are for *the general technique* the interview will test. Never cite parametric knowledge —
every non-trivial claim in a lesson links here.

## In-repo ground truth (the primary source for every lesson)
- **`reference/repo-nats-map.md`** — the survey map: the golib client, streams (fink), consumers,
  bootstrap wiring, the learner-owned subscribers, the activity-log path, NATS-vs-Kafka, ops. Start here.
- **The client golib:** `internal/golibs/nats/jetstream.go` (the `JetStreamManagement` interface,
  publish/subscribe, `UpsertStream`/`UpsertConsumer`, `handleMsg`), `marshal.go`, `trace.go`,
  `metrics.go`, `chunk_handler.go`.
- **Streams:** `cmd/server/fink/upsert_streams_nats.go` + `cmd/server/fink/streams/*.go`.
- **Names:** `internal/golibs/constants/common.go` (`Subject*`/`Stream*`/`Queue*`/`Durable*`/`Deliver*`).
- **Bootstrap:** `internal/golibs/bootstrap/{nats.go,resource.go,monitor.go}`.
- **Subscribers (learner-owned):** `internal/conversationmgmt/modules/*/controller/nats/*`,
  `internal/notification/transports/nats/*`, `cmd/server/{conversationmgmt,notificationmgmt}/gserver.go`.
- **Activity log:** `internal/platform/activitylog/http.go`, `internal/golibs/tracer/logger.go`,
  `internal/zeus/subscriptions/activity_log_subscription.go`.
- **Ops:** `local/configs/services/nats-jetstream/nats.conf`, `deployments/helm/platforms/nats-jetstream/`.

## Core NATS (official)
- **NATS concepts — Publish/Subscribe** — https://docs.nats.io/nats-concepts/core-nats/pubsub —
  subjects, one-to-many, wildcards.
- **NATS concepts — Subjects** — https://docs.nats.io/nats-concepts/subjects — the dotted hierarchy,
  `*` (token) and `>` (rest) wildcards.
- **NATS concepts — Queue Groups** — https://docs.nats.io/nats-concepts/core-nats/queue —
  load-balanced delivery to one subscriber in the group.
- **Compare NATS (core vs JetStream, vs others)** — https://docs.nats.io/nats-concepts/overview/compare-nats.

## JetStream — persistence (official)
- **JetStream overview** — https://docs.nats.io/nats-concepts/jetstream — the persistence layer;
  at-least-once, replay, dedup, KV.
- **Streams** — https://docs.nats.io/nats-concepts/jetstream/streams — retention (limits/workqueue/
  interest), storage (file/memory), replicas, discard policy, limits.
- **Consumers** — https://docs.nats.io/nats-concepts/jetstream/consumers — push vs pull, durable vs
  ephemeral, deliver policy, filter subjects.
- **Consumer details** — https://docs.nats.io/using-nats/developer/develop_jetstream/consumers —
  ack policy, `AckWait`, `MaxDeliver`, `MaxAckPending`, deliver groups.
- **JetStream model deep dive** — https://docs.nats.io/using-nats/developer/develop_jetstream/model_deep_dive —
  the ack model (Ack/Nak/InProgress/Term), dedup window, limits & retention interplay.
- **Message deduplication (`Nats-Msg-Id`)** — https://nats.io/blog/new-per-subject-discard-policy/ and
  the model deep dive — the dedup window (default 2 min).

## The Go client (official)
- **`nats.go` JetStream** — https://pkg.go.dev/github.com/nats-io/nats.go — `Connect`, `JetStream`,
  `Subscribe`/`QueueSubscribe`/`PullSubscribe`, `AddStream`/`AddConsumer`, `msg.Ack/Nak/Term`.
- **NATS by Example** — https://natsbyexample.com/ — runnable, idiomatic patterns (limits stream,
  push/pull consumers, queue groups) in Go.

## Comparison & wisdom (technique the interview tests)
- **NATS and Kafka compared (Synadia)** — https://www.synadia.com/blog/nats-and-kafka-compared —
  the authoritative-from-the-vendor comparison; latency, ops, delivery semantics, use cases.
- **Kafka vs NATS (Aiven)** — https://aiven.io/tools/streaming-comparison/kafka-vs-nats — a neutral
  side-by-side.
- **At-most-once (core) vs at-least-once (JetStream)** — the JetStream overview + model deep dive.

## Community (wisdom — test your understanding on real people)
- **NATS Slack** — https://natsio.slack.com (invite via https://slack.nats.io) — #general, #jetstream;
  the maintainers answer here.
- **NATS GitHub Discussions** — https://github.com/nats-io/nats-server/discussions and
  https://github.com/nats-io/nats.go/discussions — consumer/stream config, ack semantics.
- **r/nats / r/golang** — https://www.reddit.com/r/golang/ — NATS-vs-Kafka and JetStream design debates.

## The interview angle
- Staples worth rehearsing against this repo's code: core NATS (at-most-once, pub/sub, queue groups)
  vs JetStream (at-least-once, streams/consumers); retention policies (why interest here); push vs
  pull consumers; the ack model (Ack/Nak/Term) and what redelivery + dedup buy you; NATS vs Kafka
  (when each); and how tenancy/tracing survive an async hop. Ground each in a real subscriber here.