# miguelangarano/open-factura architecture

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

- Interactive diagram: https://gitdiagram.com/miguelangarano/open-factura
- Repository: https://github.com/miguelangarano/open-factura

## Overview

##### Project Type & Purpose
- This is an open-source Node/Bun library for electronic invoicing in Ecuador, following the SRI standards. It provides utilities to create invoice objects (with strong typing based on SRI specs), generate JSON and XML invoices, sign XML files, and interact with SRI’s endpoints (both for document reception and authorization).

##### Analyzing the File Structure
- The project’s core logic is in the “src” folder.
- The “src/baseData/invoice” directory contains various modules defining the invoice data structures (e.g., additionalInfo, details, tax info, retentions, etc.). This indicates a strong emphasis on domain modeling.
- The “src/services” folder hosts key business logic and operations:
- generateInvoice – responsible for constructing the invoice object.
- generateInvoiceXml – converts the invoice object to XML format.
- signing – handles the XML signing process using a .p12 certificate.
- reception – communicates with the SRI reception endpoint.
- authorization – handles the SRI document authorization.
- Utility functions reside under “src/utils” to support generic operations.
- “src/example” and the “tests” folder provide documented usage and sample cases, which can be considered while showing example flows.

##### Key Components
- External Client / Consumer:
- A Node or Bun application that uses the open-factura library. This is where the invoicing workflow starts.
- Invoice Domain & Data Structures:
- The baseData methods (invoice models) form the central data model. They encapsulate invoice details, tax information, and additional info as per SRI requirements.
- Service Modules:
- Invoice Generation: using generateInvoice to assemble the invoice object.
- XML Generation: converting the invoice to XML format.
- Signing Process: utilizing the signing service to securely sign the XML.
- Document Transmission: two separate modules for:
- Reception: sending the signed XML to the “RecepcionComprobantes” endpoint.
- Authorization: requesting invoice authorization from the “AutorizacionComprobantes” endpoint.
- Utilities:
- Helper functions supporting common operations across these services.
- External Endpoints:
- SRI Reception URL (for sending the invoice).
- SRI Authorization URL (for obtaining invoice authorization).

##### Relationships & Interactions
- The external client calls the library’s high-level functions (as shown in the provided code example).
- Data flows from invoice generation (using the domain models) to XML creation.
- The signing service takes the generated XML and a digital certificate (retrieved either from a local file or URL) to sign the XML.
- The signed XML is then forwarded to the SRI’s reception endpoint.
- Following reception, a subsequent call is made to the authorization endpoint.
- Throughout, utility functions assist with necessary operations.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The clear-cut division between data modeling (baseData), business logic (services), and utilities.
- Modular Design: With each function targeting a specific part of the invoice lifecycle (generation, signing, communication).
- External Integration: Defined clearly to interact with SRI endpoints.
- Extensibility: The layered architecture allows component replacements or enhancements as the specification evolves.

## Diagram (Mermaid)

```mermaid
graph TD
    CA["Client Application (External Consumer)"]:::client
    IG["Invoice Generation Service"]:::service
    ID["Invoice Domain & Data Models"]:::models
    XG["XML Generation Service"]:::service
    SS["Signing Service"]:::service
    DR["Document Reception Service"]:::service
    AU["Authorization Service"]:::service
    U["Utility Functions"]:::utility
    ER["SRI Reception Endpoint"]:::external
    EA["SRI Authorization Endpoint"]:::external

    CA -->|"calls"| IG
    IG -->|"buildsInvoiceObject"| ID
    ID -->|"generatesXML"| XG
    XG -->|"transformsXML"| SS
    SS -->|"sendsSignedXML"| DR
    DR -->|"callsReception"| ER
    DR -->|"callsAuthorization"| AU
    AU -->|"authorizesInvoice"| EA

    IG -.->|"assists"| U
    XG -.->|"assists"| U
    SS -.->|"assists"| U
    DR -.->|"assists"| U
    AU -.->|"assists"| U

    click CA "https://github.com/miguelangarano/open-factura/tree/main/src/example"
    click IG "https://github.com/miguelangarano/open-factura/blob/main/src/services/generateInvoice.ts"
    click ID "https://github.com/miguelangarano/open-factura/tree/main/src/baseData/invoice"
    click SS "https://github.com/miguelangarano/open-factura/blob/main/src/services/signing.ts"
    click DR "https://github.com/miguelangarano/open-factura/blob/main/src/services/reception.ts"
    click AU "https://github.com/miguelangarano/open-factura/blob/main/src/services/authorization.ts"
    click U "https://github.com/miguelangarano/open-factura/blob/main/src/utils/utils.ts"

    classDef client fill:#f9c,stroke:#333,stroke-width:2px
    classDef service fill:#afa,stroke:#333,stroke-width:2px
    classDef models fill:#bbf,stroke:#333,stroke-width:2px
    classDef utility fill:#ff9,stroke:#333,stroke-width:2px
    classDef external fill:#fdd,stroke:#333,stroke-width:2px
```
