chore: write/update docs

[MasterPtato]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Error			Nov 14, 2025 2:41am

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 14, 2025 2:41am
rivet-inspector	Ignored	Preview		Nov 14, 2025 2:41am
rivet-site	Ignored	Preview		Nov 14, 2025 2:41am

[MasterPtato]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(udb): update backoff algo #3469
• chore: write/update docs #3468 👈 (View in Graphite)
• chore: add debug scripts #3467
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Documentation Updates

Summary

This PR adds valuable documentation for the actor lifecycle and serverless flows while removing an outdated script reference from CLAUDE.md. Overall, this is a positive contribution to the project's documentation.

Positive Aspects

✅ Clear Visual Documentation: The Mermaid sequence diagrams effectively illustrate complex system interactions
✅ Comprehensive Coverage: Both ideal and edge-case scenarios are documented ("Messy Serverless Flow")
✅ Good Organization: Separate files for different concerns (actor lifecycle vs serverless flows)
✅ Cleanup: Removed reference to outdated update_workspace.ts script

Suggestions for Improvement

1. Missing File Extension in CLAUDE.md (Line 111)

The removed line references a non-existent file path. Consider verifying if this script removal is intentional or if documentation elsewhere needs updating.

2. Documentation Clarity

ACTOR_LIFECYCLE_FLOW.md:

• Line 28: A->>U: appears incomplete - should specify what is returned to the user (e.g., A->>U: 201 Created (actor_id))
• Lines 40-41, 44-45: Empty message arrows (RWF->>RWS: and RWS->>RWF:) could benefit from labels describing what's being communicated
• Consider adding a brief introduction paragraph explaining what this diagram represents and when to reference it

SERVERLESS_FLOW.md:

• Lines 68-83: Commented-out Mermaid code should either be removed or have a comment explaining why it's kept
• Line 95: Commented participant (%% participant A as API) - remove if unused
• Multiple empty message arrows throughout - consider labeling them for clarity
• The "Messy Serverless Flow" diagram is quite complex. Consider:
  • Adding numbered steps or annotations
  • Breaking into multiple smaller diagrams
  • Adding a summary table of edge cases handled

3. Missing Context

Consider adding:

• A top-level README in docs/engine/ explaining the documentation structure
• Links between related documents
• Glossary for abbreviations (AWF, RWF, RWS, etc.) or expand them on first use
• When to use each diagram (troubleshooting guide, onboarding, etc.)

4. Mermaid Syntax Consistency

The diagrams use consistent theming (theme: mc, look: classic) which is good, but consider:

• Adding version comments if specific Mermaid features are required
• Testing rendering in common viewers (GitHub, GitLab, VS Code)
• Some empty arrows might not render clearly in all viewers

Minor Issues

• Line consistency: Both files end without trailing newlines (which is fine, but verify your .editorconfig preferences)
• Commenting style: Mix of %% comments and uncommented sections in SERVERLESS_FLOW.md

Testing Recommendations

Since these are documentation files:

1. Verify Mermaid diagrams render correctly on GitHub
2. Review with team members unfamiliar with the system to ensure clarity
3. Validate that the flows match current implementation

Verdict

LGTM with suggestions - The documentation adds significant value. The suggestions above are mostly about polish and clarity rather than blocking issues. Consider addressing the empty message arrows and adding contextual documentation before merging.

---

Review generated with assistance from Claude Code

[claude]

PR Review: Documentation Updates for Rivet Engine

This PR adds comprehensive documentation for key Rivet engine components. The documentation is well-structured and provides valuable insights into the system architecture. Here's my detailed review:

Strengths

Excellent Visual Documentation

• The Mermaid sequence diagrams in ACTOR_LIFECYCLE.md and SERVERLESS.md provide clear visualizations of complex workflows
• The "Messy Serverless Flow" diagram is particularly valuable as it documents edge cases and race conditions that developers need to understand

Comprehensive Coverage

