git:20260519.0f7f756 to git:20260712.a867952

37 added, 31 removed. Audit A to A.

---

name: saas-erp-system-design

- description: Use when designing configurable SaaS or ERP platforms with multi-step

- business workflows, domain modules, approvals, auditability, pricing and entitlements,

- operational reporting, and tenant-specific variation. Covers domain boundaries,

- workflow states, extension points, and control design.

+ description: Use when designing configurable SaaS or ERP platforms with multi-step business workflows, domain modules, approvals, auditability, pricing and entitlements, operational reporting, and tenant-specific variation. Covers domain boundaries, workflow states, extension points, and control design.

metadata:

portable: true

compatible_with:

- - Codex

+ - claude-code

- codex

---

# SaaS ERP System Design

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

-

- ## Use When

- - Use when designing configurable SaaS or ERP platforms with multi-step business workflows, domain modules, approvals, auditability, pricing and entitlements, operational reporting, and tenant-specific variation. Covers domain boundaries, workflow states, extension points, and control design.

- - The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

+ ## Required Inputs

- ## Do Not Use When

+ | Input | Required | Use |

+ |---|---|---|

+ | Tenant, product, and lifecycle scope | yes | Bound the SaaS decision |

+ | Current architecture, plans, policies, and constraints | yes | Preserve enforceable behaviour |

+ | Production data or verified evidence | conditional | Validate thresholds and migrations |

- - The task is unrelated to `saas-erp-system-design` or would be better handled by a more specific companion skill.

- - The request only needs a trivial answer and none of this skill's constraints or references materially help.

+ ## Capability and permission contract

- ## Required Inputs

+ Default to read-only analysis. Change configuration, billing, identity, tenant data, infrastructure, or customer communications only with explicit authority, least-privilege credentials, tenant scope, rollback, and auditable approval. Never expose secrets or cross tenant boundaries.

- - Gather relevant project context, constraints, and the concrete problem to solve; load `references` only as needed.

- - Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

+ ## Degraded mode

- ## Workflow

+ If production access, policy, telemetry, or authoritative records are unavailable, produce a labelled design or dry-run plan. Do not claim deployment, reconciliation, deletion, delivery, or measured outcomes; list missing evidence and verification.

- - Read this `SKILL.md` first, then load only the referenced deep-dive files that are necessary for the task.

- - Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.

- - Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

+ ## Decision rules

- ## Quality Standards

+ | Condition | Action | Stop condition |

+ |---|---|---|

+ | Tenant isolation, money, identity, or deletion is affected | Require approval and rollback evidence | Scope or authority is ambiguous |

+ | Evidence supports a reversible change | Stage, test, and record it | Acceptance checks fail |

+ | Only partial context is available | Return assumptions and validation | A production claim cannot be verified |

- - Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.

- - Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.

- - Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

+ ## Domain Anti-Patterns

- ## Anti-Patterns

+ - Applying one tenant's policy or data to another. Fix: enforce tenant scope at every boundary.

+ - Mutating production from an advisory request. Fix: remain read-only until authority is explicit.

+ - Inventing limits, prices, metrics, or compliance claims. Fix: use authoritative records or mark them unresolved.

+ - Shipping without rollback and audit evidence. Fix: stage and retain before/after proof.

+ - Treating a missing dependency as successful. Fix: name the blocked verification.

- - Treating examples as copy-paste truth without checking fit, constraints, or failure modes.

- - Loading every reference file by default instead of using progressive disclosure.

- ## Outputs

+

+ ## Use When

- - A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.

- - Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.

- - References used, companion skills, or follow-up actions when they materially improve execution.

+ - Use when designing configurable SaaS or ERP platforms with multi-step business workflows, domain modules, approvals, auditability, pricing and entitlements, operational reporting, and tenant-specific variation. Covers domain boundaries, workflow states, extension points, and control design.

## Evidence Produced

|----------|----------|--------|---------|

| Correctness | ERP workflow decision record | Markdown doc per `skill-composition-standards/references/adr-template.md` covering domain modules, approvals, and audit-trail design | `docs/erp/workflow-adr.md` |

| Data safety | ERP module data model | Markdown doc per `skill-composition-standards/references/entity-model-template.md` covering entities, period-close, and audit columns | `docs/erp/module-data-model.md` |

## References

- Use the `references/` directory for deep detail after reading the core workflow below.

Use this skill when the system must encode real business operations, not just CRUD screens. It is optimized for multi-tenant business software where configurability, correctness, and audit trails matter.

## Design Priorities

- Domain correctness before UI convenience.

- Configurable behavior without tenant-specific forks.

- Explicit workflow states and approvals.

- Auditability for every material business change.

- Reporting models that do not corrupt transactional design.

## System Design Workflow

### 1. Map Business Capabilities

Identify bounded domains such as:

- Sales and CRM

- Procurement

- Inventory and fulfillment

- Logistics network, transportation, fleet/carrier management, and warehouse execution where physical goods move across locations

- Finance and accounting

- HR and payroll

