# invopop/gobl architecture

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

- Interactive diagram: https://gitdiagram.com/invopop/gobl
- Repository: https://github.com/invopop/gobl

## Overview

##### Project type and purpose
- GOBL is primarily a Go-based domain library (core) for building, calculating, validating and signing electronic business documents (invoices, credit notes, orders, etc.).
- It also includes:
- A CLI application (`cmd/gobl`) for command-line manipulation of GOBL documents.
- A WebAssembly-based front-end (`wasm/`) that exposes the same library in the browser.
- A large set of data files (JSON schemas, country regimes, catalogues, tax rates).

##### File structure
- Top-level packages:
- `bill`, `tax`, `cbc`, `cal`, `currency`, `org`, `pay`, `l10n`, `i18n`, `note`, `uuid`, `dsig`, `c14n`, etc. — core domain modules.
- `addons/` and `regimes/` — pluggable country-specific extensions (invoices, tax combos, identities).
- `data/` — JSON schema and data sources loaded at runtime or code-generated.
- `cmd/gobl/` and `internal/cli/` — CLI command definitions and helpers.
- `wasm/` — browser UI, including Go→WASM bindings and a small JS/HTML layer.
- `examples/` — sample YAML/JSON invoice documents demonstrating usage.
- CI and build scripts: `.github/workflows/`, `goreleaser.yml`, `mage.go`.

##### README for additional insights
- The README describes:
- Core library features: schema definitions, tax algorithms, JWS signing, envelope concept.
- CLI commands: build, correct, sign, validate.
- WASM “Builder” as companion project.
- Dependency on JSON Schema, JWK, standard Go modules.

a. Main components
- Core Library (domain packages: bill, tax, c14n, dsig, currency, cal, org, pay, etc.)
- Data Layer (JSON schema files, regime definitions, catalogues under `data/`)
- -on Registry (pluggable country modules in `addons/` + `regimes/`)
- CLI Application (`cmd/gobl` orchestrator + `internal/cli`)
- WASM Front-end (`wasm/` Go→WASM module + JS/HTML UI)
- Build & Release Tools (Mage, GoReleaser, GitHub Actions)
- Users & Tools (YAML/JSON inputs, JWK keys, external files)

b. Relationships & interactions
1. User supplies a YAML/JSON invoice → CLI or WASM UI
2. CLI/WASM parser invokes Core Library:
– Document Insertion into Envelope
– Calculation (`bill.calculator`, `tax.totals`)
– Validation (JSON Schema + local rules)
– Signing (`dsig` / JSON Web Signature using JWK)
3. Core Library loads:
– Country-specific logic via Add-on Registry (`addons/`, `regimes/`)
– Static data from `data/` JSON files or generated Go code
4. CLI/WASM outputs JSON envelope/document or errors.
5. Build pipeline uses Mage/GoReleaser and CI to produce binaries (`gobl`, WASM .wasm), packages, releases.

c. Architectural patterns & design principles
- Layered architecture: Core domain → Add-ons/Regimes → Applications (CLI, WASM)
- Plugin/Registry pattern: runtime discovery of country modules via code-generated registries
- Data-driven design: JSON schemas drive code generation (`go generate .`), validation, and documentation
- Separation of concerns:
- Domain logic (calculations, schemas, signatures)
- I/O & orchestration (CLI, WASM)
- Data (static JSON)
- Merged envelope pattern: immutability & cryptographic integrity

