# eclipxe13/sat-ws-descarga-masiva architecture

> Architecture diagram of the GitHub repository eclipxe13/sat-ws-descarga-masiva, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eclipxe13/sat-ws-descarga-masiva
- Repository: https://github.com/eclipxe13/sat-ws-descarga-masiva

## Overview

##### Main Components and Their Roles
- Service Facade: The central “Service” class (located in src/Service.php) serves as the main entry point that ties together the process flow. It takes in a RequestBuilder and a WebClient.
- Web Client: Represent the component under src/WebClient (e.g., GuzzleWebClient) which implements WebClientInterface. This client is responsible for performing the HTTP/HTTPS communications with the SAT servers.
- Service Operations: Under src/Services, distinct namespaces for different functionalities exist:
- Authenticate – for handling token generation via FIEL based authentication.
- Query – for presenting the service request with parameters (using classes like QueryParameters).
- Verify – to check the status of a previously submitted request.
- Download – for retrieving the ZIP packages from the SAT.
- Package Readers: The functionality for processing downloaded packages is encapsulated in the PackageReader folder. Two major readers exist – CfdiPackageReader for CFDI XML packages and MetadataPackageReader for metadata ZIP packages.
- Internal Helpers: Various helper traits and classes (src/Internal, src/PackageReader/Internal) are used to encapsulate common logic like XML interactions, file filtering, and data manipulation.

##### Relationships and Data Flow
- This RequestBuilder is then passed, together with a configured WebClient (GuzzleWebClient), into the Service facade.
- The Service orchestrates:
- Authentication: using the FIEL via the RequestBuilder to obtain a Token.
- Query: the Service accepts a QueryParameters object (built using Shared types and RequestBuilder) and sends a signed request to SAT.
- Verification: after query submission, the client polls (or is informed through a verification call) the status of the request.
- Download: the Service then accepts package identifiers to retrieve ZIP packages.
- Package Readers: Once downloaded, these packages are parsed through the respective PackageReader classes to extract either CFDI XML files or metadata.
- Data flows from domain objects (the input parameters) to SOAP messages and back as response packages. Exceptions at any layer (e.g., in web communication or file operations within PackageReaders) should be represented as error flows back to the client.

##### Architectural Patterns / Design Principles
- Separation of Concerns: The library separates the responsibility of request creation (RequestBuilder), communication (WebClient), process orchestration (Service), and package processing (PackageReader).
- Interface-Based Design: Use of interfaces like RequestBuilderInterface and WebClientInterface allows for flexible, interchangeable implementations.
- Domain Modeling: The use of shared classes (e.g., DateTimePeriod, DocumentStatus, DownloadType, etc.) indicates a clear domain-driven design where business rules encapsulate the logic.

##### Relevant Technologies and Libraries
- PHP (as the main language).
- Composer (dependency management).
- Guzzle (for HTTP communication) as an example of WebClient use.
- SOAP-based communication (for interacting with SAT services).
- ZIP file manipulation for processing attachments.
- Optionally, mention integration with external packages (e.g., phpcfdi/credentials) for FIEL management.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Application Layer"
        A_Client["Client Application"]:::application
        A_Builder["FIEL RequestBuilder"]:::builder
        A_Web["Web Client (GuzzleWebClient)"]:::web
        A_Client -->|"initializes"| A_Builder
        A_Client -->|"initializes"| A_Web
    end

    subgraph "Service Orchestration"
        B_Service["Service Facade"]:::facade
        A_Builder --> B_Service
        A_Web --> B_Service

        subgraph "Service Operations"
            B_Auth["Authenticate (AuthenticateTranslator)"]:::serviceOp
            B_Query["Query (QueryParameters)"]:::serviceOp
            B_Verify["Verify (VerifyTranslator)"]:::serviceOp
            B_Download["Download (DownloadTranslator)"]:::serviceOp
        end
        B_Service -->|"authenticates"| B_Auth
        B_Service -->|"queries"| B_Query
        B_Service -->|"verifies"| B_Verify
        B_Service -->|"downloads"| B_Download
    end

    subgraph "Package Processing"
        C_CFDI["CFDI Package Reader (CfdiPackageReader)"]:::package
        C_Meta["Metadata Package Reader (MetadataPackageReader)"]:::package
        B_Download -->|"parses"| C_CFDI
        B_Download -->|"parses"| C_Meta
    end

    subgraph "Shared Components"
        D_Domain["Shared Domain Objects"]:::domain
        D_InternalCore["Internal Helpers (Core)"]:::internal
        D_InternalPackage["Internal Helpers (Package)"]:::internal
    end

    A_Builder -->|"uses"| D_Domain
    B_Auth -->|"uses"| D_Domain
    B_Query -->|"uses"| D_Domain
    B_Verify -->|"uses"| D_Domain
    B_Download -->|"uses"| D_Domain

    A_Builder -->|"assists"| D_InternalCore
    C_CFDI -->|"assists"| D_InternalPackage
    C_Meta -->|"assists"| D_InternalPackage

    B_Auth -.->|"error"| A_Client
    B_Query -.->|"error"| A_Client
    B_Verify -.->|"error"| A_Client
    B_Download -.->|"error"| A_Client

    click B_Service "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/Service.php"
    click A_Builder "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/RequestBuilder/FielRequestBuilder/FielRequestBuilder.php"
    click A_Web "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/WebClient/GuzzleWebClient.php"
    click B_Auth "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/Services/Authenticate/AuthenticateTranslator.php"
    click B_Query "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/Services/Query/QueryParameters.php"
    click B_Verify "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/Services/Verify/VerifyTranslator.php"
    click B_Download "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/Services/Download/DownloadTranslator.php"
    click C_CFDI "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/PackageReader/CfdiPackageReader.php"
    click C_Meta "https://github.com/eclipxe13/sat-ws-descarga-masiva/blob/main/src/PackageReader/MetadataPackageReader.php"
    click D_Domain "https://github.com/eclipxe13/sat-ws-descarga-masiva/tree/main/src/Shared"
    click D_InternalCore "https://github.com/eclipxe13/sat-ws-descarga-masiva/tree/main/src/Internal"
    click D_InternalPackage "https://github.com/eclipxe13/sat-ws-descarga-masiva/tree/main/src/PackageReader/Internal"

    classDef application fill:#f9e79f,stroke:#B7950B,stroke-width:2px;
    classDef builder fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef web fill:#d6eaf8,stroke:#2e86c1,stroke-width:2px;
    classDef facade fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef serviceOp fill:#f5eef8,stroke:#8e44ad,stroke-width:2px;
    classDef package fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef domain fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef internal fill:#d6dbdf,stroke:#566573,stroke-width:2px;
```
