docs(nats-traffic): code-verified NATS traffic & storage sizing model

[yenta]

Summary

Reworks docs/nats-traffic-estimation.md into a current, code-verified capacity model for a single site's NATS/JetStream traffic and storage. Every stream, subject, and driver is checked against pkg/stream, pkg/subject, and the service handlers; all volumes are parameterized so the model can be re-run. Documentation only — no code changes.

What the doc now contains

Inventory (§2), surveyed from code

• §2.1 JetStream streams — corrected names/subjects (ROOMS, PUSH_NOTIFICATION, HR, MIGRATION_OPLOG); OUTBOX + flat INBOX federation (outbox-worker forwards to remote INBOX); parallel BOT_* pipeline; SYSTEM stream.
• §2.2 server→client delivery — RoomEvent/UserRoomEvent, SubscriptionUpdate, RoomKeyUpdate, PresenceState; stale stream.msg / metadata.update / notification subjects removed.
• §2.3 request/reply — every registered RPC by service (client-facing + server-to-server), incl. presence R/R and lifecycle publishes.

Traffic & storage model (§3–§11)

• §4 parameters — U=20,789, F=100, message split 4.5M/day = 2.5M human + 2.0M bot, per-user rates (R_sub, R_hist, R_room, R_member, C_pres, …), plus f_fed, N.
• §6 single-connection baseline — JetStream (incl. bot + OUTBOX) ~39M ops/~36 GB; core delivery ~470M/~543 GB (message fan-out (M_room+M_bot)×F dominates); client + server-to-server R/R. TOTAL ≈ 0.52B ops/day, ≈ 0.73 TB/day.
• §7 multi-connection (D-scaling; ~2.45B/~3.50 TB at D=5), §8 migration phase (standalone), §9 storage (~9 GB; 1-day canonical retention), §10 per-fab summary (14 sites), §11 caveats.

Notes

• Federation (OUTBOX/flat-INBOX), the BOT_* pipeline, and SYSTEM are new/target design not yet in pkg/stream — the doc flags them as such.
• Volumes are capacity-planning estimates (parameterized); a few driver assumptions (f_fed≈20%, N≈3, bot fan-out, room-key rotation on member-remove, M_push=M_room) are called out inline for easy tuning.

🤖 Generated with Claude Code

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Documentation-only update to docs/nats-traffic-estimation.md aligning stream names, federation scoping, steady-state sizing, migration subject naming, storage estimates, and bot pipeline sizing with the finalized NATS/JetStream model.

Changes

NATS Traffic Estimation Doc

Layer / File(s)	Summary
Stream inventory and federation scoping docs/nats-traffic-estimation.md	Replaces the inventory text, updates federation scoping to OUTBOX→INBOX routing, and points to pkg/stream/stream.go for canonical stream definitions.
Steady-state model recalculation docs/nats-traffic-estimation.md	Updates the human traffic parameters, methodology wording, steady-state stream and delivery tables, totals, bottleneck text, and multi-device scaling results under the revised human-only baseline.
Migration and storage sizing docs/nats-traffic-estimation.md	Updates migration-phase publish subject naming, steady-state storage estimation, and per-fab traffic totals to match the revised stream identifiers and human-only split.
Caveats and bot pipeline sizing docs/nats-traffic-estimation.md	Rewrites the caveats section to state OUTBOX→INBOX exclusion rules and migration isolation, then adds the standalone bot traffic, storage, and sizing tables.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• hmchangw/chat#248: Updates the same traffic-estimation model and stream/federation assumptions in the same document.

Suggested reviewers: ngangwar962

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the documentation-only update to the NATS traffic and storage sizing model aligned with code.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/jstream-currency-subjects-j098p1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/nats-traffic-estimation.md (1)

235-240: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Rename PUSH to PUSH_NOTIFICATION here.

This is the only remaining row that uses the old/generic label, so it now reads like a different stream than the inventory and sizing tables. Keeping the name consistent avoids confusion with a non-existent PUSH stream.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/nats-traffic-estimation.md` around lines 235 - 240, The table in this
section still uses the old generic stream label, so update the `PUSH` entry in
the sizing comparison to `PUSH_NOTIFICATION` to match the inventory and other
sizing tables. Keep the wording aligned with the existing stream names used
throughout the doc so the row clearly refers to the same server-side stream and
not a separate `PUSH` stream.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/nats-traffic-estimation.md`:
- Around line 235-240: The table in this section still uses the old generic
stream label, so update the `PUSH` entry in the sizing comparison to
`PUSH_NOTIFICATION` to match the inventory and other sizing tables. Keep the
wording aligned with the existing stream names used throughout the doc so the
row clearly refers to the same server-side stream and not a separate `PUSH`
stream.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 53c5642a-eb86-4c19-96e5-f2a5f3d7aa1c

📥 Commits

Reviewing files that changed from the base of the PR and between f3a1da5 and 5e2b63d.

📒 Files selected for processing (1)

• docs/nats-traffic-estimation.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/nats-traffic-estimation.md`:
- Around line 457-462: The fenced bot pipeline diagram in the documentation is
missing a language tag, causing the MD040 lint failure. Update the diagram fence
in the NATS traffic estimation doc to use the existing diagram content with a
text language label, and keep the block otherwise unchanged so the Markdown
linter recognizes it correctly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 780aa051-b357-42f8-aff5-defdbd0fde2f

📥 Commits

Reviewing files that changed from the base of the PR and between 1134ed9 and feee53d.

📒 Files selected for processing (1)

• docs/nats-traffic-estimation.md