# netvux/e-cf-doc architecture

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

- Interactive diagram: https://gitdiagram.com/netvux/e-cf-doc
- Repository: https://github.com/netvux/e-cf-doc

## Overview

##### Project Type and Purpose
- The project is an API-based electronic invoicing (facturación electrónica) system tailored for the Dominican Republic. It manages electronic fiscal document (ECF) processing in two environments: a test (pre-certification: “TesteCF”) environment and a live production (eCF) environment.
- The README outlines endpoints for authentication, reception, query, and status consultation of electronic invoices in both XML and JSON formats. It also handles special cases like Aprobación Comercial (ACECF) and range annulments.
- The file tree contains supporting artifacts: Postman collections for testing, sample XML files for different scenarios, XSDs for XML schema definitions (for validating different versions like e-CF31, e-CF32, etc.), and tabulated references (spreadsheets) that likely provide lookup values for codes and mappings.

##### Breaking Down the File Structure
- “Postman - JSON”: Contains collections useful for API testing and verification of endpoints.
- “Tablas”: Excel files that act as configuration or mapping tables (for tax codes, invoice types, etc.). They support validation and business logic decisions.
- “XMLs”: Sample XML documents representing various invoice submissions, errors, or responses.
- “XSDs”: XML schema definitions used to validate the structure and content of the incoming XML documents.
- README.md: Provides a detailed description of endpoints, environments, and sample request/response messages which is key to understanding the system’s flow.

##### Main Components
a. Client Applications:
- Representing external systems (contribuyentes or third-party integrators) that send requests like invoice submissions, queries, or authentication requests.
b. API Gateway/Endpoint Layer:
- The entry point for all requests. It should clearly differentiate between the two environments (pre-certification and production), since the URL paths indicate different domains (e.g., sandbox.netvux.com vs. ecf.netvux.com).
c. Authentication Service:
- A dedicated module that handles initial user authentication (accepting username, RNC, and token inputs) and issues time-based access tokens for subsequent requests.
d. ECF Processing Module:
- Responsible for receiving and processing both XML and JSON payloads. This component applies necessary validations (likely using the provided XSDs) and business rules before the processed document is either accepted or rejected.
e. DGII Integration/Communication Module:
- Facilitates the communication with the DGII systems. This module sends validated documents to DGII, receives responses (including security codes, tracking data, etc.), and interprets error messages or return information.
f. Environment Manager:
- Manages the separation between pre-certification and production environments, ensuring that routing, URL endpoints, and possibly data retention (such as the 60-day storage for pre-certification) are correctly managed.
g. Error Handling and Logging:
h. Reference/Data Lookup:
- Utilizes the “Tablas” files which serve as configuration data. These could be represented as auxiliary components that the ECF Processing Module or DGII Integration Module might reference during validation.

- Clients send authentication requests → Authentication Service returns a token.
- Clients use the token to submit XML/JSON to the API Gateway.
- API Gateway routes requests to the appropriate processing module.
- The ECF Processing Module validates the document (with XSD definitions) and then triggers the DGII Integration Module to forward the valid document.
- Responses, errors, or fiscal messages are then relayed back from the DGII Integration Module to the client.
- A clear separation between the incoming API layer, internal processing/bus logic (authentication, validation, error handling), and external integration with DGII systems.

##### Architectural Patterns and Design Principles
- Service segregation is important; each core functionality (authentication, document processing, external integration) should be depicted as separate modules or services.
- A layered architecture where the API Gateway acts as the interface layer, and the business logic is decoupled from external communications.
- Use of XML schema validation (via XSDs), which is a critical design element ensuring compliance with DGII standards.
- That the design supports multiple environments (test and production) and different data formats (XML and JSON), which may be implemented via polymorphic endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interaction
    subgraph "Client Interaction"
        A("Client Applications"):::client
    end

    %% API Layer
    subgraph "API Layer"
        B("API Gateway/Endpoint Layer"):::api
        C("Authentication Service"):::auth
    end

    %% Business Logic
    subgraph "Business Logic"
        F("Environment Manager"):::env
        subgraph "ECF Processing Module"
            D("Processing Core"):::processing
            L("XML Sample Invoices"):::xml
            M("XSD Validator"):::schema
        end
        E("DGII Integration Module"):::external
        G("Error Handling & Logging"):::error
    end

    %% Supporting Data
    subgraph "Supporting Data"
        H("Reference/Data Lookup"):::data
    end

    %% Flow Connections
    A -->|"authRequest"| C
    C -->|"tokenIssued"| A

    A -->|"invoiceSubmit"| B
    B -->|"routeUsingEnv"| F
    F -->|"forwardToProcessing"| D

    D -->|"processXML"| L
    D -->|"validateXML"| M
    D -->|"lookupConfig"| H
    D -->|"forwardValidDoc"| E
    E -->|"responseFromDGII"| D
    D -->|"result"| B
    B -->|"sendResponse"| A

    D -->|"errorTo"| G
    E -->|"errorTo"| G
    G -->|"notifyError"| B

    %% Click Events
    click A "https://github.com/netvux/e-cf-doc/tree/v2/Postman - JSON"
    click B "https://github.com/netvux/e-cf-doc/blob/v2/README.md"
    click C "https://github.com/netvux/e-cf-doc/blob/v2/README.md"
    click L "https://github.com/netvux/e-cf-doc/tree/v2/XMLs"
    click M "https://github.com/netvux/e-cf-doc/tree/v2/XSDs"
    click F "https://github.com/netvux/e-cf-doc/blob/v2/Postman - JSON/SandBox-Envi.json"
    click H "https://github.com/netvux/e-cf-doc/tree/v2/Tablas"

    %% Styles
    classDef client fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef api fill:#f9d9a9,stroke:#333,stroke-width:2px;
    classDef auth fill:#ffa9a9,stroke:#333,stroke-width:2px;
    classDef processing fill:#c0e4a8,stroke:#333,stroke-width:2px;
    classDef external fill:#f0c0ff,stroke:#333,stroke-width:2px;
    classDef env fill:#d0e0f0,stroke:#333,stroke-width:2px;
    classDef error fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef data fill:#e6e6fa,stroke:#333,stroke-width:2px;
    classDef schema fill:#fed8b1,stroke:#333,stroke-width:2px;
    classDef xml fill:#c4defc,stroke:#333,stroke-width:2px;
```
