# villano14/sunat-go architecture

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

- Interactive diagram: https://gitdiagram.com/villano14/sunat-go
- Repository: https://github.com/villano14/sunat-go

## Overview

sunat-go is a library for preparing Peruvian electronic tax documents and submitting them to SUNAT. Its main workflow accepts caller-provided document data, renders UBL, signs the XML, sends it through the relevant SOAP or GRE REST interface, and parses returned CDRs or status. The graph also preserves optional calculations, document catalogs, purchase settlements, batch summaries/reversions, withholding documents, status queries, and caller-prepared ZIP packs. Some flow links are based on README documentation because their implementation excerpts were not provided.

Main entry points: [`sunat_gre.go`](https://github.com/villano14/sunat-go/blob/main/sunat_gre.go) (GRE Client), [`sunat_batch.go`](https://github.com/villano14/sunat-go/blob/main/sunat_batch.go) (Batch and Status Facade), [`sunat.go`](https://github.com/villano14/sunat-go/blob/main/sunat.go) (Document Client), [`sign/sign.go`](https://github.com/villano14/sunat-go/blob/main/sign/sign.go) (XML Signer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_documents["Documents and Data"]
  node_invoice_model["Invoices and Notes<br/>[invoice.go]"]
  node_batch_model["Batch Documents<br/>[batch.go]"]
  node_purchase_model["Purchase Settlements<br/>[purchase.go]"]
  node_withholding_model["Retention and Perception<br/>[withholding.go]"]
  node_despatch_model["Despatch Guides<br/>[despatch.go]"]
  node_catalog["SUNAT Catalogs<br/>[catalog.go]"]
end

subgraph group_preparation["Calculation and UBL"]
  node_line_calc["Line Calculations<br/>[calc.go]"]
  node_totals_calc["Document Totals<br/>[totals.go]"]
  node_settlement_calc["Settlement Calculations<br/>[settlement.go]"]
  node_ubl_invoice["Invoice UBL<br/>[invoice.go]"]
  node_ubl_batch["Summary and Void UBL<br/>[batch.go]"]
  node_ubl_purchase["Settlement UBL<br/>[purchase.go]"]
  node_ubl_other["Other UBL Documents"]
end

subgraph group_soap["SOAP SUNAT"]
  node_soap_client["Document Client<br/>[sunat.go]"]
  node_batch_facade["Batch and Status Facade<br/>[sunat_batch.go]"]
  node_other_facades["Other SOAP Facades<br/>[sunat_note.go]"]
  node_soap_transport["SOAP Transport<br/>[transport.go]"]
  node_batch_transport["Batch and Consult Transport<br/>[batch.go]"]
  node_other_transport["Otros CPE Transport<br/>[otroscpe.go]"]
end

subgraph group_gre["GRE REST"]
  node_gre_facade["GRE Client<br/>[sunat_gre.go]"]
  node_gre_client["GRE REST and OAuth<br/>[gre.go]"]
  node_gre_token["Token Handling<br/>[token.go]"]
end

subgraph group_shared["Shared Services"]
  node_signer["XML Signer<br/>[sign.go]"]
  node_certificate["Certificate Loading<br/>[cert.go]"]
  node_cdr["CDR Parsing<br/>[cdr.go]"]
end

node_caller(("Library Caller"))
node_sunat(("SUNAT Services"))

node_caller -->|"builds or sends"| node_soap_client
node_soap_client -->|"renders invoices"| node_ubl_invoice
node_soap_client -->|"signs XML"| node_signer
node_soap_client -->|"submits documents"| node_soap_transport
node_caller -->|"builds or sends"| node_batch_facade
node_batch_facade -->|"renders batches"| node_ubl_batch
node_batch_facade -->|"signs XML"| node_signer
node_batch_facade -->|"sends and polls"| node_batch_transport
node_batch_facade -->|"parses CDR"| node_cdr
node_caller -->|"uses document flows"| node_other_facades
node_other_facades -->|"renders documents"| node_ubl_other
node_other_facades -->|"sends documents"| node_other_transport
node_soap_transport -->|"SOAP requests"| node_sunat
node_batch_transport -->|"status and CDR queries"| node_sunat
node_caller -->|"builds or sends guides"| node_gre_facade
node_gre_facade -->|"accepts guide data"| node_despatch_model
node_gre_facade -->|"renders despatch"| node_ubl_other
node_gre_facade -->|"signs XML"| node_signer
node_gre_facade -->|"sends and checks status"| node_gre_client
node_gre_facade -->|"parses returned CDR"| node_cdr
node_gre_client -->|"REST requests"| node_sunat
node_gre_client -->|"obtains OAuth token"| node_gre_token
node_caller -->|"optionally calculates lines"| node_line_calc
node_caller -->|"optionally aggregates"| node_totals_calc
node_caller -->|"optionally calculates settlement"| node_settlement_calc
node_line_calc -->|"uses codes"| node_catalog
node_line_calc -->|"returns line data"| node_invoice_model
node_totals_calc -->|"classifies taxes"| node_catalog
node_settlement_calc -->|"produces settlement"| node_purchase_model
node_invoice_model -->|"renders as UBL"| node_ubl_invoice
node_batch_model -->|"renders as UBL"| node_ubl_batch
node_purchase_model -->|"renders as UBL"| node_ubl_purchase
node_certificate -.->|"loads credentials"| node_signer

click node_invoice_model "https://github.com/villano14/sunat-go/blob/main/model/invoice.go"
click node_batch_model "https://github.com/villano14/sunat-go/blob/main/model/batch.go"
click node_purchase_model "https://github.com/villano14/sunat-go/blob/main/model/purchase.go"
click node_withholding_model "https://github.com/villano14/sunat-go/blob/main/model/withholding.go"
click node_despatch_model "https://github.com/villano14/sunat-go/blob/main/model/despatch.go"
click node_catalog "https://github.com/villano14/sunat-go/blob/main/catalog/catalog.go"
click node_line_calc "https://github.com/villano14/sunat-go/blob/main/calc/calc.go"
click node_totals_calc "https://github.com/villano14/sunat-go/blob/main/calc/totals.go"
click node_settlement_calc "https://github.com/villano14/sunat-go/blob/main/calc/settlement.go"
click node_ubl_invoice "https://github.com/villano14/sunat-go/blob/main/ubl/invoice.go"
click node_ubl_batch "https://github.com/villano14/sunat-go/blob/main/ubl/batch.go"
click node_ubl_purchase "https://github.com/villano14/sunat-go/blob/main/ubl/purchase.go"
click node_ubl_other "https://github.com/villano14/sunat-go/tree/main/ubl"
click node_soap_client "https://github.com/villano14/sunat-go/blob/main/sunat.go"
click node_batch_facade "https://github.com/villano14/sunat-go/blob/main/sunat_batch.go"
click node_other_facades "https://github.com/villano14/sunat-go/blob/main/sunat_note.go"
click node_signer "https://github.com/villano14/sunat-go/blob/main/sign/sign.go"
click node_certificate "https://github.com/villano14/sunat-go/blob/main/sign/cert.go"
click node_soap_transport "https://github.com/villano14/sunat-go/blob/main/transport/transport.go"
click node_batch_transport "https://github.com/villano14/sunat-go/blob/main/transport/batch.go"
click node_other_transport "https://github.com/villano14/sunat-go/blob/main/transport/otroscpe.go"
click node_cdr "https://github.com/villano14/sunat-go/blob/main/cdr/cdr.go"
click node_gre_facade "https://github.com/villano14/sunat-go/blob/main/sunat_gre.go"
click node_gre_client "https://github.com/villano14/sunat-go/blob/main/gre/gre.go"
click node_gre_token "https://github.com/villano14/sunat-go/blob/main/gre/token.go"

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_invoice_model,node_batch_model,node_purchase_model,node_withholding_model,node_despatch_model,node_catalog toneBlue
class node_line_calc,node_totals_calc,node_settlement_calc,node_ubl_invoice,node_ubl_batch,node_ubl_purchase,node_ubl_other toneAmber
class node_soap_client,node_batch_facade,node_other_facades,node_soap_transport,node_batch_transport,node_other_transport toneMint
class node_gre_facade,node_gre_client,node_gre_token toneRose
class node_signer,node_certificate,node_cdr,node_caller,node_sunat toneIndigo
```

## Components

### Documents and Data

- [Invoices and Notes](https://github.com/villano14/sunat-go/blob/main/model/invoice.go): `model/invoice.go`
- [Batch Documents](https://github.com/villano14/sunat-go/blob/main/model/batch.go): `model/batch.go`
- [Purchase Settlements](https://github.com/villano14/sunat-go/blob/main/model/purchase.go): `model/purchase.go`
- [Retention and Perception](https://github.com/villano14/sunat-go/blob/main/model/withholding.go): `model/withholding.go`
- [Despatch Guides](https://github.com/villano14/sunat-go/blob/main/model/despatch.go): `model/despatch.go`
- [SUNAT Catalogs](https://github.com/villano14/sunat-go/blob/main/catalog/catalog.go): `catalog/catalog.go`

### Calculation and UBL

- [Line Calculations](https://github.com/villano14/sunat-go/blob/main/calc/calc.go): `calc/calc.go`
- [Document Totals](https://github.com/villano14/sunat-go/blob/main/calc/totals.go): `calc/totals.go`
- [Settlement Calculations](https://github.com/villano14/sunat-go/blob/main/calc/settlement.go): `calc/settlement.go`
- [Invoice UBL](https://github.com/villano14/sunat-go/blob/main/ubl/invoice.go): `ubl/invoice.go`
- [Summary and Void UBL](https://github.com/villano14/sunat-go/blob/main/ubl/batch.go): `ubl/batch.go`
- [Settlement UBL](https://github.com/villano14/sunat-go/blob/main/ubl/purchase.go): `ubl/purchase.go`
- [Other UBL Documents](https://github.com/villano14/sunat-go/tree/main/ubl): `ubl`

### SOAP SUNAT

- [Document Client](https://github.com/villano14/sunat-go/blob/main/sunat.go): `sunat.go`
- [Batch and Status Facade](https://github.com/villano14/sunat-go/blob/main/sunat_batch.go): `sunat_batch.go`
- [Other SOAP Facades](https://github.com/villano14/sunat-go/blob/main/sunat_note.go): `sunat_note.go`
- [SOAP Transport](https://github.com/villano14/sunat-go/blob/main/transport/transport.go): `transport/transport.go`
- [Batch and Consult Transport](https://github.com/villano14/sunat-go/blob/main/transport/batch.go): `transport/batch.go`
- [Otros CPE Transport](https://github.com/villano14/sunat-go/blob/main/transport/otroscpe.go): `transport/otroscpe.go`

### GRE REST

- [GRE Client](https://github.com/villano14/sunat-go/blob/main/sunat_gre.go): `sunat_gre.go`
- [GRE REST and OAuth](https://github.com/villano14/sunat-go/blob/main/gre/gre.go): `gre/gre.go`
- [Token Handling](https://github.com/villano14/sunat-go/blob/main/gre/token.go): `gre/token.go`

### Shared Services

- [XML Signer](https://github.com/villano14/sunat-go/blob/main/sign/sign.go): `sign/sign.go`
- [Certificate Loading](https://github.com/villano14/sunat-go/blob/main/sign/cert.go): `sign/cert.go`
- [CDR Parsing](https://github.com/villano14/sunat-go/blob/main/cdr/cdr.go): `cdr/cdr.go`

### Other components

- **Library Caller**
- **SUNAT Services**

## Connections

- Library Caller → Document Client: builds or sends (evidence: `README.md`)
- Document Client → Invoice UBL: renders invoices (evidence: `README.md`)
- Document Client → XML Signer: signs XML (evidence: `sunat.go`)
- Document Client → SOAP Transport: submits documents (evidence: `README.md`)
- Library Caller → Batch and Status Facade: builds or sends (evidence: `README.md`)
- Batch and Status Facade → Summary and Void UBL: renders batches (evidence: `sunat_batch.go`)
- Batch and Status Facade → XML Signer: signs XML (evidence: `sunat_batch.go`)
- Batch and Status Facade → Batch and Consult Transport: sends and polls (evidence: `README.md`)
- Batch and Status Facade → CDR Parsing: parses CDR (evidence: `sunat_batch.go`)
- Library Caller → Other SOAP Facades: uses document flows (evidence: `README.md`)
- Other SOAP Facades → Other UBL Documents: renders documents (evidence: `README.md`)
- Other SOAP Facades → Otros CPE Transport: sends documents (evidence: `README.md`)
- SOAP Transport → SUNAT Services: SOAP requests (evidence: `README.md`)
- Batch and Consult Transport → SUNAT Services: status and CDR queries (evidence: `README.md`)
- Library Caller → GRE Client: builds or sends guides (evidence: `README.md`)
- GRE Client → Despatch Guides: accepts guide data (evidence: `sunat_gre.go`)
- GRE Client → Other UBL Documents: renders despatch (evidence: `sunat_gre.go`)
- GRE Client → XML Signer: signs XML (evidence: `sunat_gre.go`)
- GRE Client → GRE REST and OAuth: sends and checks status (evidence: `sunat_gre.go`)
- GRE Client → CDR Parsing: parses returned CDR (evidence: `sunat_gre.go`)
- GRE REST and OAuth → SUNAT Services: REST requests (evidence: `README.md`)
- GRE REST and OAuth → Token Handling: obtains OAuth token (evidence: `gre/gre.go`)
- Library Caller → Line Calculations: optionally calculates lines (evidence: `README.md`)
- Library Caller → Document Totals: optionally aggregates (evidence: `README.md`)
- Library Caller → Settlement Calculations: optionally calculates settlement (evidence: `README.md`)
- Line Calculations → SUNAT Catalogs: uses codes (evidence: `calc/calc.go`)
- Line Calculations → Invoices and Notes: returns line data (evidence: `calc/calc.go`)
- Document Totals → SUNAT Catalogs: classifies taxes (evidence: `calc/totals.go`)
- Settlement Calculations → Purchase Settlements: produces settlement (evidence: `calc/settlement.go`)
- Invoices and Notes → Invoice UBL: renders as UBL (evidence: `ubl/invoice.go`)
- Batch Documents → Summary and Void UBL: renders as UBL (evidence: `ubl/batch.go`)
- Purchase Settlements → Settlement UBL: renders as UBL (evidence: `ubl/purchase.go`)
- Certificate Loading → XML Signer: loads credentials
