# sulaman0/zacta-phase2 architecture

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

- Interactive diagram: https://gitdiagram.com/sulaman0/zacta-phase2
- Repository: https://github.com/sulaman0/zacta-phase2

## Overview

##### Project type and purpose
- This is a PHP library/package (with example front-end scripts) that implements Saudi Arabia ZATCA’s E-Invoicing phases.
- It provides modules to generate/ onboard EGS (E-Invoice Generation System) units, sign invoices, build UBL-compliant XML, produce QR codes, and call ZATCA’s external compliance APIs.

##### File structure
Top‐level:
- index.php, phase-1.php – example scripts (presentation layer)
- composer.json / composer.lock – dependency management, autoloader
- ZATCA/ – core PHP namespace:
– EGS.php – key generation, CSR, compliance certificate, signInvoice(), checkInvoiceCompliance()
– GenerateQrCode.php – QR payload builder
– API.php – encapsulates remote calls to ZATCA web services
– Tag.php + Tags/* – domain model for XML tags (InvoiceDate, TaxNumber, Seller, etc.)
– templates/ – PHP partials to render UBL/XML segments and signature wrappers
- assets/ – static files (CSS/JS/images) used by example pages
- docs/ + User_Manual_Developer_Portal_Manual_Version_3.pdf – specifications and user guidance

##### README for additional insights
- Supports EGS onboarding (x.509 CSIDs), cryptographic stamp generation, simplified tax invoice creation, signing, compliance checking.
- Depends on OpenSSL for ECDSA keypair & CSR generation; other modules are pure PHP and can run in lightweight environments (e.g., React Native).
- Examples run on PHP’s built-in server (php -S), demonstrating phases 1 & 2.

##### Main components & interactions
a. Presentation Layer (Examples)
- index.php, phase-1.php
- Loads Composer autoloader → instantiates ZATCA\EGS and invoice objects → triggers flows
- Outputs HTML + embedded QR code (using GenerateQrCode)

b. Application / Service Layer
- ZATCA\EGS
– generateNewKeysAndCSR() → calls OpenSSL CLI / PHP’s openssl extension
– issueComplianceCertificate() → uses API.php to call ZATCA’s compliance endpoint (SOAP/REST)
– signInvoice() →
· Builds XML via Tag classes + templates
· Applies XML digital signature (templates/ubl_signature*.php)
– checkInvoiceCompliance() → remote API call for compliance status

c. Domain Model
- ZATCA\Tag + ZATCA\Tags\*
– Represent each UBL XML element (InvoiceDate, TaxNumber, LegalMonetaryTotal, etc.)
– Provide typed getters/setters and render logic (XML fragments)

d. Template Engine
- ZATCA/templates/*.php
– Partial templates to assemble the final UBL 2.1 tax invoice XML
– Handle signature, signed properties, invoice lines, totals, billing references

e. Infrastructure Layer
- Composer autoloader / PHP runtime
- OpenSSL (system dependency)
- External ZATCA E-Invoicing web services (issuance & validation endpoints)

f. External / Consumer
- ZATCA web APIs (Compliance, Reporting)
- QR Reader Apps (mobile, to scan and validate base64 QR payload)

##### Architectural patterns & design principles
- Separation of concerns:
· Presentation (example scripts) vs. Service (EGS) vs. Domain (Tags) vs. Template (XML fragments).
- Modular, namespace-driven code organization (ZATCA\… classes).
- Thin API adapter (API.php) abstracts remote calls.
- Template-based XML generation to maintain UBL standard compliance.
- Dependency management via Composer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    title["ZATCA PHP E-Invoicing System Architecture"]

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        index["index.php"]:::frontend
        phase1["phase-1.php"]:::frontend
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        EGS["ZATCA\\EGS"]:::service
        API["ZATCA\\API"]:::service
        QR["ZATCA\\GenerateQrCode"]:::service
    end

    %% Domain Model
    subgraph "Domain Model"
        direction TB
        Tag["ZATCA\\Tag"]:::domain
        Tags["ZATCA/Tags/"]:::domain
    end

    %% Template Engine
    subgraph "Template Engine"
        direction TB
        csr["csr_template.php"]:::template
        billingRef["invoice_billing_reference_template.php"]:::template
        invoiceLine["invoice_line_template.php"]:::template
        legalTotal["legal_monetary_total_template.php"]:::template
        simpleInvoice["simplified_tax_invoice_template.php"]:::template
        taxTotal["tax_total_template.php"]:::template
        sig["ubl_signature.php"]:::template
        sigProps["ubl_signature_signed_properties_for_signing_template.php"]:::template
        sigPropsFinal["ubl_signature_signed_properties_template.php"]:::template
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        composerJson["composer.json"]:::infra
        composerLock["composer.lock"]:::infra
        OpenSSL[(OpenSSL)]:::external
        PHP[(PHP Runtime)]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        ZATCAAPI[(ZATCA Web APIs)]:::external
        QRReader[(QR Reader Apps)]:::external
    end

    %% Data Flows
    index -->|"instantiate & call"| EGS
    phase1 -->|"instantiate & call"| EGS

    EGS -->|"generateNewKeysAndCSR() → CSR"| OpenSSL
    EGS -->|"issueComplianceCertificate()"| API
    API -->|"SOAP/REST"| ZATCAAPI
    ZATCAAPI -->|"certificate response"| API
    API -->|"returns cert"| EGS

    EGS -->|"signInvoice()"| Tag
    Tag -->|"uses specific Tags"| Tags
    Tags -->|"renders fragments"| csr
    csr & billingRef & invoiceLine & legalTotal & simpleInvoice & taxTotal & sig & sigProps & sigPropsFinal -->|"assemble XML"| EGS

    EGS -->|"generate QR payload"| QR
    QR -->|"base64 QR code"| index
    QR -->|"scanned"| QRReader

    EGS -->|"checkInvoiceCompliance()"| API
    API -->|"compliance response"| EGS

    %% Infra dependencies
    index & phase1 -->|"autoload"| composerJson
    composerJson -->|"locks deps"| composerLock
    EGS & API & QR & Tag & csr -->|"runs on"| PHP

    %% Click Events
    click index "https://github.com/sulaman0/zacta-phase2/blob/main/index.php"
    click phase1 "https://github.com/sulaman0/zacta-phase2/blob/main/phase-1.php"
    click EGS "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/EGS.php"
    click API "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/API.php"
    click QR "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/GenerateQrCode.php"
    click Tag "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/Tag.php"
    click Tags "https://github.com/sulaman0/zacta-phase2/tree/main/ZATCA/Tags/"
    click csr "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/csr_template.php"
    click billingRef "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/invoice_billing_reference_template.php"
    click invoiceLine "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/invoice_line_template.php"
    click legalTotal "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/legal_monetary_total_template.php"
    click simpleInvoice "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/simplified_tax_invoice_template.php"
    click taxTotal "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/tax_total_template.php"
    click sig "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/ubl_signature.php"
    click sigProps "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/ubl_signature_signed_properties_for_signing_template.php"
    click sigPropsFinal "https://github.com/sulaman0/zacta-phase2/blob/main/ZATCA/templates/ubl_signature_signed_properties_template.php"
    click composerJson "https://github.com/sulaman0/zacta-phase2/blob/main/composer.json"
    click composerLock "https://github.com/sulaman0/zacta-phase2/blob/main/composer.lock"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef service fill:#AED6F1,stroke:#1A5276,color:#154360
    classDef domain fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef template fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef infra fill:#E5E7E9,stroke:#626567,color:#424949
    classDef external fill:#A3E4D7,stroke:#117A65,color:#0E6655
```
