# erpgulf/zatca_erpgulf architecture

> Architecture diagram of the GitHub repository erpgulf/zatca_erpgulf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erpgulf/zatca_erpgulf
- Repository: https://github.com/erpgulf/zatca_erpgulf

## Overview

This Frappe ERPNext app connects Sales Invoice and POS Invoice submission to ZATCA Phase-2 processing. The documented workflow covers compliance checks, invoice preparation and signing, then clearance or reporting; POS has a parallel path. CSR/certificate setup, QR/XML handling, event logs, settings, dashboards, and comparison/status reports support that workflow. Hooks and selected source excerpts establish only some runtime links; other subsystem relationships are left unconnected where source evidence is incomplete.

Main entry points: [`zatca_erpgulf/zatca_erpgulf/sign_invoice.py`](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sign_invoice.py) (Sales signing and submission), [`zatca_erpgulf/hooks.py`](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/hooks.py) (Sales invoice hook), [`zatca_erpgulf/zatca_erpgulf/pos_sign.py`](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/pos_sign.py) (POS signing and submission), [`zatca_erpgulf/zatca_erpgulf/sign_invoice_first.py`](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sign_invoice_first.py) (CSR and certificates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["ERPNext entry points"]
  node_sales_invoice["Sales Invoice"]
  node_pos_invoice["POS Invoice"]
  node_sales_hook["Sales invoice hook<br/>[hooks.py]"]
end

subgraph group_compliance["Compliance preparation"]
  node_sales_checks["Invoice validation<br/>[validations.py]"]
  node_tax_checks["Tax validation<br/>[tax_error.py]"]
  node_invoice_xml["Sales invoice XML<br/>[createxml.py]"]
  node_xml_tax["XML tax data<br/>[xml_tax_data.py]"]
  node_xml_final["UBL XML assembly"]
  node_pos_xml["POS XML<br/>[posxml.py]"]
end

subgraph group_submission["Signing and submission"]
  node_sales_submit["Sales signing and submission<br/>[sign_invoice.py]"]
  node_pos_submit["POS signing and submission<br/>[pos_sign.py]"]
  node_pos_background["POS background jobs"]
  node_qr["QR generation<br/>[create_qr.py]"]
  node_invoice_storage["Invoice XML and QR"]
end

subgraph group_operations["Configuration and operations"]
  node_csr_setup["CSR and certificates"]
  node_company_settings["Company settings"]
  node_multi_settings["Multiple settings"]
  node_scheduler["Scheduled submission<br/>[scheduler_event.py]"]
end

subgraph group_visibility["Monitoring and reports"]
  node_event_log[("Event logging<br/>[event_log.py]")]
  node_dashboard["ZATCA dashboard<br/>[zatca_dashboard.js]"]
  node_reports["Status and comparison reports"]
end

node_sales_user(("ERPNext user"))
node_zatca["ZATCA services"]

node_sales_user -->|"creates or submits"| node_sales_invoice
node_sales_user -->|"creates or submits"| node_pos_invoice
node_sales_invoice -->|"on submit"| node_sales_hook
node_pos_invoice -->|"on submit"| node_pos_submit
node_sales_hook -->|"dispatches to"| node_sales_submit
node_sales_hook -->|"validates"| node_sales_checks
node_sales_hook -->|"validates tax"| node_tax_checks
node_sales_submit -->|"requests clearance or reporting"| node_zatca
node_pos_submit -->|"requests clearance"| node_zatca
node_csr_setup -->|"requests production credentials"| node_zatca
node_sales_submit -.->|"logs outcomes"| node_event_log
node_pos_submit -.->|"logs outcomes"| node_event_log
node_scheduler -.->|"submits in background"| node_sales_submit
node_scheduler -.->|"submits in background"| node_pos_background
node_sales_submit -.->|"prepares invoice XML"| node_invoice_xml
node_invoice_xml -->|"uses tax data"| node_xml_tax
node_sales_submit -.->|"assembles XML"| node_xml_final
node_pos_submit -.->|"prepares POS XML"| node_pos_xml
node_sales_submit -.->|"creates QR"| node_qr
node_sales_submit -.->|"attaches returned XML"| node_invoice_storage
node_company_settings -.->|"provides certificate settings"| node_csr_setup
node_multi_settings -.->|"provides certificate settings"| node_csr_setup

click node_sales_hook "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/hooks.py"
click node_sales_checks "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/validations.py"
click node_tax_checks "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/tax_error.py"
click node_invoice_xml "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/createxml.py"
click node_xml_tax "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/xml_tax_data.py"
click node_xml_final "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/create_xml_final_part.py"
click node_pos_xml "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/posxml.py"
click node_csr_setup "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sign_invoice_first.py"
click node_company_settings "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/doctype/zatca_erpgulf_setting/zatca_erpgulf_setting.py"
click node_multi_settings "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/doctype/zatca_multiple_setting/zatca_multiple_setting.py"
click node_sales_submit "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sign_invoice.py"
click node_pos_submit "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/pos_sign.py"
click node_pos_background "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/pos_schedule_background.py"
click node_qr "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/create_qr.py"
click node_invoice_storage "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sales_invoice_with_xmlqr.py"
click node_event_log "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/event_log.py"
click node_scheduler "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/scheduler_event.py"
click node_dashboard "https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/page/zatca_dashboard/zatca_dashboard.js"
click node_reports "https://github.com/erpgulf/zatca_erpgulf/tree/main/zatca_erpgulf/zatca_erpgulf/report"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sales_invoice,node_pos_invoice,node_sales_hook,node_sales_user toneBlue
class node_sales_checks,node_tax_checks,node_invoice_xml,node_xml_tax,node_xml_final,node_pos_xml toneAmber
class node_sales_submit,node_pos_submit,node_pos_background,node_qr,node_invoice_storage toneMint
class node_csr_setup,node_company_settings,node_multi_settings,node_scheduler toneRose
class node_event_log,node_dashboard,node_reports,node_zatca toneIndigo
```

## Components

### ERPNext entry points

- **Sales Invoice**
- **POS Invoice**
- [Sales invoice hook](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/hooks.py): `zatca_erpgulf/hooks.py`

### Compliance preparation

- [Invoice validation](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/validations.py): `zatca_erpgulf/zatca_erpgulf/validations.py`
- [Tax validation](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/tax_error.py): `zatca_erpgulf/zatca_erpgulf/tax_error.py`
- [Sales invoice XML](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/createxml.py): `zatca_erpgulf/zatca_erpgulf/createxml.py`
- [XML tax data](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/xml_tax_data.py): `zatca_erpgulf/zatca_erpgulf/xml_tax_data.py`
- [UBL XML assembly](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/create_xml_final_part.py): `zatca_erpgulf/zatca_erpgulf/create_xml_final_part.py`
- [POS XML](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/posxml.py): `zatca_erpgulf/zatca_erpgulf/posxml.py`

### Signing and submission

- [Sales signing and submission](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sign_invoice.py): `zatca_erpgulf/zatca_erpgulf/sign_invoice.py`
- [POS signing and submission](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/pos_sign.py): `zatca_erpgulf/zatca_erpgulf/pos_sign.py`
- [POS background jobs](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/pos_schedule_background.py): `zatca_erpgulf/zatca_erpgulf/pos_schedule_background.py`
- [QR generation](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/create_qr.py): `zatca_erpgulf/zatca_erpgulf/create_qr.py`
- [Invoice XML and QR](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sales_invoice_with_xmlqr.py): `zatca_erpgulf/zatca_erpgulf/sales_invoice_with_xmlqr.py`

### Configuration and operations

- [CSR and certificates](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/sign_invoice_first.py): `zatca_erpgulf/zatca_erpgulf/sign_invoice_first.py`
- [Company settings](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/doctype/zatca_erpgulf_setting/zatca_erpgulf_setting.py): `zatca_erpgulf/zatca_erpgulf/doctype/zatca_erpgulf_setting/zatca_erpgulf_setting.py`
- [Multiple settings](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/doctype/zatca_multiple_setting/zatca_multiple_setting.py): `zatca_erpgulf/zatca_erpgulf/doctype/zatca_multiple_setting/zatca_multiple_setting.py`
- [Scheduled submission](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/scheduler_event.py): `zatca_erpgulf/zatca_erpgulf/scheduler_event.py`

### Monitoring and reports

- [Event logging](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/event_log.py): `zatca_erpgulf/zatca_erpgulf/event_log.py`
- [ZATCA dashboard](https://github.com/erpgulf/zatca_erpgulf/blob/main/zatca_erpgulf/zatca_erpgulf/page/zatca_dashboard/zatca_dashboard.js): `zatca_erpgulf/zatca_erpgulf/page/zatca_dashboard/zatca_dashboard.js`
- [Status and comparison reports](https://github.com/erpgulf/zatca_erpgulf/tree/main/zatca_erpgulf/zatca_erpgulf/report): `zatca_erpgulf/zatca_erpgulf/report`

### Other components

- **ERPNext user**
- **ZATCA services**

## Connections

- ERPNext user → Sales Invoice: creates or submits (evidence: `README.md`)
- ERPNext user → POS Invoice: creates or submits (evidence: `README.md`)
- Sales Invoice → Sales invoice hook: on submit (evidence: `zatca_erpgulf/hooks.py`)
- POS Invoice → POS signing and submission: on submit
- Sales invoice hook → Sales signing and submission: dispatches to (evidence: `zatca_erpgulf/hooks.py`)
- Sales invoice hook → Invoice validation: validates (evidence: `zatca_erpgulf/hooks.py`)
- Sales invoice hook → Tax validation: validates tax (evidence: `zatca_erpgulf/hooks.py`)
- Sales signing and submission → ZATCA services: requests clearance or reporting (evidence: `zatca_erpgulf/zatca_erpgulf/sign_invoice.py`)
- POS signing and submission → ZATCA services: requests clearance (evidence: `zatca_erpgulf/zatca_erpgulf/pos_sign.py`)
- CSR and certificates → ZATCA services: requests production credentials (evidence: `zatca_erpgulf/zatca_erpgulf/sign_invoice_first.py`)
- Sales signing and submission → Event logging: logs outcomes (evidence: `zatca_erpgulf/zatca_erpgulf/sign_invoice.py`)
- POS signing and submission → Event logging: logs outcomes (evidence: `zatca_erpgulf/zatca_erpgulf/pos_sign.py`)
- Scheduled submission → Sales signing and submission: submits in background
- Scheduled submission → POS background jobs: submits in background
- Sales signing and submission → Sales invoice XML: prepares invoice XML (evidence: `zatca_erpgulf/zatca_erpgulf/sign_invoice.py`)
- Sales invoice XML → XML tax data: uses tax data
- Sales signing and submission → UBL XML assembly: assembles XML (evidence: `zatca_erpgulf/zatca_erpgulf/sign_invoice.py`)
- POS signing and submission → POS XML: prepares POS XML (evidence: `zatca_erpgulf/zatca_erpgulf/pos_sign.py`)
- Sales signing and submission → QR generation: creates QR (evidence: `zatca_erpgulf/zatca_erpgulf/sign_invoice.py`)
- Sales signing and submission → Invoice XML and QR: attaches returned XML (evidence: `zatca_erpgulf/zatca_erpgulf/sign_invoice.py`)
- Company settings → CSR and certificates: provides certificate settings
- Multiple settings → CSR and certificates: provides certificate settings
