docs: Billing system overview for external billing migration

[bengotow]

Summary

• Adds a comprehensive overview document (docs/billing-system-overview.md) cataloging all billing-related code in the application
• Documents the current architecture (IdentityStore, BillingModal webview, FeatureUsageStore quota enforcement), all UI entry points that trigger billing actions, and the component/URL inventory
• Includes migration considerations for moving from in-app webview billing to external browser-based billing with feature flag gating

Test plan

• Review document for accuracy and completeness
• Confirm all referenced files and line numbers are correct
• Validate that no billing-related code paths were missed

Generated with Indent - session link

[indent-staging]

Issues

No issues found.

Resolved (1 issue)

• The Send Reminders feature ID is listed as reminders but the actual codebase uses send-reminders (resolved from PLUGIN_ID in send-reminders-utils.ts). This could mislead a developer implementing the migration. (fixed by commit 7fa26b3)

Summary

This PR adds a comprehensive documentation file (docs/billing-system-overview.md) that catalogs all billing-related code in Mailspring to support a planned migration from in-app billing modals/webviews to an external browser-based billing flow. No runtime code is changed.

• Adds a 209-line reference document mapping the billing system architecture, key files with line numbers, entry points, billing URLs, and component registrations
• Documents all 8 feature quota paywall entry points and their feature IDs
• Includes a migration plan section outlining points of change, what stays the same, and what can be removed after full migration

CI Checks

No CI checks have been reported for this PR.

Rule Checks 3 rules evaluated, 3 passed, 0 failed

Passing rules

This is a longer title to see what happens when they are too long to fit
B
Ben Rule

[ShubhamDeshmuk-h]

This is strong, high-quality documentation overall, but a few important areas need to be addressed before merging to ensure production readiness and avoid gaps during migration.

1. Missing Failure & Edge Case Handling

The document currently assumes a happy path only. Please include handling for key edge cases such as:

User closes the browser without completing payment
Payment failure scenarios
Expired SSO URLs
Network failures during fetchIdentity()
Multiple tabs or repeated upgrade clicks

Without these, the migration flow may lead to inconsistent billing states or unresolved UI flows.

2. Weak Definition of Foreground Detection

The document mentions:

"App foreground listener — New code needed"

However, there are no implementation details. This is a critical part of the new flow and needs to be clearly defined.

Please include:

Which Electron APIs will be used (e.g., app.on('browser-window-focus'), visibilitychange)
Debounce or throttling strategy to avoid excessive calls
Safeguards to prevent duplicate fetchIdentity() calls
3. Missing Security Considerations

Since billing involves sensitive flows, a security section is required. Currently, there is no mention of:

SSO token expiration and validity window
Risks of SSO URL leakage (logs, sharing, etc.)
Trust assumptions when redirecting users to an external browser

Adding this will ensure the migration is aligned with secure practices.

Addressing these points will make the document significantly more robust.