# ferreiramg/nfe architecture

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

- Interactive diagram: https://gitdiagram.com/ferreiramg/nfe
- Repository: https://github.com/ferreiramg/nfe

## Overview

##### Project type and purpose
- This is a PHP SDK (library) for generating, signing, sending and validating Brazilian electronic invoices (NFe) against SEFAZ web-services.
- There is no UI: it’s a backend tool that transforms invoice data into XML, applies X.509 certificates, performs schema and certificate validation, sends requests over SOAP/HTTP, and processes responses.

##### File structure
- Top-level:
- conf/ – runtime configuration (API endpoints, certificates store)
- src/ – all production code, organized by concern:
– Certificates/ (Certificate, PrivateKey, PublicKey, interfaces)
– Template/ (TemplateXMLElement)
– Filters/Validates/ (SchemaValidate, ValidateCertificate)
– Request/ (PrepareRequest, ClientStream)
– Service/ (AbstractService, InterfaceService, Status)
– Core classes (Base, SignNFe, DecorateProcess, ProcessTemplate, ProccessInterface)
– Exceptions/ (domain and request errors)
- autoload.php + composer.json – PSR-4 autoloading and dependencies
- test/ – PHPUnit test suites, fixtures, certificate samples

##### README
- Very minimal: shows how to clone, composer update, set up config in conf/api.conf.public.php, run phpunit.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% SDK Entry
    subgraph "SDK Entry"
        SignNFe["SignNFe (Entry Point)"]:::processing
        Autoload["src/autoload.php"]:::processing
        Composer["composer.json"]:::processing
    end

    SignNFe --> Autoload
    SignNFe --> Composer
    Autoload --> ConfigurationLoader
    Composer --> ConfigurationLoader

    %% Configuration
    ConfigurationLoader["Configuration Loader"]:::input
    ServiceEndpointsConfig["Service Endpoints Config"]:::input

    ConfigurationLoader --> ServiceEndpointsConfig

    %% Input & Templating
    InputInvoice["Input: Invoice Data"]:::input
    InputInvoice --> Template
    Template["TemplateXMLElement"]:::input

    %% Process Orchestrator
    Template --> ProcessTemplate
    subgraph "Process Orchestrator"
        direction TB
        ProcessTemplate["ProcessTemplate"]:::processing
        ProccessInterface["ProccessInterface"]:::processing
        DecorateProcess["DecorateProcess"]:::processing
    end
    ProcessTemplate --> ProccessInterface
    ProccessInterface --> DecorateProcess

    %% Validation Filters
    DecorateProcess --> SchemaValidate
    DecorateProcess --> ValidateCertificate
    SchemaValidate["SchemaValidate"]:::processing
    ValidateCertificate["ValidateCertificate"]:::processing

    %% Certificate Manager
    DecorateProcess --> CertificateManager
    subgraph "Certificate Manager"
        direction TB
        Certificate["Certificate"]:::processing
        PrivateKey["PrivateKey"]:::processing
        PublicKey["PublicKey"]:::processing
        Certified["Certified"]:::processing
        SignatureInterface["SignatureInterface"]:::processing
        VerificationInterface["VerificationInterface"]:::processing
    end
    ValidateCertificate --> CertificateManager
    CertificateManager --> Certificate
    CertificateManager --> PrivateKey
    CertificateManager --> PublicKey
    CertificateManager --> Certified
    CertificateManager --> SignatureInterface
    CertificateManager --> VerificationInterface

    %% Signing
    CertificateManager --> Signer
    Signer["Signer"]:::processing
    Signer --> PrepareRequest

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        PrepareRequest["PrepareRequest"]:::transport
        ClientStream["ClientStream"]:::transport
        SEFAZ["SEFAZ Web-Service"]:::external
    end
    PrepareRequest --> ClientStream
    ClientStream --> SEFAZ

    %% Response Handling
    subgraph "Response Handling"
        direction TB
        ResponseParser["Response Parser"]:::processing
        AbstractService["AbstractService"]:::processing
        InterfaceService["InterfaceService"]:::processing
        Status["Status"]:::processing
        CertificateException["CertificateException"]:::error
        SchemaXmlException["SchemaXmlException"]:::error
        NFeRequestException["NFeRequestException"]:::error
        NFeException["NFeException"]:::error
    end
    SEFAZ --> ResponseParser
    ResponseParser --> AbstractService
    AbstractService --> InterfaceService
    InterfaceService --> Status
    ResponseParser --> CertificateException
    ResponseParser --> SchemaXmlException
    ResponseParser --> NFeRequestException
    ResponseParser --> NFeException

    %% Click Events
    click ConfigurationLoader "https://github.com/ferreiramg/nfe/blob/master/conf/api.conf.public.php"
    click ServiceEndpointsConfig "https://github.com/ferreiramg/nfe/blob/master/conf/url-services.xml"
    click Template "https://github.com/ferreiramg/nfe/blob/master/src/Template/TemplateXMLElement.php"
    click ProcessTemplate "https://github.com/ferreiramg/nfe/blob/master/src/ProccessTemplate.php"
    click ProccessInterface "https://github.com/ferreiramg/nfe/blob/master/src/ProccessInterface.php"
    click DecorateProcess "https://github.com/ferreiramg/nfe/blob/master/src/DecorateProcess.php"
    click SchemaValidate "https://github.com/ferreiramg/nfe/blob/master/src/Filters/Validates/SchemaValidate.php"
    click ValidateCertificate "https://github.com/ferreiramg/nfe/blob/master/src/Filters/Validates/ValidateCertificate.php"
    click Certificate "https://github.com/ferreiramg/nfe/blob/master/src/Certificates/Certificate.php"
    click PrivateKey "https://github.com/ferreiramg/nfe/blob/master/src/Certificates/PrivateKey.php"
    click PublicKey "https://github.com/ferreiramg/nfe/blob/master/src/Certificates/PublicKey.php"
    click Certified "https://github.com/ferreiramg/nfe/blob/master/src/Certificates/Certified.php"
    click SignatureInterface "https://github.com/ferreiramg/nfe/blob/master/src/Certificates/SignatureInterface.php"
    click VerificationInterface "https://github.com/ferreiramg/nfe/blob/master/src/Certificates/VerificationInterface.php"
    click SignNFe "https://github.com/ferreiramg/nfe/blob/master/src/SignNFe.php"
    click PrepareRequest "https://github.com/ferreiramg/nfe/blob/master/src/Request/PrepareRequest.php"
    click ClientStream "https://github.com/ferreiramg/nfe/blob/master/src/Request/ClientStream.php"
    click AbstractService "https://github.com/ferreiramg/nfe/blob/master/src/Service/AbstractSevice.php"
    click InterfaceService "https://github.com/ferreiramg/nfe/blob/master/src/Service/InterfaceService.php"
    click Status "https://github.com/ferreiramg/nfe/blob/master/src/Service/Status.php"
    click CertificateException "https://github.com/ferreiramg/nfe/blob/master/src/Exception/CertificateException.php"
    click SchemaXmlException "https://github.com/ferreiramg/nfe/blob/master/src/Exception/SchemaXmlException.php"
    click NFeRequestException "https://github.com/ferreiramg/nfe/blob/master/src/Exception/NFeRequestException.php"
    click NFeException "https://github.com/ferreiramg/nfe/blob/master/src/Exception/NFeException.php"

    %% Styles
    classDef input fill:#AED6F1,stroke:#0174DF,color:#000;
    classDef processing fill:#F5B041,stroke:#B9770E,color:#000;
    classDef transport fill:#ABEBC6,stroke:#229954,color:#000;
    classDef error fill:#F1948A,stroke:#C0392B,color:#000;
    classDef external fill:#D5DBDB,stroke:#7B7D7D,color:#000;
```
