# Mission — NATS JetStream in *this* repo

## Who this is for
A backend engineer who owns **conversationmgmt** and **notification** — services that *subscribe* to
NATS JetStream events every day — and wants to genuinely understand the eventing layer they use, plus
be **interview-ready** on NATS/JetStream technique.

Strong backend maturity (17th course; the Kafka, Postgres, Auth, and CDC courses are done). **Newer
to NATS specifically**: core NATS pub/sub, the JetStream persistence model (streams, durable
consumers, acks), the `golibs/nats` wrapper, and how their own subscribers actually work.

## The mission
> *"Teach me NATS JetStream — core pub/sub through the persistence model — grounded in how this repo
> uses it, so I can catch up on the services I own and prepare for the interview."*

Two concrete targets:
1. **Catch-up fluency** — open any `RegisterNatsSubscribers`/subscriber in their services and know
   exactly what it does: which stream/consumer, which ack policy, what happens on failure, how
   tenancy and tracing survive the hop.
2. **Interview readiness** — explain core NATS vs JetStream, streams and retention, push vs pull
   consumers, the ack model, delivery semantics + dedup, and NATS vs Kafka — grounded in real code.

## The lead focus (chosen by the learner)
**Balanced: core → JetStream → repo usage.** Subjects & pub/sub first, then the JetStream persistence
model (streams, consumers, acks, replay), then the `golibs/nats` wrapper and how their services
subscribe and publish. No single layer dominates; the goal is end-to-end understanding.

## The anchor (chosen by the learner)
**conversationmgmt & notification** — the NATS code the learner actually owns. Every lesson leans on
their real subscribers (`UserCreated`, `StaffUpserted`, `UserGroupUpdate`, `Notification.Created`) and
the publisher link between the two services; the golib and streams (fink) are the supporting cast.

## What "done" looks like
- Can explain **core NATS** (subjects, wildcards, pub/sub, queue groups, at-most-once) and how
  **JetStream** adds persistence (streams, durable consumers, at-least-once, replay).
- Can read a **stream config** (retention `InterestPolicy`, storage, replicas) and say why the repo
  chose interest retention, and that streams are provisioned by the **fink** job.
- Can distinguish **push vs pull** and **durable vs ephemeral** consumers, and read the repo's
  `QueueSubscribe` (durable push queue-group) options: ack policy, `AckWait`, `MaxDeliver`, filter.
- Can trace a message through **`handleMsg`**: unmarshal the `DataInMessage` envelope, re-inject
  tenancy so **RLS survives the async hop**, run the handler, and ack / redeliver / drop.
- Can defend the **delivery semantics** (at-least-once, dedup via `Nats-Msg-Id`, redelivery via
  `AckWait`+`MaxDeliver`) — and name the gaps (no `Nak`/`Term`, no DLQ).
- Can articulate **NATS vs Kafka** in this repo, including the active NATS→Kafka migration.

## Non-goals
- Not the Kafka course (that exists) — this is the *other* bus, though NATS-vs-Kafka is taught.
- Not NATS KV/Object-store or leaf-nodes/super-clusters — the repo uses JetStream streams/consumers.
- Not exhaustive of every service's subscribers — conversationmgmt/notification generalize; the
  activity-log firehose is the one cross-cutting extra.