Zerp — System Requirements Documentation Spec

Goal: A complete, rebuild-grade requirements documentation set for the zerp ERP (backend zerp-be + admin zerp-admin), organized by domain → module → flow. Detailed enough that an engineer could rebuild the system from these docs alone.

Source of truth

Repo Path Role
zerp-be /Users/sabiridwan/Projects/zerp/zerp-be NestJS 9 + Apollo GraphQL (code-first) + MongoDB (Mongoose 6). ~37 modules.
zerp-admin /Users/sabiridwan/Projects/zerp/zerp-admin Next.js admin (React Context + Apollo Client). ~45 modules.

Key reference inputs (mine these for business rules):

  • zerp-be/CLAUDE.md, zerp-admin/CLAUDE.md — architecture standards.
  • zerp-be/docs/inventory-stock-flow.md — the canonical style reference for rebuild-grade docs.
  • zerp-be/docs/superpowers/plans/*.md and zerp-admin/docs/superpowers/plans/*.md — 60+ historical implementation plans containing business rules, formulas, and decisions.
  • zerp-be/src/schema.gql — generated GraphQL schema (authoritative API surface).
  • zerp-be/src/migrations/* — data rules and invariants.

Principles

  1. Code-accurate. Every field, enum, and rule must come from the actual code, not assumption. Cite file paths (module/file.ts) so claims are verifiable.
  2. Full-stack per domain. Pair the backend module with its matching admin module(s). BE↔︎admin do not map 1:1 — see module-map.md.
  3. Flows included. Each domain _overview.md captures the end-to-end flows ("and flow" in the brief).
  4. Rebuild-grade. Follow TEMPLATE.md for every module doc. Prefer real code/enum snippets and small diagrams over prose.
  5. No invention. If something is unclear or not implemented, say so explicitly ("Not implemented", "TODO in code") rather than guessing.

Output structure

zerp/
  README.md                 master index / SRD entry point
  00-system-overview.md     what zerp is, the two apps, deployment, multi-tenancy
  module-map.md             BE↔admin correspondence matrix (incl. headless & UI-only modules)
  glossary.md               domain terms + cross-cutting data dictionary
  SPEC.md                   this file
  TEMPLATE.md               per-module doc skeleton (every doc follows it)

  platform/                 cross-cutting system "spine"
    architecture.md         layering, base abstractions, stack, conventions
    multi-tenancy.md        tenant DBs, master DB, context, timezone
    auth.md                 JWT, OTP, login/session
    permissions-access.md   RBAC, permission modules/actions, access groups, CASL, master-access
    workflow-approval-engine.md
    audit-trail.md
    notifications.md
    files-assets-upload.md
    reporting-framework.md

  domains/<domain>/
    _overview.md            domain entity map + cross-module end-to-end flows + shared enums/permissions
    <sub-module>.md         one doc per sub-module, following TEMPLATE.md

Domain → source mapping (the work breakdown)

Each row = one documentation work unit (one sub-agent). Sub-agents read the listed BE + admin paths fully and write the listed docs.

See module-map.md for the authoritative correspondence. The execution plan groups them into ~20 parallel passes. Splits exist only to keep each pass within a readable scope; the output is one coherent doc set.

Conventions for every doc

  • Markdown, GitHub-flavored. Use fenced code for schemas/enums/GraphQL.
  • Use relative links between docs (e.g. [stock](./stock.md), [permissions](../../platform/permissions-access.md)).
  • Reference source code as `inventory/stock/stock.schema.ts` (path relative to src/modules/).
  • Tables for field lists. Diagrams as ASCII/Mermaid where a flow is clearer shown than told.
  • Keep each sub-module doc self-contained but link to shared platform docs instead of repeating them.