# beveren-software-inc/zatca_integration architecture

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

- Interactive diagram: https://gitdiagram.com/beveren-software-inc/zatca_integration
- Repository: https://github.com/beveren-software-inc/zatca_integration

## Overview

This ERPNext app provides Saudi ZATCA Phase 2 e-invoicing: it prepares standard B2B and simplified B2C invoices, generates and signs compliant XML, submits invoices for clearance or reporting, and tracks responses. Company administrators also configure ZATCA environments and credentials; invoice data validation, VAT reporting, and compliant PDF/QR output support the main workflow. The README documents these capabilities, while the excerpts show key submission, signing, and validation relationships. Several listed subsystems were not sampled, so their internal links are omitted.

Main entry points: [`zatca_integration/public/js/sales_invoice.js`](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/public/js/sales_invoice.js) (Sales Invoice), [`zatca_integration/clearence_util.py`](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/clearence_util.py) (ZATCA Submission), [`zatca_integration/saudi_arabia_electronic_invoicing/doctype/compliance_csid/compliance_csid.py`](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/compliance_csid/compliance_csid.py) (Compliance CSID), [`zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/final_invoice_signing.py`](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/final_invoice_signing.py) (Invoice Signing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_invoice["Invoice Workflow"]
  node_sales_invoice["Sales Invoice<br/>[sales_invoice.js]"]
  node_invoice_validation["Invoice Validation<br/>[common_util.py]"]
  node_xml_generation["Invoice XML"]
  node_invoice_signing["Invoice Signing"]
  node_zatca_submission["ZATCA Submission<br/>[clearence_util.py]"]
  node_zatca{{"ZATCA Portal"}}
  node_submission_audit[("Submission Audit")]
end

subgraph group_credentials["ZATCA Setup"]
  node_csr["CSR Settings"]
  node_compliance_csid["Compliance CSID<br/>[compliance_csid.py]"]
  node_production_csid[("Production CSID<br/>[production_csid.py]")]
  node_environment["Environment Settings"]
end

subgraph group_compliance["Tax Compliance"]
  node_vat_setup["VAT Setup<br/>[vat_setup.py]"]
  node_vat_reports["VAT Reports<br/>[zatca_vat.py]"]
  node_vat_return["VAT Return"]
  node_party_validation["Party Validation<br/>[address.py]"]
end

subgraph group_outputs["Invoice Outputs"]
  node_pdf_output["Invoice PDF"]
  node_qr_output["QR Generation"]
end

node_user(("ERPNext User"))

node_user -->|"creates invoice"| node_sales_invoice
node_sales_invoice -.->|"validates data"| node_invoice_validation
node_sales_invoice -.->|"starts submission"| node_xml_generation
node_invoice_signing -->|"builds signed XML"| node_xml_generation
node_zatca_submission -->|"invokes signing"| node_invoice_signing
node_zatca_submission -->|"submits invoice"| node_zatca
node_zatca -->|"returns response"| node_zatca_submission
node_zatca_submission -.->|"tracks status"| node_submission_audit
node_user -->|"configures credentials"| node_csr
node_csr -->|"creates compliance CSID"| node_compliance_csid
node_compliance_csid -->|"requests CSID"| node_zatca
node_compliance_csid -->|"generates production CSID"| node_production_csid
node_environment -.->|"selects endpoint"| node_zatca_submission
node_user -->|"sets up VAT"| node_vat_setup
node_vat_reports -->|"presents reports"| node_user
node_vat_return -.->|"supports filing"| node_zatca
node_party_validation -.->|"checks party data"| node_invoice_validation
node_sales_invoice -->|"produces PDF"| node_pdf_output
node_sales_invoice -->|"generates QR"| node_qr_output

click node_sales_invoice "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/public/js/sales_invoice.js"
click node_invoice_validation "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/common_util.py"
click node_xml_generation "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/generate_invoice_xml.py"
click node_invoice_signing "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/final_invoice_signing.py"
click node_zatca_submission "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/clearence_util.py"
click node_submission_audit "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_transactions/zatca_transactions.py"
click node_csr "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_csr_settings/zatca_csr_settings.py"
click node_compliance_csid "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/compliance_csid/compliance_csid.py"
click node_production_csid "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/production_csid/production_csid.py"
click node_environment "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_environment/zatca_environment.py"
click node_vat_setup "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/vat_setup.py"
click node_vat_reports "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/report/zatca_vat/zatca_vat.py"
click node_vat_return "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/zatca_vat_return_api.py"
click node_party_validation "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/overrides/address.py"
click node_pdf_output "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/customization/sales_invoice/generate_pdf_3a_convertapi.py"
click node_qr_output "https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/temp_qr_generator.py"

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_invoice_validation,node_xml_generation,node_invoice_signing,node_zatca_submission,node_zatca,node_submission_audit,node_user toneBlue
class node_csr,node_compliance_csid,node_production_csid,node_environment toneAmber
class node_vat_setup,node_vat_reports,node_vat_return,node_party_validation toneMint
class node_pdf_output,node_qr_output toneRose
```

## Components

### Invoice Workflow

- [Sales Invoice](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/public/js/sales_invoice.js): `zatca_integration/public/js/sales_invoice.js`
- [Invoice Validation](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/common_util.py): `zatca_integration/common_util.py`
- [Invoice XML](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/generate_invoice_xml.py): `zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/generate_invoice_xml.py`
- [Invoice Signing](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/final_invoice_signing.py): `zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/final_invoice_signing.py`
- [ZATCA Submission](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/clearence_util.py): `zatca_integration/clearence_util.py`
- **ZATCA Portal**
- [Submission Audit](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_transactions/zatca_transactions.py): `zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_transactions/zatca_transactions.py`

### ZATCA Setup

- [CSR Settings](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_csr_settings/zatca_csr_settings.py): `zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_csr_settings/zatca_csr_settings.py`
- [Compliance CSID](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/compliance_csid/compliance_csid.py): `zatca_integration/saudi_arabia_electronic_invoicing/doctype/compliance_csid/compliance_csid.py`
- [Production CSID](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/production_csid/production_csid.py): `zatca_integration/saudi_arabia_electronic_invoicing/doctype/production_csid/production_csid.py`
- [Environment Settings](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_environment/zatca_environment.py): `zatca_integration/saudi_arabia_electronic_invoicing/doctype/zatca_environment/zatca_environment.py`

### Tax Compliance

- [VAT Setup](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/vat_setup.py): `zatca_integration/saudi_arabia_electronic_invoicing/vat_setup.py`
- [VAT Reports](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/report/zatca_vat/zatca_vat.py): `zatca_integration/saudi_arabia_electronic_invoicing/report/zatca_vat/zatca_vat.py`
- [VAT Return](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/zatca_vat_return_api.py): `zatca_integration/saudi_arabia_electronic_invoicing/zatca_vat_return_api.py`
- [Party Validation](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/overrides/address.py): `zatca_integration/overrides/address.py`

### Invoice Outputs

- [Invoice PDF](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/customization/sales_invoice/generate_pdf_3a_convertapi.py): `zatca_integration/customization/sales_invoice/generate_pdf_3a_convertapi.py`
- [QR Generation](https://github.com/beveren-software-inc/zatca_integration/blob/version-16/zatca_integration/saudi_arabia_electronic_invoicing/temp_qr_generator.py): `zatca_integration/saudi_arabia_electronic_invoicing/temp_qr_generator.py`

### Other components

- **ERPNext User**

## Connections

- ERPNext User → Sales Invoice: creates invoice (evidence: `README.md`)
- Sales Invoice → Invoice Validation: validates data
- Sales Invoice → Invoice XML: starts submission
- Invoice Signing → Invoice XML: builds signed XML (evidence: `zatca_integration/saudi_arabia_electronic_invoicing/signing_engine/final_invoice_signing.py`)
- ZATCA Submission → Invoice Signing: invokes signing (evidence: `zatca_integration/clearence_util.py`)
- ZATCA Submission → ZATCA Portal: submits invoice (evidence: `zatca_integration/clearence_util.py`)
- ZATCA Portal → ZATCA Submission: returns response (evidence: `zatca_integration/clearence_util.py`)
- ZATCA Submission → Submission Audit: tracks status
- ERPNext User → CSR Settings: configures credentials (evidence: `README.md`)
- CSR Settings → Compliance CSID: creates compliance CSID (evidence: `README.md`)
- Compliance CSID → ZATCA Portal: requests CSID (evidence: `zatca_integration/saudi_arabia_electronic_invoicing/doctype/compliance_csid/compliance_csid.py`)
- Compliance CSID → Production CSID: generates production CSID (evidence: `README.md`)
- Environment Settings → ZATCA Submission: selects endpoint
- ERPNext User → VAT Setup: sets up VAT (evidence: `README.md`)
- VAT Reports → ERPNext User: presents reports (evidence: `README.md`)
- VAT Return → ZATCA Portal: supports filing
- Party Validation → Invoice Validation: checks party data (evidence: `zatca_integration/overrides/address.py`)
- Sales Invoice → Invoice PDF: produces PDF (evidence: `README.md`)
- Sales Invoice → QR Generation: generates QR (evidence: `README.md`)
