# victors1681/dgii-ecf architecture

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

- Interactive diagram: https://gitdiagram.com/victors1681/dgii-ecf
- Repository: https://github.com/victors1681/dgii-ecf

## Overview

##### Project Type and Purpose
- This is a server-side Node.js library/package focused on electronic invoicing.
- Its primary responsibilities include authentication using digital certificates, signing XML documents, interacting (sending/receiving) with DGII API endpoints, and providing utilities for processing and validating electronic invoices.
- The README makes it clear this package is to be used only on server-side applications due to sensitive information handling.

##### Key Components from the File Structure
- Core Modules:
- P12Reader (src/P12Reader.ts): Handles reading and extracting the certificate (P12) details.
- Signature (located in src/Signature/): Manages signing of XML documents and contains custom implementations as well as tests.
- ECF (src/ecf/ECF.ts): Central class for authentication with DGII, sending invoices, inquiring status, and handling the overall eCF flow.
- CustomAuthentication (src/customAuthentication/CustomAuthentication.ts): Provides endpoints to generate seeds, verify signed seeds, and handle JWT tokens.
- Transformer (src/transformers/Transformer.ts): Converts JSON objects into their XML representations.
- SenderReceiver (src/senderReceiver/SenderReceiver.ts): Formats the responses for message communications between sender and receiver systems.
- Networking (src/networking/): Contains modules that produce and invoke REST API calls towards the DGII or related external endpoints.
- Utilities (src/utils/): Helper functions like generating QR codes, formatting dates, validating XML certificates, and other common tasks.
- Certification modules (src/certification/): Might include specialized functions for handling commercial approvals.
- Tests are thoroughly spread among the components (look for __tests__ directories), showing a commitment to integration/unit testing.

##### Identifying Relationships and Data Flow
- A client (Node.js application) will use this package. The flow typically starts by:
- Using P12Reader to extract the certificate and key from a .p12 file.
- Passing the credentials to the Signature class to sign XML or to the ECF class for authentication.
- The ECF class then utilizes components from networking to send signed XML documents, authenticate, check statuses, and handle responses from DGII.
- For custom authentication, the CustomAuthentication module handles generating and verifying seeds, and issuing tokens.
- Transformer is used when the data for invoices is provided as JSON and needs conversion to XML before being signed.
- The SenderReceiver module formats responses and handles communication details once data is sent/received.
- External dependency is the DGII API, which is communicated with via REST calls (handled in networking).

##### Architectural Patterns and Principles
- Separation of Concerns:
- Each module addresses a distinct aspect: certificate handling, XML signing, REST communication, transformation, etc.
- Layered Architecture:
- The lower layers (utilities and networking) support the higher-level operations (ECF and CustomAuthentication).
- Integration with External Systems:
- Clear demarcation between internal components and external DGII endpoints along with optional buyer endpoints.
- Test Driven:
- The presence of extensive __tests__ directories encourages depicting testability as an aspect of the design.

##### Technology and Integration Details
- Node.js/TypeScript is used, with configuration files (.babelrc, tsconfig.json) for build and linting.
- Testing is set up via Jest.
- External integrations include DGII endpoints, which are handled in the ECF and networking modules.

##### Additional Details
- Boundaries between server-side components (the library) and external systems (DGII API, optional buyer endpoints) distinctly.
- Annotations for data flow steps—especially the authentication process using a seed XML, signing process, and subsequent API calls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client layer
    CA("Client Application"):::client

    %% Core Processing Layer
    subgraph "Core Processing"
        P12["P12Reader (Certificate Extraction)"]:::core
        SIGN["Signature Engine (XML Signing)"]:::core
        TRANS["Transformer (JSON to XML Conversion)"]:::core
        ECF["ECF Module (Authentication & Invoice Operations)"]:::core
        CUSTAUTH["Custom Authentication Module"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        NET["Networking (REST API Calls)"]:::support
        SR["SenderReceiver (Message Formatter)"]:::support
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        UTIL["Utilities (Helper Functions)"]:::support
        CERT["Certification Modules (Commercial Approvals)"]:::support
    end

    %% External Integration
    EXT("DGII API"):::external

    %% Data Flow
    CA --> P12
    P12 --> SIGN
    TRANS --> SIGN
    SIGN --> ECF
    CUSTAUTH --> ECF
    ECF --> NET
    NET -->|"calls"| EXT
    NET --> SR
    ECF --> UTIL
    ECF --> CERT
    CUSTAUTH --> UTIL

    %% Click Events
    click P12 "https://github.com/victors1681/dgii-ecf/blob/main/src/P12Reader.ts"
    
    click SIGN "https://github.com/victors1681/dgii-ecf/blob/main/src/Signature/Signature.ts"
    click SIGN "https://github.com/victors1681/dgii-ecf/tree/main/src/Signature/custom"
    
    click ECF "https://github.com/victors1681/dgii-ecf/blob/main/src/ecf/ECF.ts"
    click ECF "https://github.com/victors1681/dgii-ecf/blob/main/src/ecf/index.ts"
    
    click CUSTAUTH "https://github.com/victors1681/dgii-ecf/blob/main/src/customAuthentication/CustomAuthentication.ts"
    click CUSTAUTH "https://github.com/victors1681/dgii-ecf/blob/main/src/customAuthentication/index.ts"
    
    click TRANS "https://github.com/victors1681/dgii-ecf/blob/main/src/transformers/Transformer.ts"
    click TRANS "https://github.com/victors1681/dgii-ecf/blob/main/src/transformers/index.ts"
    
    click SR "https://github.com/victors1681/dgii-ecf/blob/main/src/senderReceiver/SenderReceiver.ts"
    click SR "https://github.com/victors1681/dgii-ecf/blob/main/src/senderReceiver/index.ts"
    
    click NET "https://github.com/victors1681/dgii-ecf/blob/main/src/networking/RestApi.ts"
    click NET "https://github.com/victors1681/dgii-ecf/blob/main/src/networking/restClient.ts"
    click NET "https://github.com/victors1681/dgii-ecf/blob/main/src/networking/index.ts"
    
    click UTIL "https://github.com/victors1681/dgii-ecf/tree/main/src/utils/"
    
    click CERT "https://github.com/victors1681/dgii-ecf/blob/main/src/certification/commercialApproval.ts"

    %% Styles
    classDef client fill:#f2f2f2,stroke:#333,stroke-width:2px;
    classDef core fill:#ffd1dc,stroke:#a00,stroke-width:2px;
    classDef support fill:#d1eaff,stroke:#007,stroke-width:2px;
    classDef external fill:#d1ffd1,stroke:#070,stroke-width:2px;
```
