# sartrebrasil/nfe architecture

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

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

## Overview

This is a Java library for creating, signing, validating, and transmitting Brazilian electronic fiscal documents (NF-e/NFC-e, CT-e, and MDF-e). The documented workflow is: configure environment and certificates, construct a document using schema-shaped Java classes, then use the version-specific WSFacade to sign, validate, transmit, and receive a Java response. The tree also shows document-key parsing, shared XML serialization, validation, and mutual-TLS/HTTP support. Facade workflow edges reflect the README; unsampled implementation details and links between separate document operations are intentionally omitted.

Main entry points: [`src/main/java/com/fincatto/documentofiscal/nfe400/webservices/WSFacade.java`](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/nfe400/webservices/WSFacade.java) (NF-e web services), [`src/main/java/com/fincatto/documentofiscal/DFConfig.java`](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/DFConfig.java) (Environment and credentials), [`src/main/java/com/fincatto/documentofiscal/cte400/webservices/WSFacade.java`](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/cte400/webservices/WSFacade.java) (CT-e web services), [`src/main/java/com/fincatto/documentofiscal/mdfe3/webservices/WSFacade.java`](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/mdfe3/webservices/WSFacade.java) (MDF-e web services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration and standards"]
  node_settings["Environment and credentials<br/>[DFConfig.java]"]
  node_standards["Document standards<br/>[DFModelo.java]"]
end

subgraph group_documents["Fiscal documents"]
  node_nfe_model["NF-e / NFC-e model"]
  node_cte_model["CT-e model"]
  node_mdfe_model["MDF-e model"]
  node_nfe_key["NF-e key parser"]
  node_cte_key["CT-e key parser<br/>[CTChaveParser.java]"]
  node_mdfe_key["MDF-e key parser"]
end

subgraph group_operations["SEFAZ operations"]
  node_nfe_facade["NF-e web services<br/>[WSFacade.java]"]
  node_cte_facade["CT-e web services<br/>[WSFacade.java]"]
  node_mdfe_facade["MDF-e web services<br/>[WSFacade.java]"]
  node_nfe_distribution["NF-e distribution"]
  node_cte_distribution["CT-e distribution"]
  node_mdfe_distribution["MDF-e distribution"]
end

subgraph group_transport["Transport and security"]
  node_tls["TLS context"]
  node_key_manager["Certificate key manager<br/>[DFKeyManager.java]"]
  node_http["SOAP HTTP client<br/>[DFHttpClient.java]"]
end

subgraph group_shared["Shared internals"]
  node_xml["XML serialization<br/>[DFBase.java]"]
  node_registry["XML transformers"]
  node_validation["Field validation"]
end

node_issuer(("Library user"))
node_sefaz(("SEFAZ services"))

node_issuer -->|"configures"| node_settings
node_issuer -->|"builds"| node_nfe_model
node_issuer -->|"builds"| node_cte_model
node_issuer -->|"builds"| node_mdfe_model
node_issuer -->|"invokes"| node_nfe_facade
node_issuer -->|"invokes"| node_cte_facade
node_issuer -->|"invokes"| node_mdfe_facade
node_nfe_facade -->|"transmits to"| node_sefaz
node_cte_facade -->|"transmits to"| node_sefaz
node_mdfe_facade -->|"transmits to"| node_sefaz
node_nfe_facade -->|"dispatches distribution"| node_nfe_distribution
node_sefaz -->|"returns response"| node_nfe_facade
node_sefaz -->|"returns response"| node_cte_facade
node_sefaz -->|"returns response"| node_mdfe_facade
node_settings -->|"provides credentials"| node_tls
node_tls -->|"creates"| node_key_manager
node_http -->|"reads timeouts"| node_settings
node_http -->|"uses TLS"| node_tls
node_nfe_key -->|"looks up model"| node_standards
node_cte_key -->|"looks up model"| node_standards
node_mdfe_key -->|"looks up model"| node_standards
node_xml -->|"uses transformers"| node_registry

click node_settings "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/DFConfig.java"
click node_standards "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/DFModelo.java"
click node_nfe_model "https://github.com/sartrebrasil/nfe/tree/master/src/main/java/com/fincatto/documentofiscal/nfe400"
click node_cte_model "https://github.com/sartrebrasil/nfe/tree/master/src/main/java/com/fincatto/documentofiscal/cte300/classes/nota"
click node_mdfe_model "https://github.com/sartrebrasil/nfe/tree/master/src/main/java/com/fincatto/documentofiscal/mdfe3"
click node_nfe_key "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/nfe310/parsers/NotaFiscalChaveParser.java"
click node_cte_key "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/cte300/parsers/CTChaveParser.java"
click node_mdfe_key "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/mdfe3/classes/parsers/MDFChaveParser.java"
click node_nfe_facade "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/nfe400/webservices/WSFacade.java"
click node_cte_facade "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/cte400/webservices/WSFacade.java"
click node_mdfe_facade "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/mdfe3/webservices/WSFacade.java"
click node_nfe_distribution "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/nfe/webservices/distribuicao/WSDistribuicaoNFe.java"
click node_cte_distribution "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/cte/webservices/distribuicao/WSDistribuicaoCTe.java"
click node_mdfe_distribution "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/mdfe/webservices/distribuicao/WSDistribuicaoMDFe.java"
click node_tls "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/utils/DFSocketFactory.java"
click node_key_manager "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/utils/DFKeyManager.java"
click node_http "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/utils/DFHttpClient.java"
click node_xml "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/DFBase.java"
click node_registry "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/transformers/DFRegistryMatcher.java"
click node_validation "https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/validadores/DFStringValidador.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_settings,node_standards,node_issuer toneBlue
class node_nfe_model,node_cte_model,node_mdfe_model,node_nfe_key,node_cte_key,node_mdfe_key toneAmber
class node_nfe_facade,node_cte_facade,node_mdfe_facade,node_nfe_distribution,node_cte_distribution,node_mdfe_distribution toneMint
class node_tls,node_key_manager,node_http toneRose
class node_xml,node_registry,node_validation,node_sefaz toneIndigo
```

## Components

### Configuration and standards

- [Environment and credentials](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/DFConfig.java): `src/main/java/com/fincatto/documentofiscal/DFConfig.java`
- [Document standards](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/DFModelo.java): `src/main/java/com/fincatto/documentofiscal/DFModelo.java`

### Fiscal documents

- [NF-e / NFC-e model](https://github.com/sartrebrasil/nfe/tree/master/src/main/java/com/fincatto/documentofiscal/nfe400): `src/main/java/com/fincatto/documentofiscal/nfe400`
- [CT-e model](https://github.com/sartrebrasil/nfe/tree/master/src/main/java/com/fincatto/documentofiscal/cte300/classes/nota): `src/main/java/com/fincatto/documentofiscal/cte300/classes/nota`
- [MDF-e model](https://github.com/sartrebrasil/nfe/tree/master/src/main/java/com/fincatto/documentofiscal/mdfe3): `src/main/java/com/fincatto/documentofiscal/mdfe3`
- [NF-e key parser](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/nfe310/parsers/NotaFiscalChaveParser.java): `src/main/java/com/fincatto/documentofiscal/nfe310/parsers/NotaFiscalChaveParser.java`
- [CT-e key parser](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/cte300/parsers/CTChaveParser.java): `src/main/java/com/fincatto/documentofiscal/cte300/parsers/CTChaveParser.java`
- [MDF-e key parser](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/mdfe3/classes/parsers/MDFChaveParser.java): `src/main/java/com/fincatto/documentofiscal/mdfe3/classes/parsers/MDFChaveParser.java`

### SEFAZ operations

- [NF-e web services](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/nfe400/webservices/WSFacade.java): `src/main/java/com/fincatto/documentofiscal/nfe400/webservices/WSFacade.java`
- [CT-e web services](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/cte400/webservices/WSFacade.java): `src/main/java/com/fincatto/documentofiscal/cte400/webservices/WSFacade.java`
- [MDF-e web services](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/mdfe3/webservices/WSFacade.java): `src/main/java/com/fincatto/documentofiscal/mdfe3/webservices/WSFacade.java`
- [NF-e distribution](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/nfe/webservices/distribuicao/WSDistribuicaoNFe.java): `src/main/java/com/fincatto/documentofiscal/nfe/webservices/distribuicao/WSDistribuicaoNFe.java`
- [CT-e distribution](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/cte/webservices/distribuicao/WSDistribuicaoCTe.java): `src/main/java/com/fincatto/documentofiscal/cte/webservices/distribuicao/WSDistribuicaoCTe.java`
- [MDF-e distribution](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/mdfe/webservices/distribuicao/WSDistribuicaoMDFe.java): `src/main/java/com/fincatto/documentofiscal/mdfe/webservices/distribuicao/WSDistribuicaoMDFe.java`

### Transport and security

- [TLS context](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/utils/DFSocketFactory.java): `src/main/java/com/fincatto/documentofiscal/utils/DFSocketFactory.java`
- [Certificate key manager](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/utils/DFKeyManager.java): `src/main/java/com/fincatto/documentofiscal/utils/DFKeyManager.java`
- [SOAP HTTP client](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/utils/DFHttpClient.java): `src/main/java/com/fincatto/documentofiscal/utils/DFHttpClient.java`

### Shared internals

- [XML serialization](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/DFBase.java): `src/main/java/com/fincatto/documentofiscal/DFBase.java`
- [XML transformers](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/transformers/DFRegistryMatcher.java): `src/main/java/com/fincatto/documentofiscal/transformers/DFRegistryMatcher.java`
- [Field validation](https://github.com/sartrebrasil/nfe/blob/master/src/main/java/com/fincatto/documentofiscal/validadores/DFStringValidador.java): `src/main/java/com/fincatto/documentofiscal/validadores/DFStringValidador.java`

### Other components

- **Library user**
- **SEFAZ services**

## Connections

- Library user → Environment and credentials: configures
- Library user → NF-e / NFC-e model: builds
- Library user → CT-e model: builds
- Library user → MDF-e model: builds
- Library user → NF-e web services: invokes
- Library user → CT-e web services: invokes
- Library user → MDF-e web services: invokes
- NF-e web services → SEFAZ services: transmits to
- CT-e web services → SEFAZ services: transmits to
- MDF-e web services → SEFAZ services: transmits to
- NF-e web services → NF-e distribution: dispatches distribution (evidence: `src/main/java/com/fincatto/documentofiscal/nfe400/webservices/WSFacade.java`)
- SEFAZ services → NF-e web services: returns response
- SEFAZ services → CT-e web services: returns response
- SEFAZ services → MDF-e web services: returns response
- Environment and credentials → TLS context: provides credentials (evidence: `src/main/java/com/fincatto/documentofiscal/utils/DFSocketFactory.java`)
- TLS context → Certificate key manager: creates (evidence: `src/main/java/com/fincatto/documentofiscal/utils/DFSocketFactory.java`)
- SOAP HTTP client → Environment and credentials: reads timeouts (evidence: `src/main/java/com/fincatto/documentofiscal/utils/DFHttpClient.java`)
- SOAP HTTP client → TLS context: uses TLS (evidence: `src/main/java/com/fincatto/documentofiscal/utils/DFHttpClient.java`)
- NF-e key parser → Document standards: looks up model (evidence: `src/main/java/com/fincatto/documentofiscal/nfe310/parsers/NotaFiscalChaveParser.java`)
- CT-e key parser → Document standards: looks up model (evidence: `src/main/java/com/fincatto/documentofiscal/cte300/parsers/CTChaveParser.java`)
- MDF-e key parser → Document standards: looks up model (evidence: `src/main/java/com/fincatto/documentofiscal/mdfe3/classes/parsers/MDFChaveParser.java`)
- XML serialization → XML transformers: uses transformers (evidence: `src/main/java/com/fincatto/documentofiscal/DFBase.java`)