- Operations and reporting

Keep each capability distinct even if the first release ships only a subset.

### 2. Map Business Objects and Lifecycles

For each object define:

- Draft state

- Review or approval states

- Posted or committed state

- Reversal or cancellation path

- Audit requirements

Do not model important workflows as a single status field without state transition rules.

### 3. Separate Configuration from Transactions

Use distinct models for:

- Master data

- Configuration and entitlements

- Transactions

- Ledgers or audit history

- Reporting projections

Tenant-specific behavior should come from configuration, policy, or feature flags, not code forks.

### 4. Design Control Points

Every ERP-grade workflow needs explicit controls for:

- Permissions and separation of duties

- Approval thresholds

- Posting and locking periods

- Reconciliation and correction

- Audit log and reason capture

- Policy evaluation points and rule override governance

### 5. Design for Extensions

- Use module boundaries and extension points around optional verticals.

- Keep core concepts stable: party, product, location, document, ledger, user, role, workflow.

- Add industry-specific detail in modules without corrupting the core language.

- Prefer workflow composition and policy engines over tenant-specific code paths.

## Modeling Rules

### Workflow Rules

- Important transactions are append-only or at least auditable.

- Corrections should prefer reversal plus replacement over silent mutation.

- Status transitions must be explicit and permission-checked.

- Derived totals must be reproducible from source data.

### Financial Integrity

- Never edit posted financial records in place without a traceable reversal model.

- Use document numbers, posting dates, fiscal periods, and actor attribution consistently.

- Separate operational status from accounting status when those timelines differ.

### Reporting

- Operational reports can read transactional tables only while scale permits.

- Build projections or aggregates once reporting complexity or volume grows.

- Distinguish regulatory, finance, and operational reporting needs.

### Cross-Module Workflows

- Define how documents, approvals, entitlements, accounting, and notifications interact.

- Ensure every cross-module workflow can be reconstructed from source events and audit history.

- Make downstream posting and reversal rules explicit before implementation.

## Decision Heuristics

Use configurable policies when:

- The rule differs by tenant but the workflow concept stays the same.

Use modules when:

- The feature adds new concepts, permissions, data, or pricing boundaries.

Use approval workflows when:

- Monetary, inventory, compliance, or high-risk operational consequences exist.

Avoid per-tenant code branches unless:

- Legal or contractual obligations make configuration insufficient.

## Deliverables

For major SaaS or ERP design tasks, produce:

- Domain map and module boundaries.

- Core entities and lifecycle states.

- Control and approval model.

- Entitlement and pricing model.

- Audit and reporting strategy.

- Integration map for external systems and async jobs.

- Cross-module workflow map and policy boundaries.

For ERP projects involving manufacturing, wholesale, distribution, import/export, fleet, field delivery, agriculture aggregation, or warehouse operations, pair this skill with `inventory-management` and load `inventory-management/references/cltd-logistics-inventory-patterns.md`. The ERP design should explicitly model inventory policy, in-transit stock, shipment events, carrier/fleet assignment, freight documents, customs controls where relevant, returns, claims, and logistics KPIs rather than treating fulfilment as a simple order status.

For ERP projects with billing, fees, POS, payroll, inventory valuation, grants, patient billing, school fees, donor funds, manufacturing cost, or statutory reporting, pair this skill with `saas-accounting-system` and load `saas-accounting-system/references/accounting-bookkeeping-erp-patterns.md`. The design should model GL, subledgers, control accounts, fiscal periods, posting rules, reconciliation, close, dimensions, cost centres, profit centres, tax, fixed assets, and management reporting as first-class capabilities.

## References

- [references/domain-modeling.md](references/domain-modeling.md): Core entities, controls, and workflow review prompts.

- - [../inventory-management/references/cltd-logistics-inventory-patterns.md](../inventory-management/references/cltd-logistics-inventory-patterns.md): Logistics network, inventory policy, transportation, carrier/fleet, trade documentation, and shipment exception patterns for ERP systems.

+ - Load the external `chwezi-accounting-doctrine` inventory and logistics skill for inventory policy, transportation, trade documentation, and shipment exception patterns.

- [../saas-accounting-system/references/accounting-bookkeeping-erp-patterns.md](../saas-accounting-system/references/accounting-bookkeeping-erp-patterns.md): Double-entry bookkeeping, subledgers, ERP finance configuration, cost accounting, controls, reconciliations, and close patterns.

- Load `modular-saas-architecture`, `multi-tenant-saas-architecture`, and `database-design-engineering` when implementing the design.

+ ## Quality Standards

+ The design must expose authoritative records, valid transitions, approval segregation, tenant extensions, audit events, integration failures, and reporting ownership without shared-table ambiguity.

+ ## Outputs

+ | Artefact | Consumer | Acceptance condition |

+ |---|---|---|

+ | ERP domain and workflow design | Product architects and implementation teams | Domain ownership, state transitions, approvals, extension points, tenant variation, audit events, and reporting boundaries are unambiguous |