Per-module documentation template

Every sub-module doc under domains/<domain>/<sub-module>.md follows this skeleton. Style reference: zerp-be/docs/inventory-stock-flow.md. Be code-accurate, cite file paths, prefer real enum/schema snippets over prose. Omit a section only if it genuinely does not apply (say "N/A" with one line of why).

—

One-paragraph framing: "The whole reduces to …". State the single core idea.

Source: BE src/modules/<path> · Admin src/modules/<path>

1. Purpose & scope

What this module is responsible for, where it sits in the system, what it explicitly does NOT do.

2. Data model

For each schema/collection:

  • Collection name, what it represents.
  • Field table: field | type | required? | description (incl. refs to other collections, defaults, indexes).
  • Enums (paste the actual enum with values).
  • Relationships (FK refs, embedded vs referenced), soft-delete behavior, tenant/branch scoping.
  • Derived/computed fields and how they're computed.
// paste the real schema/enum shapes (trimmed to the meaningful fields)

3. API surface

  • GraphQL queries / mutations / resolve-fields: name, args (input DTO shape), return type, auth.
  • REST controllers (if any): method, route, body, response.
  • Pagination inputs/outputs where relevant.
Operation Type Input Returns Permission

4. Business rules & calculations

  • Validation rules (class-validator decorators + service-level invariants).
  • Formulas / algorithms (costing, payroll, depreciation, tax, totals) — write the actual math.
  • Status / state machine: allowed states and transitions (diagram if non-trivial).
  • Side effects (what else writes when this writes: GL legs, stock ledger, notifications, audit).
  • Transactionality (what runs in a single Mongo session).

5. Permissions

  • Required permission module(s) + action(s); guards/decorators used.
  • CASL abilities or role gates, if any.

6. Flows

Step-by-step for each primary flow: admin screen → GraphQL op → service → repository → DB, with side effects called out. Number the steps. Include the unhappy paths (validation failure, approval rejection, reversal/void).

7. Admin UI

  • Pages/routes (zerp-admin/src/pages/...) and the module screens.
  • Key components (tables, forms, modals), the Formik/validation schema, and the context.tsx methods that drive data (xxxPage, createXxx, updateXxx, deleteXxx).
  • Notable UX behaviors (inline create, import, print/PDF, filters).

8. Dependencies & integrations

  • Other modules this calls / is called by (and why).
  • Events emitted/consumed, cron/jobs, external services (S3, mail, zoom, etc.).

9. Gotchas & project-specific rules

  • Anything non-obvious: timezone date-range rule, FIFO layers, multi-tenant edge cases, known TODOs.