# asamirsherif/zatca-integration architecture

> Architecture diagram of the GitHub repository asamirsherif/zatca-integration, 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/asamirsherif/zatca-integration
- Repository: https://github.com/asamirsherif/zatca-integration

## Overview

##### Project type and purpose
- This is a Laravel-compatible PHP package (a composer library) whose purpose is to integrate with ZATCA API servers and generate TLV-encoded, signed QR codes for Saudi Arabia’s e-invoicing requirements.
- It is not a standalone full-stack app but a reusable package that plugs into a Laravel application via a ServiceProvider and Facade.

##### File structure
- Top-level files
- composer.json – package metadata, dependencies, PSR-4 autoload rules
- Readme.md – usage instructions
- LICENSE, .gitignore
- src/
- Facades/Zatca.php – Laravel Facade interface
- ZatcaServiceProvider.php – registers the service binding and facade alias
- Zatca.php – core service class that provides the TLV builder, API calls, and code generation
- Utilis/Tag.php – builds TLV tags
- Utilis/QrCodeOptions.php – DTO for QR code rendering options
- helpers.php – global helper functions (e.g., zatca(), qrCodeOptions() shortcuts)

##### Key insights from the README
- The flow: consumer calls Zatca facade → sets sellerName, VAT, timestamp, totals → calls toBase64() or toQrCode() → package generates TLV binary or renders a QR code with the given options.
- Laravel auto-discovery means no manual registration is normally needed.

##### Components and relationships
a. Main components
- Consuming Laravel Application (Client)
- Laravel Service Container
- ZatcaServiceProvider (binds Zatca class into the container)
- Zatca Facade (static interface to underlying service)
- Core Zatca Service (Asamirsherif\Zatca\Zatca)
- TLV Builder (Utilis\Tag)
- QR Code Generator (external library dependency, invoked inside Zatca)
- QrCodeOptions DTO
- External ZATCA API Endpoint (optional if phase-two implements real API calls)
b. Relationships and data flow
1. Client code invokes `Zatca::sellerName(...)->…->toBase64()/toQrCode()`
2. Facade routes the call through Laravel’s Service Container to the Zatca Service instance
3. Zatca Service uses Tag to assemble TLV segments in the correct sequence
4. For Base64: Zatca Service encodes TLV to Base64 and returns
5. For QR Code: Zatca Service calls QR library, passing in the TLV Base64 and QrCodeOptions parameters, then returns an image/svg or PNG
6. (Future) Zatca Service may also sign or POST data to the ZATCA API server and validate responses
c. Architectural patterns and principles
- Facade pattern: simplifies consumer interface
- Service Provider / IoC Container: decouples instantiation
- Single Responsibility: Tag handles TLV encoding, QrCodeOptions holds config, Zatca Service orchestrates processes
- Extensibility: hooks/helpers for adding options or swapping QR library
d. Technologies and libraries
- PHP 7+ / Composer for autoload and dependency management
- Laravel’s Service Container & Facades
- Endroid QR Code or similar underlying QR library (implicit)
- PSR-4 autoloading

##### Elements
- Facade → Service Container → Zatca Service
- Zatca Service → Tag (build TLV)
- Zatca Service → QR Library (render)
- (Optional) Zatca Service ↔ External API
- Host application in another
- External dependencies/services in a third

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Laravel Host"
        App["Laravel App\n(Client)"]:::host
        ServiceContainer["Service Container"]:::host
    end

    subgraph "Package Internals"
        SvcProvider["ZatcaServiceProvider"]:::internal
        ZFacade["Zatca Facade"]:::internal
        ZService["Zatca Service"]:::internal
        Tag["TLV Builder\n(Tag)"]:::internal
        Options["QrCodeOptions DTO"]:::internal
        Helpers["Global Helpers"]:::internal
    end

    QRLib["QR Library"]:::external
    ExtAPI["External ZATCA API"]:::external

    subgraph "Documentation"
        Composer["composer.json"]:::internal
        Readme["Readme.md"]:::internal
        DiagramRef["Untitled Diagram.drawio"]:::internal
    end

    App -->|calls facade| ZFacade
    ZFacade -->|"resolves via"| ServiceContainer
    ServiceContainer -->|binds service| SvcProvider
    ServiceContainer -->|provides instance| ZService
    ZService -->|builds TLV| Tag
    ZService -->|uses options| Options
    ZService -->|encodes and renders| QRLib
    ZService -.->|optional API calls| ExtAPI
    App -->|helper shortcuts| Helpers

    click SvcProvider "https://github.com/asamirsherif/zatca-integration/blob/master/src/ZatcaServiceProvider.php"
    click ZFacade "https://github.com/asamirsherif/zatca-integration/blob/master/src/Facades/Zatca.php"
    click ZService "https://github.com/asamirsherif/zatca-integration/blob/master/src/Zatca.php"
    click Tag "https://github.com/asamirsherif/zatca-integration/blob/master/src/Utilis/Tag.php"
    click Options "https://github.com/asamirsherif/zatca-integration/blob/master/src/Utilis/QrCodeOptions.php"
    click Helpers "https://github.com/asamirsherif/zatca-integration/blob/master/src/helpers.php"
    click Composer "https://github.com/asamirsherif/zatca-integration/blob/master/composer.json"
    click Readme "https://github.com/asamirsherif/zatca-integration/blob/master/Readme.md"
    click DiagramRef "https://github.com/asamirsherif/zatca-integration/blob/master/src/Utilis/Untitled Diagram.drawio"

    classDef host fill:#e0f7fa,stroke:#006064,color:#006064
    classDef internal fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef external fill:#ffebee,stroke:#c62828,color:#c62828
```
