Data Model

Warka stores nothing in a bespoke schema. Every record is a standard Frappe, ERPNext, or HRMS doctype, and the custom app adds only a handful of custom fields, some seeded master data, and one document-event hook. This means the entire ERPNext and HRMS data model, its reports, its permission system, and its integrity guarantees are available unchanged. This document lists the doctypes each module uses, the fields Warka adds, the master data it seeds, the document hook it registers, and the submittable-document-with-a-ledger model that underpins finance and payroll. The endpoints that read and write these doctypes are in the API Reference.

Doctypes by module

HR and Payroll (ERPNext + HRMS)

Finance (ERPNext Accounts)

Selling (ERPNext CRM and Selling)

Buying (ERPNext Buying)

Stock (ERPNext Stock)

Projects (ERPNext Projects)

Core (Frappe)

Custom fields Warka adds

Warka adds custom fields idempotently through Frappe's custom-field system, wired to the after_install and after_migrate hooks so the schema is reproducible on any site. It never forks a standard doctype.

Employee (ensure_employee_custom_fields in api.py)

A "National Identity and Residence" section with an Ethiopian context, inserted after the blood-group field:

Company (ensure_careers_fields in careers.py)

A collapsible "Careers Page" section that lets HR brand the public careers site from inside the ERP:

Employee Boarding Activity (ensure_boarding_field in api.py)

The cz_completed flag tracks per-activity checklist progress directly, which sidesteps the fragile standard submit/Task machinery so the lifecycle flow always works. The app also self-heals this column on demand (_ensure_boarding_field_once) if a site was updated in place without running the migrate hook.

Master data seeded by setup_defaults.py

ensure_operational_defaults() is idempotent and runs on every migrate. It fills the gaps a bare bench new-site leaves, so no transactional endpoint fails on a missing link. If any of these is deleted by hand, the next migrate recreates it.

complete_setup_wizard() is the separate one-time routine that runs the real ERPNext setup wizard to provision the Company and chart of accounts from the COMPANY_* configuration. See Configuration and Customization for the values it consumes and why this makes Warka company-agnostic.

The document event hook

The app registers one doc_events hook in hooks.py:

doc_events = {
    "Expense Claim": {
        "validate": "cyber_zeb_erp.doc_hooks.expense_claim_defaults",
    },
}

expense_claim_defaults (in doc_hooks.py) runs on every write path (frontend REST, the whitelisted API, and imports). Cost center is mandatory on every expense row but users rarely set it, so the hook defaults the header and each row to the company cost center when blank, turning a hard validation error into a sensible default. This is the pattern to follow when adding your own hooks; see Extending and Customizing.

The submittable-document-with-a-ledger model

ERPNext transactions are submittable documents, and this is the key model to understand. A document has a docstatus:

When a Sales Invoice, Purchase Invoice, Payment Entry, Journal Entry, or Salary Slip is submitted, ERPNext writes immutable GL Entry rows to the general ledger. Reports such as the Profit and Loss statement, the Balance Sheet, and the aging reports read those GL Entries, never the source documents, so the financial statements are always a faithful projection of what was actually posted. Warka's create endpoints insert a draft and then attempt to submit it inside a savepoint, so a submit that fails validation leaves a recoverable draft rather than losing the record (_submit_or_draft in api.py). Stock movements work the same way: submitting a stock document updates the per-item, per-warehouse Bin, which the inventory dashboard reads for valuation and low-stock detection.

Multi-company

Every transactional doctype carries a company field, and the ledger, cost centers, warehouses, and default accounts are all company-scoped. The API resolves the active company from the user default, then the Global Defaults singleton, then the first Company on the site (_default_company). The cached dashboards are keyed per company so one company's numbers are never served to another. A single Warka instance can therefore run several companies, though a typical deployment provisions one. Company setup and the chart of accounts are covered in the Implementation Guide.