Domain deep dive — Finance, AR & integrations

Purpose

Single D1 narrative for engineers working on accounts receivable, payment capture, and Xero / Stripe sync. It ties together:

Generated pages under Finance, AR & integrations in DocType reference
Xero and Stripe integration docs
Lee Kim module flows: Billing flow, Debt management, Xero tenant

Domain boundary

In scope	Out of scope (link instead)
Xero OAuth, tenants, invoice/contact sync, webhooks	Full ERPNext accounting curriculum
Stripe Payment Links, webhooks, Sales Invoice settlement	Stripe Connect marketplace features
Debt / collection DocTypes and Xero debt tables	Legal collections process (ops playbook)
Sales Invoice extensions, billing notes, invoice line bridges	Payroll — Payroll & HR / payroll-hr

DocType cluster (generated)

All custom tables grouped under finance-ar-integrations share one sidebar folder — use the category index as a map, not as runtime architecture.

Sub-theme	Examples (see generated pages for fields)
Xero core	`xero_api_settings`, `xero_tenants`, `xero_organization`, `xero_invoice`, `xero_contact*`, `xero_invoice_sync`
Stripe	`stripe_settings`, `default_stipe_gateway`, gateway selection vs company
AR / debt	`debt_management`, `debt_collection`, `debt_call_notification`, `xero_debt_management_table`
Bridges	`sales_invoice_billing_note`, `company_billing_note`, `invoice_services_list`, `sync_data`

Code map

Layer	Primary locations
HTTP / webhooks	`leekimerp/api/xero.py`, `leekimerp/api/stripe.py`, `leekimerp/api/stripe_webhook.py`
Routes	`hooks.py` — `website_route_rules` for Stripe short paths (Stripe); Xero whitelist entries
Hooks	`hooks.py` `doc_events` — cross-check Doc events when changing AR documents
Desk / reports	`lee_kim_alliance_erp/report/` — AR, Xero, tax-related reports (Reports catalog)

Sequence (simplified AR path)

Money and invoice truth can arrive from Desk, Stripe webhooks, or Xero webhooks — order depends on deployment. This diagram is logical, not a single guaranteed pipeline.

For a Billing-centric walkthrough (emails and Application), use Tutorial: Billing → Xero and Billing flow.

Overlay priority (for `overlays.json`)

Use this table when extending docs/doctype-overlays/overlays.json (see docs/doctype-overlays/README.md in the repository for schema and workflow). Keys are DocType folder names (snake_case).

Priority	DocType keys	Rationale
P1 — Overlays present	`xero_api_settings`, `xero_invoice`, `debt_management`, `billing` (see incorporation category), `stripe_settings`, `xero_tenants`, `sync_data`	OAuth, invoice truth, debt, payment comms, Stripe company keys, tenant routing, Sync Data caveat
P2	`xero_contact`, `xero_invoice_sync`, `default_stipe_gateway`, `sales_invoice_billing_note`, `company_billing_note`	Reconciliation and SI bridges
P3	Narrow list / child tables (`xero_invoice_items`, `ccbcc_accounts`, …)	Field tables + parent link; overlay only if support tickets repeat

After editing overlays, run npm run generate:doctypes from docs/ and commit generated doctype-reference/** if your team tracks them.

Failure modes (where to look)

Symptom	First checks
Xero OAuth / token errors	Xero API Settings, `api/xero.py` token helpers, clock skew
Webhook 401/403	Signature secrets vs dashboard; `allow_guest` handlers — Security checklist
Stripe paid but SI stale	`stripe_webhook.py`, Payment Entry, company keys in Stripe Settings
Debt workflow stuck	Debt Management doc state, Xero debt tables, Debt management
Wrong tenant / company	Xero Tenants, Company links, `xero_tenants` vs Customer mapping

Logs: Frappe Error Log, application server logs for Python tracebacks, provider dashboards (Xero/Stripe) for delivery and HTTP status.

Domain deep dive — Incorporation & application — Billing doc category and Application flows
Domain deep dive — Payroll & HR
Domain documentation strategy
Documentation upgrade roadmap
API inventory
Feature catalog — owning team column for AR features