• Documents critical components: Guard (routing/proxying), actor lifecycle, hibernating websockets, runner shutdown, and serverless flows
• The terminology document provides a helpful reference for understanding abbreviations used throughout

Clear Structure

• Documentation is well-organized in docs/engine/ directory
• Cross-references between docs (e.g., GUARD.md → HIBERNATING_WS.md) help readers navigate

Issues & Suggestions

1. Empty Documentation Files

Severity: Medium

Three files are created but left empty:

• docs/engine/ACTOR_KV.md
• docs/engine/GASOLINE.md
• docs/engine/GATEWAY.md

Recommendation: Either add content to these files or remove them from this PR. Empty files can be confusing for readers. Based on the existing docs:

• GASOLINE.md should document the workflow engine mentioned in CLAUDE.md
• GATEWAY.md appears to be a duplicate concept with GUARD.md - clarify the distinction or merge

2. Typo in HIBERNATING_WS.md

Severity: Low

Line 25:

- When a runner receives a CommandStartActor message via the runner protocol, it contains information about which hiberating requests are still active.

Should be: hibernating (not hiberating)

3. Inconsistent Terminology

Severity: Low

GUARD.md line 8 uses "Gateway" in the title "Rivet Guard" context, but the document differentiates between Guard and Gateway. From reading the docs:

• Guard = HTTP routing/proxying layer
• Gateway = Used in sequence diagrams as a participant (appears to be the same as Guard?)

Recommendation: Add clarification to TERMINOLOGY.md about Guard vs Gateway distinction, or use consistent naming in diagrams.

4. CLAUDE.md Change Context Missing

Severity: Low

The PR removes these lines from CLAUDE.md:

# When adding a new package to the workspace
deno run -A scripts/cargo/update_workspace.ts

Question: Is this script no longer needed, or was this workflow changed? Consider adding a commit message explanation or updating relevant documentation if the workflow changed.

5. Incomplete Step in HIBERNATING_WS.md

Severity: Low

Line 14 (step 9) starts with a bare numbered list without context:

9. 
	- If the actor is awoken from any other source...

Recommendation: Add a brief intro sentence after "9." like:

9. When the websocket is hibernating, the following can occur:
	- If the actor is awoken from any other source...

6. SERVERLESS.md Commented-Out Code

Severity: Low

Lines 68-83 in "Ideal Serverless Flow" contain commented-out Mermaid code for actor sleep flow.

Recommendation: Either:

• Uncomment if this flow should be documented
• Remove if it's not part of the "ideal" flow
• Add a comment explaining why it's omitted (e.g., "Actor sleep flow omitted for clarity - see Messy Serverless Flow")

Minor Suggestions

1. GUARD.md line 36: "is websocket" → "its websocket"

   - The runner sends HTTP responses and websocket messages back to Rivet through is websocket via the runner protocol

2. Cross-reference consistency: Consider adding a header comment in each file linking to related docs, e.g.:

   # Hibernating Websockets
   
   Related: [GUARD.md](GUARD.md), [ACTOR_LIFECYCLE.md](ACTOR_LIFECYCLE.md)

3. RUNNER_SHUTDOWN.md: Consider adding a sequence diagram similar to other docs for visual consistency

Performance, Security & Testing

Not Applicable: This PR only adds documentation files, so there are no code changes to review for performance, security vulnerabilities, or test coverage.

Summary

This is a valuable documentation addition that will help developers understand Rivet's complex distributed actor system. The main action items are:

1. ✅ Fix the typo: "hiberating" → "hibernating"
2. ✅ Fix the grammar: "through is websocket" → "through its websocket"
3. 🔧 Decide whether to add content or remove empty .md files
4. 📝 Clarify Guard vs Gateway terminology
5. 🧹 Clean up commented-out Mermaid code in SERVERLESS.md

Overall: Approve with minor changes recommended

Great work documenting these complex flows! 🎉