# saleh7/php-zatca-xml architecture

> Architecture diagram of the GitHub repository saleh7/php-zatca-xml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saleh7/php-zatca-xml
- Repository: https://github.com/saleh7/php-zatca-xml

## Overview

##### Main Components
- Certificate Module – This module is in charge of generating certificate signing requests and handling compliance certificates. It is represented by classes like CertificateBuilder (in src), Certificate helper (in src/Helpers/Certificate), and exception classes in src/Exceptions.
- Invoice Generation Module – Contains all classes needed to create an invoice. This includes Invoice, InvoiceLine, and their related mappers (in src/Mappers) plus validators and helpers (e.g., InvoiceSignatureBuilder, InvoiceSigner in src/Helpers). The GeneratorInvoice is responsible for creating the raw XML.
- Digital Signing Module – Handles the task of digitally signing the generated invoice XML. The InvoiceSigner and accompanying certificate classes integrate with the Certificate module to apply the digital signature.
- API Communication Module – Encapsulated by the ZatcaAPI class (in src) and its associated API result classes (in src/Api), this module manages the communication with the external ZATCA servers (submitting CSR and signed invoices).
- XML & Storage Module – This module takes care of reading & writing files (see Storage class in src) and deals with saving or loading invoice XML, certificates, and output files.
- Utilities & Helpers – Contains supplementary functions such as the QRCodeGenerator (in src/Helpers) and additional functions for invoice extensions or document mapping.

##### Relationships and Interactions
- The Certificate Module generates a CSR and private key which, after external approval via the API module, becomes a compliance certificate.
- The Invoice Generation Module builds an invoice object from various components (invoice header, lines, taxes, payment means, seller/customer details, etc.). Once built, it is transformed into an XML format using the GeneratorInvoice.
- Before invoice submission, the Digital Signing Module uses the certificate information to sign the generated XML.
- The API Communication Module then uses the signed XML to interact with ZATCA’s servers (for final invoice submission) and to request the compliance certificate after CSR generation. There is also data persistence via the Storage module.
- Utilities such as QR code generation and invoice mapping/validation are tied to both certificate and invoice modules to ensure the data is compliant and ready for transmission.

##### Important Architectural Patterns and Design Principles
- Modularization: The project cleanly separates responsibilities into certificate, invoice generation, digital signing, and API communication. This modular design promotes easy maintenance and extensibility.
- Builder Pattern: Used in the CertificateBuilder and in constructing the invoice (evidenced by fluent methods configuring various parameters).
- Facade Pattern: The library provides high-level functions that abstract away the internal complexities (for example, the facade provided by InvoiceSigner::signInvoice).
- Separation of Concerns: Test cases and examples further confirm the aim for clear boundaries between various components (for instance, tests for mappers and signature builder).

##### Relevant Technologies and Frameworks
- PHP 8.1+ and Composer for dependency management.
- PHP extensions like DOM, libxml, openssl, etc., are critical for XML processing, digital signing, and certificate generation.
- The project uses unit test frameworks for testing (as seen in the tests directory).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Certificate Module
    subgraph "Certificate Module"
      CB("CertificateBuilder"):::module
      CH("Certificate Helper"):::module
      CE("Certificate Exceptions"):::module
    end

    %% Invoice Generation Module
    subgraph "Invoice Generation Module"
      Inv("Invoice"):::module
      IL("InvoiceLine"):::module
      Gen("XML Generation"):::module
      Mappers("Mappers"):::module
      Validators("Validators"):::module
    end

    %% Digital Signing Module
    subgraph "Digital Signing Module"
      IS("Invoice Signer"):::module
      ISB("Signing Helper"):::module
    end

    %% API Communication Module
    subgraph "API Communication Module"
      ZAPI("ZatcaAPI"):::module
      APIRes("API Result Classes"):::module
    end

    %% XML & Storage Module
    subgraph "XML & Storage Module"
      Storage("Storage"):::module
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
      QR("QR Code Generator"):::utility
      IExt("Additional Invoice Extensions"):::utility
    end

    %% Data Flow / Relationships
    CB -->|"CSR"| ZAPI
    ZAPI -->|"ComplianceCertificate"| CB

    Inv -->|"invoiceData"| Gen
    IL -->|"lineData"| Gen
    Gen -->|"UnsignedInvoiceXML"| IS

    ISB -->|"assists"| IS

    IS -->|"SignedInvoiceXML"| Storage
    IS -->|"SignedInvoiceXML"| ZAPI
    ZAPI -->|"APIRequest/Response"| APIRes

    Mappers -.->|"map"| Validators
    CH -.->|"helper"| QR
    Inv -.->|"extension"| IExt
    Validators -.->|"extension"| IExt

    %% Styles
    classDef module fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef utility fill:#d4edda,stroke:#155724,stroke-width:2px;

click CB "https://github.com/saleh7/php-zatca-xml/blob/main/src/CertificateBuilder.php"
click CH "https://github.com/saleh7/php-zatca-xml/blob/main/src/Helpers/Certificate.php"
click CE "https://github.com/saleh7/php-zatca-xml/blob/main/src/Exceptions/CertificateBuilderException.php"
click Inv "https://github.com/saleh7/php-zatca-xml/blob/main/src/Invoice.php"
click IL "https://github.com/saleh7/php-zatca-xml/blob/main/src/InvoiceLine.php"
click Gen "https://github.com/saleh7/php-zatca-xml/blob/main/src/GeneratorInvoice.php"
click Mappers "https://github.com/saleh7/php-zatca-xml/tree/main/src/Mappers"
click Validators "https://github.com/saleh7/php-zatca-xml/tree/main/src/Mappers/Validators"
click IS "https://github.com/saleh7/php-zatca-xml/blob/main/src/InvoiceSigner.php"
click ISB "https://github.com/saleh7/php-zatca-xml/blob/main/src/Helpers/InvoiceSignatureBuilder.php"
click ZAPI "https://github.com/saleh7/php-zatca-xml/blob/main/src/ZatcaAPI.php"
click APIRes "https://github.com/saleh7/php-zatca-xml/tree/main/src/Api"
click Storage "https://github.com/saleh7/php-zatca-xml/blob/main/src/Storage.php"
click QR "https://github.com/saleh7/php-zatca-xml/blob/main/src/Helpers/QRCodeGenerator.php"
click IExt "https://github.com/saleh7/php-zatca-xml/blob/main/src/Helpers/InvoiceExtension.php"
```
