Start guide — documentation map & code reading order

Purpose

Single entry point for developers taking over the codebase: where to read first, how docs map to folders, and how requests and batch jobs flow through Frappe and custom code.

Who this is for

• Backend engineers familiar with Python and ideally Frappe / ERPNext.
• Anyone who needs to change integrations (Xero, Stripe, DocuSign), payroll hooks, or Lee Kim–specific DocTypes.

Documentation map (IA)

This site is grouped into Start, Tutorial, Reference, and Operations. Use Reference for facts and schema; use Tutorial for guided paths and scenarios.

Repository layout (high level)

The Git repo root contains the Frappe app leekimerp/ and this docs site under docs/. A separate socket.io stack may live at repo root (sockets/ / package.json); see Socket.io realtime.

Suggested reading order (first week)

Details: Reading order & code map.

How a Desk / HTTP request reaches your code

How Billing can link to Xero (conceptual)

End-to-end touchpoints span Billing, Sales Invoice, custom Xero helpers, and webhooks. See the full walkthrough: Scenario: Billing → Xero.

First-week onboarding (day-by-day)

Use this as a default ramp; your tech lead may reorder by business priority.

Day 1 — Orientation and safety

• Read Reference vs implementation so you know where the commercial template ends and repo facts begin.
• Skim Platform primer and confirm your local Bench can run the app (Deployment & operations).
• Open leekimerp/hooks.py and note: doc_events, scheduler_events, after_migrate, and any override_doctype_class entries — these are extension points you will touch again.
• Do not change production integration keys on day one; use UAT or read-only inspection.

Day 2 — Data model and boundaries

• Read System overview and System context.
• Open Custom DocTypes & data and ER diagrams by domain; pick one domain (e.g. finance AR) and trace it in the DocType reference.
• Understand the split between standard ERPNext DocTypes (Customer, Sales Invoice, …) and Lee Kim DocTypes under lee_kim_alliance_erp/doctype/.

Day 3 — Integrations

• Deep-read Xero, Stripe, and Singpass — even if you do not work on all three, they illustrate webhook + OAuth + guest API patterns used elsewhere.
• Cross-check Whitelisted API inventory for allow_guest=True surfaces; file follow-ups if production exposure is unclear.

Day 4 — Hooks, overrides, and jobs

• Read Doc events, Schedulers, and DocType overrides — overview.
• Trace one business flow end-to-end using Scenario: Billing → Xero or Business logic flows.

Day 5 — Operations and handover hygiene

• Read Operational runbook and Environment & integration matrix.
• If you are the inheriting lead, walk through Handover completion checklist with your team.

Documentation vs code — how to resolve drift

Situation	Action
Doc says a method exists; grep does not find it	Search leekimerp/api/ for renames; update docs or log an ADR if behavior intentionally changed (Architecture decisions).
DocType field table differs from Desk	Prefer JSON in repo (*.json under doctype/) over static HTML; regenerate DocType reference if your pipeline supports it.
Integration behavior changed with ERPNext upgrade	Add an ADR; re-run integration tests and attach Test evidence.

Environment variables and config (conceptual)

Frappe sites rarely use a single .env file for everything. Typical patterns:

Layer	Where names appear	Notes
Bench / site	site_config.json	DB, encryption key, sometimes integration secrets
App DocTypes	Xero / Stripe / DocuSign / Singpass settings	Often per-company or per-site
Docs build only	PUBLIC_SITE_URL for Astro	Not used by ERP runtime

Never commit secrets. Use Environment matrix as the checklist of what exists, not values.

First “safe” change (suggested)

Pick a read-only task first: e.g. add logging around an integration branch in UAT, or extend a DocType list view filter with QA sign-off. Avoid schema changes and guest API changes until you understand Security checklist.

Risk areas for new maintainers

Area	Risk	Mitigation
Guest HTTP APIs	Abuse, data leakage	Inventory + network controls + rate limits
Webhooks (Xero, Stripe)	Signature mismatch, duplicate processing	Idempotent handlers; monitor Error Log
Scheduler jobs	Silent failure, duplicate emails	Monitor job logs; test in staging
DocType overrides	Break on ERPNext upgrade	Pin versions; read upstream diffs

Where to go next

Goal	Page
Frappe vs ERPNext vs this app	Platform primer
System context (runtime + docs site)	System context
Sidebar groups → features & code	Feature inventory by category
Link-level ERD (Mermaid)	ER diagrams by domain
Which diagrams to add next	Diagram roadmap
Step-by-step code paths	Reading order & code map
Field-level schema	DocType reference
Naming rules for docs	Documentation conventions
DocType documentation strategy	Domain documentation strategy