# lapyme/facturas architecture

> Architecture diagram of the GitHub repository lapyme/facturas, 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/lapyme/facturas
- Repository: https://github.com/lapyme/facturas

## Overview

facturas is a TypeScript SDK and CLI for ARCA electronic invoicing, credit/debit notes, and taxpayer-registry queries, with a companion PDF package. The main workflow configures a client, authenticates through WSAA, derives and reserves a voucher, calls the selected ARCA service, then returns authorization evidence and a QR URL. The graph also preserves CLI diagnostics/setup and PDF voucher rendering. Core client wiring and several service calls are evidenced by excerpts and the source index; some documented capabilities are shown without inferred internal call chains.

Main entry points: [`packages/arca/src/client.ts`](https://github.com/lapyme/facturas/blob/main/packages/arca/src/client.ts) (Client factory), [`packages/arca/src/services/vouchers.ts`](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/vouchers.ts) (Voucher orchestration), [`packages/arca/src/soap/index.ts`](https://github.com/lapyme/facturas/blob/main/packages/arca/src/soap/index.ts) (SOAP transport), [`packages/arca/src/store/types.ts`](https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/types.ts) (Reservation store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_public["Public API<br/>[index.ts]"]
  node_client["Client factory<br/>[client.ts]"]
  node_cli["CLI commands<br/>[main.ts]"]
  node_config["Config discovery<br/>[config.ts]"]
end

subgraph group_issuance["Issuance domain"]
  node_voucher["Voucher orchestration<br/>[vouchers.ts]"]
  node_fields["Fiscal fields<br/>[issuance-fields.ts]"]
  node_derive["WSFE derivation<br/>[wsfe-derive.ts]"]
  node_fiscal["Fiscal evidence<br/>[fiscal-evidence.ts]"]
end

subgraph group_transport["ARCA transport"]
  node_wsfe["Domestic invoices<br/>[wsfe.ts]"]
  node_wsfex["Export invoices<br/>[wsfex.ts]"]
  node_wsmtxca["Detailed invoices<br/>[wsmtxca.ts]"]
  node_padron["Tax registry<br/>[padron.ts]"]
  node_soap["SOAP transport<br/>[index.ts]"]
  node_wsaa["WSAA login<br/>[index.ts]"]
end

subgraph group_state["Sessions and state"]
  node_store[("Reservation store<br/>[types.ts]")]
  node_postgres[("Postgres adapter<br/>[postgres.ts]")]
  node_redis[("Redis adapter<br/>[redis.ts]")]
  node_file[("File adapter<br/>[file.ts]")]
  node_memory[("Memory adapter<br/>[memory.ts]")]
end

subgraph group_documents["Documents"]
  node_qr["QR generation<br/>[qr.ts]"]
  node_document["Voucher document"]
  node_pdf["PDF renderer<br/>[voucher.tsx]"]
end

node_developer(("SDK caller"))
node_cliuser(("CLI user"))
node_arca{{"ARCA services"}}

node_developer -->|"calls"| node_public
node_public -->|"exports"| node_client
node_client -->|"normalizes"| node_config
node_client -->|"creates"| node_wsaa
node_client -->|"creates"| node_soap
node_client -->|"creates"| node_wsfe
node_client -->|"creates"| node_wsfex
node_client -->|"creates"| node_wsmtxca
node_client -->|"creates"| node_padron
node_client -->|"creates"| node_voucher
node_developer -->|"issues"| node_voucher
node_voucher -->|"derives fields"| node_fields
node_voucher -->|"derives request"| node_derive
node_voucher -->|"submits"| node_wsfe
node_voucher -->|"submits"| node_wsfex
node_voucher -->|"submits"| node_wsmtxca
node_voucher -->|"reserves attempts"| node_store
node_voucher -->|"returns outcomes"| node_fiscal
node_wsfe -->|"executes SOAP"| node_soap
node_wsfex -->|"executes SOAP"| node_soap
node_wsaa -->|"logs in"| node_arca
node_soap -->|"sends SOAP"| node_arca
node_wsfe -->|"authenticates"| node_wsaa
node_wsfex -->|"authenticates"| node_wsaa
node_padron -.->|"uses transport"| node_soap
node_postgres -.->|"implements"| node_store
node_redis -.->|"implements"| node_store
node_file -->|"implements"| node_store
node_memory -.->|"implements"| node_store
node_cliuser -->|"runs"| node_cli
node_cli -->|"creates client"| node_client
node_fiscal -.->|"authorization QR"| node_qr
node_developer -->|"builds voucher"| node_document
node_document -->|"renders with"| node_pdf

click node_public "https://github.com/lapyme/facturas/blob/main/packages/arca/src/index.ts"
click node_client "https://github.com/lapyme/facturas/blob/main/packages/arca/src/client.ts"
click node_cli "https://github.com/lapyme/facturas/blob/main/packages/arca/src/cli/main.ts"
click node_config "https://github.com/lapyme/facturas/blob/main/packages/arca/src/config.ts"
click node_voucher "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/vouchers.ts"
click node_fields "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/issuance-fields.ts"
click node_derive "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsfe-derive.ts"
click node_fiscal "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/fiscal-evidence.ts"
click node_wsfe "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsfe.ts"
click node_wsfex "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsfex.ts"
click node_wsmtxca "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsmtxca.ts"
click node_padron "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/padron.ts"
click node_soap "https://github.com/lapyme/facturas/blob/main/packages/arca/src/soap/index.ts"
click node_wsaa "https://github.com/lapyme/facturas/blob/main/packages/arca/src/wsaa/index.ts"
click node_store "https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/types.ts"
click node_postgres "https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/postgres.ts"
click node_redis "https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/redis.ts"
click node_file "https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/file.ts"
click node_memory "https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/memory.ts"
click node_qr "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/qr.ts"
click node_document "https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/voucher-document.ts"
click node_pdf "https://github.com/lapyme/facturas/blob/main/packages/pdf/src/voucher.tsx"

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_public,node_client,node_cli,node_config,node_cliuser toneBlue
class node_voucher,node_fields,node_derive,node_fiscal toneAmber
class node_wsfe,node_wsfex,node_wsmtxca,node_padron,node_soap,node_wsaa toneMint
class node_store,node_postgres,node_redis,node_file,node_memory toneRose
class node_qr,node_document,node_pdf,node_developer,node_arca toneIndigo
```

## Components

### Entry points

- [Public API](https://github.com/lapyme/facturas/blob/main/packages/arca/src/index.ts): `packages/arca/src/index.ts`
- [Client factory](https://github.com/lapyme/facturas/blob/main/packages/arca/src/client.ts): `packages/arca/src/client.ts`
- [CLI commands](https://github.com/lapyme/facturas/blob/main/packages/arca/src/cli/main.ts): `packages/arca/src/cli/main.ts`
- [Config discovery](https://github.com/lapyme/facturas/blob/main/packages/arca/src/config.ts): `packages/arca/src/config.ts`

### Issuance domain

- [Voucher orchestration](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/vouchers.ts): `packages/arca/src/services/vouchers.ts`
- [Fiscal fields](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/issuance-fields.ts): `packages/arca/src/services/issuance-fields.ts`
- [WSFE derivation](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsfe-derive.ts): `packages/arca/src/services/wsfe-derive.ts`
- [Fiscal evidence](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/fiscal-evidence.ts): `packages/arca/src/services/fiscal-evidence.ts`

### ARCA transport

- [Domestic invoices](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsfe.ts): `packages/arca/src/services/wsfe.ts`
- [Export invoices](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsfex.ts): `packages/arca/src/services/wsfex.ts`
- [Detailed invoices](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/wsmtxca.ts): `packages/arca/src/services/wsmtxca.ts`
- [Tax registry](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/padron.ts): `packages/arca/src/services/padron.ts`
- [SOAP transport](https://github.com/lapyme/facturas/blob/main/packages/arca/src/soap/index.ts): `packages/arca/src/soap/index.ts`
- [WSAA login](https://github.com/lapyme/facturas/blob/main/packages/arca/src/wsaa/index.ts): `packages/arca/src/wsaa/index.ts`

### Sessions and state

- [Reservation store](https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/types.ts): `packages/arca/src/store/types.ts`
- [Postgres adapter](https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/postgres.ts): `packages/arca/src/store/postgres.ts`
- [Redis adapter](https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/redis.ts): `packages/arca/src/store/redis.ts`
- [File adapter](https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/file.ts): `packages/arca/src/store/file.ts`
- [Memory adapter](https://github.com/lapyme/facturas/blob/main/packages/arca/src/store/memory.ts): `packages/arca/src/store/memory.ts`

### Documents

- [QR generation](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/qr.ts): `packages/arca/src/services/qr.ts`
- [Voucher document](https://github.com/lapyme/facturas/blob/main/packages/arca/src/services/voucher-document.ts): `packages/arca/src/services/voucher-document.ts`
- [PDF renderer](https://github.com/lapyme/facturas/blob/main/packages/pdf/src/voucher.tsx): `packages/pdf/src/voucher.tsx`

### Other components

- **SDK caller**
- **CLI user**
- **ARCA services**

## Connections

- SDK caller → Public API: calls (evidence: `README.md`)
- Public API → Client factory: exports (evidence: `packages/arca/src/index.ts`)
- Client factory → Config discovery: normalizes (evidence: `packages/arca/src/client.ts`)
- Client factory → WSAA login: creates (evidence: `packages/arca/src/client.ts`)
- Client factory → SOAP transport: creates (evidence: `packages/arca/src/client.ts`)
- Client factory → Domestic invoices: creates (evidence: `packages/arca/src/client.ts`)
- Client factory → Export invoices: creates (evidence: `packages/arca/src/client.ts`)
- Client factory → Detailed invoices: creates (evidence: `packages/arca/src/client.ts`)
- Client factory → Tax registry: creates (evidence: `packages/arca/src/client.ts`)
- Client factory → Voucher orchestration: creates (evidence: `packages/arca/src/client.ts`)
- SDK caller → Voucher orchestration: issues (evidence: `README.md`)
- Voucher orchestration → Fiscal fields: derives fields (evidence: `packages/arca/src/services/vouchers.ts`)
- Voucher orchestration → WSFE derivation: derives request (evidence: `packages/arca/src/services/vouchers.ts`)
- Voucher orchestration → Domestic invoices: submits (evidence: `packages/arca/src/services/vouchers.ts`)
- Voucher orchestration → Export invoices: submits (evidence: `packages/arca/src/services/vouchers.ts`)
- Voucher orchestration → Detailed invoices: submits (evidence: `packages/arca/src/services/vouchers.ts`)
- Voucher orchestration → Reservation store: reserves attempts (evidence: `packages/arca/src/services/vouchers.ts`)
- Voucher orchestration → Fiscal evidence: returns outcomes (evidence: `packages/arca/src/services/vouchers.ts`)
- Domestic invoices → SOAP transport: executes SOAP (evidence: `packages/arca/src/services/wsfe.ts`)
- Export invoices → SOAP transport: executes SOAP (evidence: `packages/arca/src/services/wsfex.ts`)
- WSAA login → ARCA services: logs in (evidence: `packages/arca/src/wsaa/index.ts`)
- SOAP transport → ARCA services: sends SOAP (evidence: `packages/arca/src/soap/index.ts`)
- Domestic invoices → WSAA login: authenticates (evidence: `packages/arca/src/services/wsfe.ts`)
- Export invoices → WSAA login: authenticates (evidence: `packages/arca/src/services/wsfex.ts`)
- Tax registry → SOAP transport: uses transport
- Postgres adapter → Reservation store: implements
- Redis adapter → Reservation store: implements (evidence: `packages/arca/src/store/redis.ts`)
- File adapter → Reservation store: implements (evidence: `packages/arca/src/store/file.ts`)
- Memory adapter → Reservation store: implements
- CLI user → CLI commands: runs (evidence: `README.md`)
- CLI commands → Client factory: creates client (evidence: `packages/arca/src/cli/main.ts`)
- Fiscal evidence → QR generation: authorization QR
- SDK caller → Voucher document: builds voucher (evidence: `README.md`)
- Voucher document → PDF renderer: renders with (evidence: `README.md`)