# sat-cfdi/python-satcfdi architecture

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

- Interactive diagram: https://gitdiagram.com/sat-cfdi/python-satcfdi
- Repository: https://github.com/sat-cfdi/python-satcfdi

## Overview

##### Project Type and Purpose
- This is an open-source Python library (not a web app) called “satcfdi” for generating, processing, signing and rendering Mexican electronic invoices (CFDI, DIOT, PLD, Contabilidad Electrónica, Retenciones) and integrating with PAC/SAT services.
- It supplies both a CLI (satcfdi/cli/main.py) and a programmatic API for Python applications.

##### Top-Level Architectural Components
A. Entry Points
- CLI: satcfdi/cli/main.py — parses user commands for create, process, download, validate, export
- Python API: importable module “satcfdi” for embedding in other apps
B. Core Library Layers
1. Domain Models (satcfdi/models, satcfdi/cfdi.py, satcfdi/xelement.py)
– Python classes that represent CFDI, DIOT, PLD, Contabilidad, Retenciones, Certificates, Signer, etc.
2. Creation Layer (satcfdi/create/…)
– Subpackages for each document type (cfd, cancelación, contabilidad, pld, retención, w3 signatures)
– Factories that populate Domain Model objects
3. Processing & Transformation Layer
– XMLify & XSLT (satcfdi/transform/*.py, schemas/XSD & XSLT under transform/schemas)
– Signing & Certificates (satcfdi/certifica/pkcs7.py, satcfdi/models/certificate_*)
– Validation utilities (XML schema validation, listing SAT catalogs)
4. External Services & API Connectors (satcfdi/apis, satcfdi/pacs)
– HTTP wrappers for Banxico, Diverza, Finkok, Prodigia, SW Sapien, SAT (authentication, stamping, consulta, descarga)
5. Rendering Layer (satcfdi/render)
– Jinja2 templates for HTML/JSON (render/templates)
– PDF generation (via external library calls)
6. Utilities & I/O
– File I/O (read/write XML, JSON, ZIP)
– ZIP handling (satcfdi/zip.py)
– Common helpers (satcfdi/utils.py, satcfdi/sat_requests_utils.py)
C. Output Targets and Side-Effects
- Local File System (XML, JSON, HTML, PDF, Excel)
- PAC/SAT endpoints (send/receive web service calls)
- Read-the-Docs & GitHub Actions (documentation, tests, publishing pipelines)

##### Relationships & Data Flow
- CLI/API → Creation Layer: user specifies “create CFDI” → Python factory constructs Domain Model.
- Domain Model → Processing: transform to XML, sign certificate, validate against XSD.
- Processing → External Services: optional stamping/consulta/descarga via PAC connectors.
- Processed object → Rendering: render to JSON, HTML (single/multiple), PDF.
- Rendered output →File System.
- Loading existing XML: inverse path via Transform.Objectify → Domain Model.

##### Architectural Patterns & Principles
- Layered architecture: clear separation of concerns (model, creation, transform, render, API connectors).
- Plugin-style extensibility:
- “satcfdi/create” modules for each document type
- “satcfdi/pacs” connectors for each PAC provider
- Jinja2 templates for renderers
- Schema-driven transformation: uses XSD and XSLT under transform/schemas for strict validation and canonicalization.
- Domain-Driven Design: core Domain Models encapsulate invoice structure & behavior (sign, process).
- CLI facade over library with argparse (or click) to offer command-line usability.

##### Technologies & Frameworks
- Python 3.x
- Jinja2 for HTML/JSON templates
- requests (or urllib) for HTTP to external services
- lxml or xml.etree for XML handling
- cryptography / pkcs7 for digital signatures
- ZIP, base64, decimal, datetime from stdlib
- setuptools for packaging (setup.py)
- CI/CD via GitHub Actions (tests.yml, codeql.yml, publish.yml)
- ReadTheDocs for documentation, Sphinx under docs/

##### Detail Balance
- Essential high-level components; avoid listing every single file.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        direction TB
        CLI["CLI (satcfdi/cli/main.py)"]:::entry
        API["Python API (satcfdi/__init__.py)"]:::entry
    end

    %% Core Library Layers
    subgraph "Core Library"
        direction TB
        subgraph "Domain Models"
            DM1["satcfdi/models/"]:::core
            DM2["satcfdi/cfdi.py"]:::core
            DM3["satcfdi/xelement.py"]:::core
        end
        subgraph "Creation Layer"
            CL["satcfdi/create/"]:::core
        end
        subgraph "Processing & Transformation"
            PT1["xmlify.py"]:::core
            PT2["xslt.py"]:::core
            PT3["objectify.py"]:::core
            PT4["helpers.py"]:::core
            PT5["schemas.py"]:::core
            PT6["satcfdi/transform/schemas/"]:::core
        end
        subgraph "Signing & Certificates"
            SC1["satcfdi/certifica/pkcs7.py"]:::core
            SC2["satcfdi/models/certificate*.py"]:::core
        end
        subgraph "External Services & API Connectors"
            ES1["satcfdi/apis/banxico.py"]:::external
            ES2["satcfdi/apis/"]:::external
            ES3["satcfdi/pacs/"]:::external
            ES4["satcfdi/pacs/sat_templates/"]:::external
        end
        subgraph "Rendering Layer"
            R1["satcfdi/render/environment.py"]:::core
            R2["satcfdi/render/helpers.py"]:::core
            R3["satcfdi/render/templates/"]:::core
        end
        subgraph "Utilities & I/O"
            U1["satcfdi/utils.py"]:::core
            U2["satcfdi/sat_requests_utils.py"]:::core
            U3["satcfdi/zip.py"]:::core
            U4["satcfdi/ans1e.py"]:::core
        end
    end

    %% Output Targets
    subgraph "Outputs"
        direction TB
        FS["File System (XML/JSON/HTML/PDF)"]:::storage
        PAC["PAC/SAT Endpoints"]:::cloud
    end

    %% Connections
    CLI -->|"uses"| CL
    API -->|"imports"| DM1
    CL -->|"creates Domain Model"| DM1
    DM1 -->|"to XML"| PT1
    PT1 --> PT2
    PT2 -->|"validate"| PT5
    PT2 -->|"objectify"| PT3
    PT2 -->|"helpers"| PT4
    PT2 -->|"schemas files"| PT6
    PT3 --> DM1
    PT2 --> SC1
    SC1 --> SC2
    SC1 --> PAC
    PAC --> ES3
    ES2 --> PAC
    ES1 --> PAC
    ES4 --> ES3
    PT2 --> R1
    R1 --> R2
    R2 --> R3
    R3 --> FS
    U1 --> CLI
    U2 --> ES2
    U3 --> FS
    U4 --> FS

    %% Click Events
    click CLI "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/cli/main.py"
    click API "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/__init__.py"
    click DM1 "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/models/"
    click DM2 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/cfdi.py"
    click DM3 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/xelement.py"
    click CL "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/create/"
    click PT1 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/transform/xmlify.py"
    click PT2 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/transform/xslt.py"
    click PT3 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/transform/objectify.py"
    click PT4 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/transform/helpers.py"
    click PT5 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/transform/schemas.py"
    click PT6 "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/transform/schemas/"
    click SC1 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/certifica/pkcs7.py"
    click SC2 "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/models/"
    click ES1 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/apis/banxico.py"
    click ES2 "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/apis/"
    click ES3 "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/pacs/"
    click ES4 "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/pacs/sat_templates/"
    click R1 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/render/environment.py"
    click R2 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/render/helpers.py"
    click R3 "https://github.com/sat-cfdi/python-satcfdi/tree/main/satcfdi/render/templates/"
    click U1 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/utils.py"
    click U2 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/sat_requests_utils.py"
    click U3 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/zip.py"
    click U4 "https://github.com/sat-cfdi/python-satcfdi/blob/main/satcfdi/ans1e.py"

    %% Styles
    classDef entry fill:#a2f5a2,stroke:#3c763d,color:#000;
    classDef core fill:#cfe2f3,stroke:#2a6496,color:#000;
    classDef external fill:#fddf8c,stroke:#b45f06,color:#000;
    classDef storage fill:#dddddd,stroke:#999999,color:#000;
    classDef cloud fill:#fbc9a9,stroke:#a43f08,color:#000;
```
