How invopop/gobl works
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