Docs/billing system

[arxja]

Summary by CodeRabbit

• Documentation
  • Added new guides covering billing architecture, webhook endpoint handling, payment provider abstraction, webhook idempotency/deduplication, queue-based deferred processing, tenant billing flow, and transactional email service design.
  • Documented signature verification, 202 webhook responses, duplicate-event protection with TTL, retry/dead-letter behavior, tenant lookup/error handling, and provider extension/migration guidance.
• Chores
  • Updated repository ignore settings for internal migration notes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 15484632-3bf3-4356-b1aa-6bb062ac3f1a

📥 Commits

Reviewing files that changed from the base of the PR and between 195774a and 7e728fc.

📒 Files selected for processing (5)

• docs/guides/billing-overview.md
• docs/guides/idempotency.md
• docs/guides/queue-system.md
• docs/guides/tenant-billing-service.md
• docs/guides/webhook-endpoint.md

🚧 Files skipped from review as they are similar to previous changes (5)

• docs/guides/idempotency.md
• docs/guides/tenant-billing-service.md
• docs/guides/billing-overview.md
• docs/guides/webhook-endpoint.md
• docs/guides/queue-system.md

---

📝 Walkthrough

Walkthrough

Added documentation for a Stripe-based billing architecture, covering webhook verification, queuing, idempotency, tenant billing updates, and email notifications. Also updated .gitignore to exclude migration-to-production.md.

Changes

Billing architecture guides

Layer / File(s)	Summary
Webhook contracts and entry flow docs/guides/payment-provider.md, docs/guides/webhook-endpoint.md, docs/guides/billing-overview.md	Documents provider abstraction, Stripe signature verification, event parsing, webhook responses, and the overall billing flow.
Queue and deduplication processing docs/guides/queue-system.md, docs/guides/idempotency.md	Documents deferred processing, retries, dead-letter handling, JetQueue migration, and MongoDB-backed webhook deduplication.
Tenant billing and email handling docs/guides/tenant-billing-service.md, docs/guides/email-service.md	Documents event-specific tenant updates, tenant lookup, retry errors, email contracts, and provider selection.

Repository ignore configuration

Layer / File(s)	Summary
Migration document ignore rule .gitignore	Adds a Notes subsection and ignores migration-to-production.md.

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

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is related, but too generic to clearly convey the main billing-docs changes.	Use a more specific title such as "Add billing system documentation" or "Document Stripe-based billing architecture".

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/billing-system

---

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]

Actionable comments posted: 9

🤖 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/guides/billing-overview.md`:
- Around line 3-5: The billing documentation must not claim exactly-once
processing. In docs/guides/billing-overview.md lines 3-5, replace that wording
with a qualified deduplication or at-least-once guarantee; in
docs/guides/idempotency.md lines 3-10, either document an atomic claim/lease
mechanism or explicitly state the residual duplicate-processing risk from the
check-then-process-then-mark flow and 24-hour TTL.
- Around line 11-17: Update the architecture diagram flow around the Stripe
Webhook and Provider Abstraction so event verification/parsing occurs before
enqueueing, with the Job Queue preceding the Immediate 202 response; move the
Idempotency Guard and Tenant Billing Service after the queue to represent
asynchronous processing, while preserving the existing notification step.

In `@docs/guides/idempotency.md`:
- Around line 12-14: Update the model reference under the “MongoDB Model”
section to point to processedWebhook.model.ts instead of processedWebhook.ts,
preserving the surrounding documentation.

In `@docs/guides/queue-system.md`:
- Around line 10-13: Update the QueueAdapter.enqueue contract to return
Promise<void> instead of void, and make the JetQueue adapter and in-memory
implementation return and propagate that promise. Ensure callers can await
enqueue completion so success responses occur only after durable enqueue
succeeds and enqueue failures reach the route.
- Around line 22-23: Update the retry descriptions in
docs/guides/queue-system.md lines 22-23 and
docs/guides/tenant-billing-service.md lines 33-35 to state that jobs may execute
4 times total: 1 initial attempt plus 3 retries, while preserving the existing
backoff delays and dead-letter behavior.
- Around line 39-43: Update the migration guidance in “What stays the same” to
account for the route’s direct queue import from the in-memory module: either
require callers to switch to a stable queue factory/module import, or remove the
claim that all callers remain unchanged and document the route import change.
Keep the QueueAdapter and business-logic guidance intact.
- Around line 20-26: Update the documentation describing lib/queue/in-memory.ts
to remove the claim that its setTimeout-based execution works reliably on
Vercel. Clearly label the implementation as demo-only, note that serverless
shutdown can lose queued jobs and prevent retries or dead-letter collection, and
recommend a durable queue for deployed webhook processing.

In `@docs/guides/tenant-billing-service.md`:
- Around line 27-31: Update the missing-tenant handling in the tenant billing
event flow so lookup failures do not return successfully and get marked
processed. When no tenant is found via stripeCustomerId or client_reference_id,
either raise the established retryable error or persist the event for
reconciliation, while preserving normal processing for resolved tenants.

In `@docs/guides/webhook-endpoint.md`:
- Around line 9-11: Qualify the webhook’s 202 response in
docs/guides/webhook-endpoint.md lines 9-11 by documenting that enqueue failures
return 500. In docs/guides/billing-overview.md lines 3-5, replace the claim that
it always responds immediately with 202 Accepted to state that 202 is returned
only after successful validation and enqueueing.

🪄 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: 49008df4-1a2f-47f0-bfeb-a4eeee5e456c

📥 Commits

Reviewing files that changed from the base of the PR and between 24f4ce8 and 195774a.

📒 Files selected for processing (8)

• .gitignore
• docs/guides/billing-overview.md
• docs/guides/email-service.md
• docs/guides/idempotency.md
• docs/guides/payment-provider.md
• docs/guides/queue-system.md
• docs/guides/tenant-billing-service.md
• docs/guides/webhook-endpoint.md