Project Structure

Relevant source files

• README.md
• cii.go
• cii_test.go
• cmd/gobl.cii/convert.go
• examples_test.go
• go.mod
• go.sum
• party_parse.go
• utils.go

This page describes the physical layout of the gobl.cii repository: how the Go source files are organized, what each top-level file is responsible for, how the CLI sub-package fits in, and how the test data tree is structured.

For details on the public API functions themselves, see Core Conversion API. For the CLI command options, see CLI Usage. For the testing approach and golden-file mechanics, see Testing Framework.

---

Module Identity

The repository root is the Go module github.com/invopop/gobl.cii (go.mod1). The root directory is also the single importable cii package; there are no internal sub-packages. All source, CLI, and test data live under this one root.

---

Top-Level Directory Layout

gobl.cii/
├── cii.go               # Package doc, public API, Context types, namespaces
├── invoice.go           # Invoice struct, ConvertInvoice, newInvoice
├── agreement.go         # Agreement struct, addAgreement
├── settlement.go        # Settlement struct, newSettlement
├── party.go             # Party struct, newParty, goblNewParty
├── line.go              # Line struct, addLines, goblAddLines
├── tax.go               # Tax struct, tax-rate mapping
├── delivery.go          # Delivery struct, newDelivery
├── header.go            # Header struct, addHeader
├── cdar.go              # CDAR struct, UnmarshalCDAR, NewCDAR
├── parse.go             # parseInvoice, goblInvoice, goblNewPaymentDetails
├── cii_test.go          # Unit tests for Convert / context handling
├── examples_test.go     # Golden-file integration tests (convert + parse)
├── go.mod
├── go.sum
├── .golangci.yaml       # golangci-lint configuration
├── cmd/
│   └── gobl.cii/
│       ├── main.go      # cobra root command, entrypoint
│       └── convert.go   # "convert" sub-command implementation
└── test/
    └── data/
        ├── convert/     # GOBL JSON → CII XML test inputs + expected outputs
        └── parse/       # CII XML → GOBL JSON test inputs + expected outputs

Sources: cii.go1-19 invoice.go1-13 examples_test.go269-288 cmd/gobl.cii/convert.go1-11

---

Root cii Package

All exported types, functions, and constants live directly in the cii package. No internal sub-packages are used.

File responsibilities:

File	Key exports / purpose
cii.go	Parse, Convert, Unmarshal, WithContext, Context struct, all ContextXxx vars, namespace constants
invoice.go	Invoice struct, Transaction, Tax, Date, Note; ConvertInvoice, UnmarshalInvoice, newInvoice
agreement.go	Agreement struct; addAgreement method
settlement.go	Settlement, PaymentMeans, Terms, Summary structs; newSettlement, goblNewPaymentDetails
party.go	Party and address/identity sub-types; newParty, goblNewParty, goblNewAddress
line.go	Line, LineDoc, Product, LineAgreement structs; addLines, goblAddLines
tax.go	Tax category and rate mapping utilities
delivery.go	Delivery struct; newDelivery
header.go	Header (ExchangedDocument) struct; addHeader
cdar.go	CDAR, CDARAcknowledgement, CDARReferencedDocument; UnmarshalCDAR, NewCDAR
parse.go	parseInvoice, goblInvoice, goblNewOrdering

Sources: cii.go1-239 invoice.go1-141

---

Diagram: Source Files and Their Primary Exports

Root package file → exported symbol map

Sources: cii.go131-239 invoice.go14-68

---

cmd/gobl.cii Package

The CLI lives in cmd/gobl.cii/ as a separate main package. It imports the root cii package as a library.

File	Purpose
cmd/gobl.cii/main.go	Creates the cobra root command and calls Execute()
cmd/gobl.cii/convert.go	Implements the convert sub-command: reads input, detects JSON vs XML, dispatches to cii.ConvertInvoice or cii.Parse, writes output

The --context flag in convert.go maps string names to cii.Context values:

Flag value	cii.Context used
en16931 (default)	ContextEN16931V2017
facturx	ContextFacturXV1
zugferd	ContextZUGFeRDV2
xrechnung	ContextXRechnungV3
peppol	ContextPeppolV3
choruspro	ContextChorusProV1

Sources: cmd/gobl.cii/convert.go13-55

---

Diagram: CLI to Library Call Path

How cmd/gobl.cii delegates to the root package

Sources: cmd/gobl.cii/convert.go34-115 cii.go131-155 cii.go178-206 invoice.go58-68

---

Test Data Directory

The test/data/ tree is the fixture store for golden-file integration tests. It is split into two top-level sub-trees by conversion direction.

test/
└── data/
    ├── convert/                  # GOBL JSON → CII XML
    │   ├── en16931/
    │   │   ├── invoice-complete.json
    │   │   ├── invoice-minimal.json
    │   │   └── out/
    │   │       ├── invoice-complete.xml
    │   │       └── invoice-minimal.xml
    │   ├── peppol/
    │   │   └── out/
    │   ├── facturx/
    │   │   └── out/
    │   ├── xrechnung/
    │   │   └── out/
    │   ├── choruspro/
    │   │   └── out/
    │   ├── zugferd/
    │   │   └── out/
    │   ├── peppol-france-facturx/
    │   │   └── out/
    │   └── peppol-france-cius/
    │       └── out/
    └── parse/                    # CII XML → GOBL JSON
        ├── en16931/
        │   └── out/
        ├── peppol/
        │   └── out/
        ├── facturx/
        │   └── out/
        ├── xrechnung/
        │   └── out/
        ├── choruspro/
        │   └── out/
        ├── zugferd/
        │   └── out/
        ├── peppol-france-facturx/
        │   └── out/
        ├── peppol-france-cius/
        │   └── out/
        └── peppol-france-extended/
            └── out/

Each out/ directory holds the expected ("golden") output checked in to version control. The --update flag regenerates these files during a test run.

Sources: examples_test.go24-32 examples_test.go54-121 examples_test.go124-210 examples_test.go269-288

---

Diagram: Test Data Flow and Helpers

How examples_test.go resolves file paths

Sources: examples_test.go212-228 examples_test.go231-266 examples_test.go269-313

---

Configuration and Tooling Files

File	Purpose
go.mod	Module path github.com/invopop/gobl.cii, Go 1.24.4 minimum, direct dependencies
go.sum	Dependency checksums
.golangci.yaml	golangci-lint v2 config; enables errname, goconst, gocyclo, nakedret, revive, unconvert, unparam, zerologlint; formatters gofmt and goimports
.github/workflows/	CI workflows (lint, test, release) — see CI/CD Pipeline

Sources: go.mod1-15 .golangci.yaml1-36

---

Direct Module Dependencies

The following direct dependencies are declared in go.mod:

Module	Role
github.com/invopop/gobl	Core GOBL data model (gobl.Envelope, bill.Invoice, addon keys)
github.com/invopop/xmlctx	XML marshal/unmarshal with namespace context
github.com/invopop/phive	Phive gRPC client for schema validation in tests
github.com/invopop/validation	Field-level validation utilities
github.com/spf13/cobra	CLI framework for cmd/gobl.cii
github.com/joho/godotenv	.env file loading (test environment config)
github.com/stretchr/testify	Test assertions (assert, require)
gitlab.com/flimzy/testy	Golden-file test utilities
google.golang.org/grpc	gRPC transport for Phive validation client

For a full description of each dependency, see Module Dependencies.

Sources: go.mod5-15