# dojocodinglabs/hacienda-cr architecture

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

## Overview

Hacienda CR is a TypeScript toolkit for Costa Rican electronic invoicing, exposed through an SDK, terminal CLI, and MCP server. The main workflow prepares and validates document data, calculates amounts, builds XML, signs and submits it to Hacienda, then checks its status. The README documents these capabilities across the packages; sampled code confirms key client, authentication, HTTP, XML-builder, and MCP registration relationships. Some CLI and SDK subsystems are represented by their exact enclosing directories because their implementation files were not sampled.

Main entry points: [`packages/sdk/src/client.ts`](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/client.ts) (SDK client), [`packages/sdk/src/documents`](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/documents) (Document builders), [`packages/cli/src/commands`](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/cli/src/commands) (CLI commands), [`packages/sdk/src/api/orchestrator.ts`](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/orchestrator.ts) (Submission workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_sdk_entry["SDK client<br/>[client.ts]"]
  node_cli_entry["CLI commands"]
  node_cli_draft["Draft creation<br/>[draft.ts]"]
  node_cli_submit["CLI submission<br/>[submit.ts]"]
  node_mcp_server["MCP server<br/>[server.ts]"]
  node_mcp_tools["MCP tools"]
  node_mcp_resources["MCP resources"]
end

subgraph group_sdk["SDK workflow"]
  node_auth["OAuth authentication<br/>[token-manager.ts]"]
  node_clave["Clave generation"]
  node_documents["Document builders"]
  node_tax["Tax calculation"]
  node_xml["XML validation"]
  node_signing["Digital signing"]
  node_api_orchestrator["Submission workflow<br/>[orchestrator.ts]"]
  node_http["Hacienda API client<br/>[http-client.ts]"]
end

subgraph group_shared["Shared domain"]
  node_shared_schemas["Document schemas"]
  node_shared_constants["Reference catalogs"]
  node_money["Exact monetary math<br/>[decimal-text.ts]"]
end

subgraph group_operations["Operations"]
  node_config[("Configuration and sequences")]
  node_delivery["Delivery tracking"]
  node_calendar["Business calendar"]
  node_status["Status and lookups<br/>[comprobantes.ts]"]
  node_cancel["Cancellation controls<br/>[cancellation.ts]"]
end

node_user(("Application or operator"))
node_hacienda(("Hacienda services"))

node_user -->|"uses SDK"| node_sdk_entry
node_user -->|"runs commands"| node_cli_entry
node_user -->|"connects assistant"| node_mcp_server
node_cli_entry -->|"routes commands"| node_cli_draft
node_cli_entry -->|"routes commands"| node_cli_submit
node_mcp_server -->|"registers tools"| node_mcp_tools
node_mcp_server -->|"registers resources"| node_mcp_resources
node_sdk_entry -->|"initializes"| node_auth
node_sdk_entry -->|"builds and parses"| node_clave
node_cli_draft -->|"prepares drafts"| node_documents
node_mcp_tools -->|"generates XML"| node_documents
node_documents -->|"validates input"| node_shared_schemas
node_documents -->|"calculates amounts"| node_tax
node_tax -.->|"uses exact arithmetic"| node_money
node_documents -->|"builds XML"| node_xml
node_shared_schemas -.->|"uses catalogs"| node_shared_constants
node_cli_submit -->|"signs documents"| node_signing
node_sdk_entry -->|"signs documents"| node_signing
node_sdk_entry -->|"submits documents"| node_api_orchestrator
node_api_orchestrator -->|"calls API client"| node_http
node_http -->|"gets access token"| node_auth
node_http -->|"sends requests"| node_hacienda
node_api_orchestrator -->|"tracks delivery"| node_delivery
node_sdk_entry -->|"checks status"| node_status
node_cli_entry -->|"queries status"| node_status
node_status -->|"queries records"| node_hacienda
node_sdk_entry -.->|"manages configuration"| node_config
node_sdk_entry -.->|"uses business days"| node_calendar
node_api_orchestrator -->|"supports cancellation"| node_cancel

click node_sdk_entry "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/client.ts"
click node_cli_entry "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/cli/src/commands"
click node_cli_draft "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/cli/src/commands/draft.ts"
click node_cli_submit "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/cli/src/commands/submit.ts"
click node_mcp_server "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/mcp/src/server.ts"
click node_mcp_tools "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/mcp/src/tools"
click node_mcp_resources "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/mcp/src/resources"
click node_auth "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/auth/token-manager.ts"
click node_clave "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/clave"
click node_documents "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/documents"
click node_tax "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/tax"
click node_xml "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/xml"
click node_signing "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/signing"
click node_api_orchestrator "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/orchestrator.ts"
click node_http "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/http-client.ts"
click node_shared_schemas "https://github.com/dojocodinglabs/hacienda-cr/tree/main/shared/src/schemas"
click node_shared_constants "https://github.com/dojocodinglabs/hacienda-cr/tree/main/shared/src/constants"
click node_money "https://github.com/dojocodinglabs/hacienda-cr/blob/main/shared/src/monetary/decimal-text.ts"
click node_config "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/config"
click node_delivery "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/delivery"
click node_calendar "https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/calendar"
click node_status "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/comprobantes.ts"
click node_cancel "https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/cancellation.ts"

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_sdk_entry,node_cli_entry,node_cli_draft,node_cli_submit,node_mcp_server,node_mcp_tools,node_mcp_resources toneBlue
class node_auth,node_clave,node_documents,node_tax,node_xml,node_signing,node_api_orchestrator,node_http toneAmber
class node_shared_schemas,node_shared_constants,node_money toneMint
class node_config,node_delivery,node_calendar,node_status,node_cancel toneRose
class node_user,node_hacienda toneIndigo
```

## Components

### User interfaces

- [SDK client](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [CLI commands](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/cli/src/commands): `packages/cli/src/commands`
- [Draft creation](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/cli/src/commands/draft.ts): `packages/cli/src/commands/draft.ts`
- [CLI submission](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/cli/src/commands/submit.ts): `packages/cli/src/commands/submit.ts`
- [MCP server](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/mcp/src/server.ts): `packages/mcp/src/server.ts`
- [MCP tools](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/mcp/src/tools): `packages/mcp/src/tools`
- [MCP resources](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/mcp/src/resources): `packages/mcp/src/resources`

### SDK workflow

- [OAuth authentication](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/auth/token-manager.ts): `packages/sdk/src/auth/token-manager.ts`
- [Clave generation](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/clave): `packages/sdk/src/clave`
- [Document builders](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/documents): `packages/sdk/src/documents`
- [Tax calculation](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/tax): `packages/sdk/src/tax`
- [XML validation](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/xml): `packages/sdk/src/xml`
- [Digital signing](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/signing): `packages/sdk/src/signing`
- [Submission workflow](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/orchestrator.ts): `packages/sdk/src/api/orchestrator.ts`
- [Hacienda API client](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/http-client.ts): `packages/sdk/src/api/http-client.ts`

### Shared domain

- [Document schemas](https://github.com/dojocodinglabs/hacienda-cr/tree/main/shared/src/schemas): `shared/src/schemas`
- [Reference catalogs](https://github.com/dojocodinglabs/hacienda-cr/tree/main/shared/src/constants): `shared/src/constants`
- [Exact monetary math](https://github.com/dojocodinglabs/hacienda-cr/blob/main/shared/src/monetary/decimal-text.ts): `shared/src/monetary/decimal-text.ts`

### Operations

- [Configuration and sequences](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/config): `packages/sdk/src/config`
- [Delivery tracking](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/delivery): `packages/sdk/src/delivery`
- [Business calendar](https://github.com/dojocodinglabs/hacienda-cr/tree/main/packages/sdk/src/calendar): `packages/sdk/src/calendar`
- [Status and lookups](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/comprobantes.ts): `packages/sdk/src/api/comprobantes.ts`
- [Cancellation controls](https://github.com/dojocodinglabs/hacienda-cr/blob/main/packages/sdk/src/api/cancellation.ts): `packages/sdk/src/api/cancellation.ts`

### Other components

- **Application or operator**
- **Hacienda services**

## Connections

- Application or operator → SDK client: uses SDK
- Application or operator → CLI commands: runs commands
- Application or operator → MCP server: connects assistant
- CLI commands → Draft creation: routes commands (evidence: `packages/cli/src/commands/index.ts`)
- CLI commands → CLI submission: routes commands (evidence: `packages/cli/src/commands/index.ts`)
- MCP server → MCP tools: registers tools (evidence: `packages/mcp/src/server.ts`)
- MCP server → MCP resources: registers resources (evidence: `packages/mcp/src/server.ts`)
- SDK client → OAuth authentication: initializes (evidence: `packages/sdk/src/client.ts`)
- SDK client → Clave generation: builds and parses (evidence: `packages/sdk/src/client.ts`)
- Draft creation → Document builders: prepares drafts
- MCP tools → Document builders: generates XML
- Document builders → Document schemas: validates input (evidence: `packages/sdk/src/documents/exact-fec-foreign-service-builder.ts`)
- Document builders → Tax calculation: calculates amounts (evidence: `packages/sdk/src/documents/exact-fec-foreign-service-builder.ts`)
- Tax calculation → Exact monetary math: uses exact arithmetic
- Document builders → XML validation: builds XML (evidence: `packages/sdk/src/documents/exact-fec-foreign-service-builder.ts`)
- Document schemas → Reference catalogs: uses catalogs
- CLI submission → Digital signing: signs documents
- SDK client → Digital signing: signs documents
- SDK client → Submission workflow: submits documents
- Submission workflow → Hacienda API client: calls API client (evidence: `packages/sdk/src/api/orchestrator.ts`)
- Hacienda API client → OAuth authentication: gets access token (evidence: `packages/sdk/src/api/http-client.ts`)
- Hacienda API client → Hacienda services: sends requests
- Submission workflow → Delivery tracking: tracks delivery (evidence: `packages/sdk/src/api/orchestrator.ts`)
- SDK client → Status and lookups: checks status
- CLI commands → Status and lookups: queries status
- Status and lookups → Hacienda services: queries records
- SDK client → Configuration and sequences: manages configuration
- SDK client → Business calendar: uses business days
- Submission workflow → Cancellation controls: supports cancellation (evidence: `packages/sdk/src/api/orchestrator.ts`)
