إنتقل إلى المحتوى الرئيسي

⚙️ Deterministic Core Engines

A fundamental architectural constraint of BayanCore is transactional determinism. While generative AI assists in compiling data, drafting records, and explaining anomalies, the AI is strictly prohibited from writing or posting financial, inventory, or HR records directly to the General Ledger without passing through deterministic code validation and manual human approval.

[AI Draft Proposal] ──> [Deterministic Validation Engine] ──> [Human Review UI] ──> [ERPNext Ledger Commit]

1. Financial Ledger & ZATCA Engine​

The financial core handles double-entry accounting and tax calculations.

  • ERPNext Ledger Kernel: We utilize ERPNext's standard General Ledger (GL) posting mechanism. This ensures all debit-credit mappings, period-close rules, and currency adjustments are executed by a mature, globally tested accounting engine.
  • The Tax Engine: Manages Saudi-specific tax parameters:
    • Standard VAT (15%) calculated at item levels.
    • Withholding Tax (WHT) calculations based on supplier contract types.
  • The ZATCA Clearance Loop:
    1. Creation: An invoice is saved as a draft.
    2. Validation: The system runs structural checks against the ZATCA UBL 2.1 schema and local BR-KSA rules (e.g., checking if the customer's CR, postal code, or street name matches formatting requirements).
    3. Cryptographic Signing: If validation passes, the system converts the document to XML, appends the cryptographic hash chain, embeds the PCSID certificate, generates the Base64 TLV QR code, and triggers clearance/reporting.
    4. Posting: The invoice is locked and posted to the General Ledger only after ZATCA clears or reports the invoice.

2. Project & Inventory Engine​

This engine regulates physical assets, stock valuation, and contracting milestones.

  • Inventory Valuation: Supports Weighted Average and FIFO (First-In, First-Out) methods. The valuation rate is automatically adjusted by Landed Cost Vouchers (LCVs) to allocate import shipping, customs, and clearing expenses.
  • BOQ & Milestone Control: For contracting projects, the engine controls expenditures by matching subcontractor claims and purchase orders to the Bill of Quantities (BOQ). A purchase requisition exceeding the BOQ line item budget is programmatically blocked from creation.
  • Stock Transfer Verification: Tracks inventory movements across multiple warehouses using double-entry stock bookkeeping. Stock remains in an intermediate "In-Transit" warehouse account until physically scanned and accepted at the destination.

3. HR & Payroll Engine​

The HR engine enforces compliance with Saudi Labor Law and local social insurance (GOSI).

  • Statutory Deductions: پروگرامmatically computes salary slip deductions:
    • GOSI (Saudi Nationals): Auto-deducts 9.75% from the employee's basic salary + housing allowance, and calculates the employer's 11.75% contribution.
    • GOSI (Expat Employees): Calculates the employer's 2% occupational hazard insurance contribution.
  • WPS File Generation: At the end of the payroll cycle, the engine compiles a Wage Protection System (.SIF) file. This file must match the strict format required by Saudi banks, containing employee IBANs, GOSI registration numbers, salaries, and deduction details.
  • EOSB (End of Service Benefits): Programmatic calculation based on employment type (fixed/unlimited) and duration, ensuring legal compliance on contract termination.
  • Saudization (Nitaqat) Engine: Programmatically tracks native Saudi hiring ratios and cross-references data with the Qiwa database, alerting management if the establishment's compliance status risks entering yellow or red zones.