d. Technologies, frameworks, libraries
- Go modules & standard library
- JSON Schema for data validation (`schema/`)
- JSON Web Signatures (`dsig/`, `c14n/`)
- WebAssembly via `tinygo` or `go wasm` (in `wasm/`)
- Mage build scripts & GoReleaser for CI/CD
- GitHub Actions for lint, test, release

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        CLI_UI["CLI Application"]:::app
        Browser_UI["Browser UI (HTML/JS)"]:::app
        WASM_Module["gobl.wasm"]:::app
    end

    %% Application Layer
    subgraph "Application Layer"
        CMD["cmd/gobl"]:::app
        CLI_Helper["internal/cli"]:::app
        WASM_Serve["wasm/serve"]:::app
    end

    %% Core Domain Library
    subgraph "Core Domain Library"
        bill["bill"]:::core
        tax["tax"]:::core
        c14n["c14n"]:::core
        dsig["dsig"]:::core
        currency["currency"]:::core
        cal["cal"]:::core
        org["org"]:::core
        pay["pay"]:::core
        l10n["l10n"]:::core
        i18n["i18n"]:::core
        note["note"]:::core
        num["num"]:::core
        uuid["uuid"]:::core
        cbc["cbc"]:::core
        cataloguesLib["catalogues"]:::core
        schemaLib["schema"]:::core
    end

    %% Add-on Registry
    subgraph "Add-on Registry"
        addons["addons"]:::core
        regimes["regimes"]:::core
    end

    %% Data & Schema
    subgraph "Data & Schema"
        data_addons["data/addons"]:::data
        data_catalogues["data/catalogues"]:::data
        data_currency["data/currency"]:::data
        data_regimes["data/regimes"]:::data
        data_schemas["data/schemas"]:::data
    end

    %% Build & CI Pipeline
    subgraph "Build & CI"
        Mage["mage.go"]:::build
        GoReleaser[".goreleaser.yml"]:::build
        GitHubActions[".github/workflows"]:::build
    end

    %% Flows
    CLI_UI --> CMD
    CMD --> CLI_Helper
    CLI_Helper --> bill
    CLI_Helper --> tax
    CLI_Helper --> dsig
    CLI_Helper --> c14n
    CLI_Helper --> schemaLib

    Browser_UI --> WASM_Serve
    WASM_Serve --> WASM_Module
    WASM_Module --> bill
    WASM_Module --> tax
    WASM_Module --> dsig
    WASM_Module --> c14n
    WASM_Module --> schemaLib

    %% Core dependencies
    bill -->|uses| data_catalogues
    tax -->|uses| data_regimes
    dsig -->|uses| data_schemas
    c14n -->|uses| data_schemas
    schemaLib -->|validates| data_schemas

    %% Add-ons and registry
    bill --> addons
    tax --> regimes
    addons --> data_addons
    regimes --> data_regimes

    %% Build pipeline
    Mage --> GoReleaser
    GoReleaser --> GitHubActions

    %% Styles
    classDef app fill:#D0E8FF,stroke:#009,stroke-width:2px
    classDef core fill:#E0FFE0,stroke:#080,stroke-width:2px
    classDef data fill:#FFE0B2,stroke:#E66,stroke-width:2px
    classDef build fill:#E0E0E0,stroke:#666,stroke-width:2px

    %% Click Events
    click bill "https://github.com/invopop/gobl/tree/main/bill/"
    click tax "https://github.com/invopop/gobl/tree/main/tax/"
    click c14n "https://github.com/invopop/gobl/tree/main/c14n/"
    click dsig "https://github.com/invopop/gobl/tree/main/dsig/"
    click currency "https://github.com/invopop/gobl/tree/main/currency/"
    click cal "https://github.com/invopop/gobl/tree/main/cal/"
    click org "https://github.com/invopop/gobl/tree/main/org/"
    click pay "https://github.com/invopop/gobl/tree/main/pay/"
    click l10n "https://github.com/invopop/gobl/tree/main/l10n/"
    click i18n "https://github.com/invopop/gobl/tree/main/i18n/"
    click note "https://github.com/invopop/gobl/tree/main/note/"
    click num "https://github.com/invopop/gobl/tree/main/num/"
    click uuid "https://github.com/invopop/gobl/tree/main/uuid/"
    click cbc "https://github.com/invopop/gobl/tree/main/cbc/"
    click cataloguesLib "https://github.com/invopop/gobl/tree/main/catalogues/"
    click schemaLib "https://github.com/invopop/gobl/tree/main/schema/"

    click data_addons "https://github.com/invopop/gobl/tree/main/data/addons/"
    click data_catalogues "https://github.com/invopop/gobl/tree/main/data/catalogues/"
    click data_currency "https://github.com/invopop/gobl/tree/main/data/currency/"
    click data_regimes "https://github.com/invopop/gobl/tree/main/data/regimes/"
    click data_schemas "https://github.com/invopop/gobl/tree/main/data/schemas/"

    click addons "https://github.com/invopop/gobl/tree/main/addons/"
    click regimes "https://github.com/invopop/gobl/tree/main/regimes/"

    click CMD "https://github.com/invopop/gobl/tree/main/cmd/gobl/"
    click CLI_Helper "https://github.com/invopop/gobl/tree/main/internal/cli/"

    click WASM_Serve "https://github.com/invopop/gobl/tree/main/wasm/serve/"
    click Mage "https://github.com/invopop/gobl/blob/main/mage.go"
    click GoReleaser "https://github.com/invopop/gobl/blob/main/.goreleaser.yml"
    click GitHubActions "https://github.com/invopop/gobl/tree/main/.github/workflows/"
```
