docs(diff-api): add checkpoint tuning guidance

[tiljrd]

User description

docs(diff-api): add checkpoint tuning guidance

Summary

Adds a "Checkpoint tuning" section to the diff-api documentation explaining the performance trade-offs of different CHECKPOINT_INTERVAL values. This helps users understand how to tune the interval based on their latency vs. resource requirements.

Review & Testing Checklist for Human

• Verify the technical accuracy of the performance trade-offs described (smaller intervals = faster responses but more overhead)
• Check that the suggested ranges (100-1,000 for low latency, 5,000-10,000 for resource conservation) are reasonable
• Ensure the guidance is clear and helpful for users tuning their deployments

Notes

This documentation was added in response to user questions about what different checkpoint interval values mean for API performance and resource usage. No functional changes, documentation-only.

Link to Devin run: https://app.devin.ai/sessions/e72fee05e6bf470182b09dc6ffce468d
Requested by: Til Jordan (@tiljrd)

---

PR Type

Documentation

---

Description

• Add checkpoint tuning guidance to diff-api documentation

• Explain performance trade-offs between interval sizes

• Provide recommended values for different use cases

---

Diagram Walkthrough

flowchart LR
  A["Small Intervals (100-1,000)"] --> B["Fast /diffs/since responses"]
  A --> C["Higher CPU/disk overhead"]
  D["Large Intervals (5,000-10,000)"] --> E["Lower resource overhead"]
  D --> F["Slower responses for large jumps"]
  G["User Requirements"] --> H["Choose interval based on trade-off"]
  H --> A
  H --> D

Loading

File Walkthrough

	Relevant files
Documentation	diff-api.md Add checkpoint interval tuning guidance                                    docs/diff-api.md Add new "Checkpoint tuning" section explaining interval performance trade-offs Document smaller intervals provide faster responses but higher overhead Include recommended values for different latency vs resource scenarios +5/-0

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

No code suggestions found for the PR.