bus-entities — counterparty reference data and stable entity IDs (SDD)
bus-entities — counterparty reference data and stable entity IDs
Introduction and Overview
Bus Entities maintains counterparty reference datasets as schema-validated repository data, normalizes identity details, and provides stable entity identifiers for linking across modules.
Requirements
FR-ENT-001 Entity registry. The module MUST store entity reference data with stable identifiers and schema validation. Acceptance criteria: entity rows validate against schemas and expose stable identifiers for use in other datasets.
FR-ENT-002 CLI surface for reference data. The module MUST provide commands to initialize, list, and add entities. Acceptance criteria: init, list, and add are available under bus entities.
NFR-ENT-001 Auditability. Entity records MUST remain stable across the retention period when referenced by vouchers, invoices, or bank data. Acceptance criteria: identifiers are stable and corrections are append-only.
NFR-ENT-002 Path exposure via Go library. The module MUST expose a Go library API that returns the workspace-relative path(s) to its owned data file(s) (entities table and schema). Other modules that need read-only access to the entity registry raw file(s) MUST obtain the path(s) from this module’s library, not by hardcoding file names. The API MUST be designed so that future dynamic path configuration can be supported without breaking consumers. Acceptance criteria: the library provides path accessor(s) for the entities dataset; consumers use these accessors for read-only access; no consumer hardcodes entities.csv outside this module.
System Architecture
Bus Entities owns the entity reference dataset (entities.csv) at the workspace root (no entities/ subdirectory) and provides stable identifiers to other modules. It integrates with invoices, bank imports, reconciliation, VAT, and attachments through shared identifier references.
Key Decisions
KD-ENT-001 Entity data is a shared reference dataset. Counterparty identifiers are stored as repository data and reused across modules.
KD-ENT-002 Path exposure for read-only consumption. The module exposes path accessors in its Go library so that other modules can resolve the location of the entity dataset for read-only access. Write access and all entity business logic remain in this module.
Component Design and Interfaces
Interface IF-ENT-001 (module CLI). The module exposes bus entities with subcommands init, list, and add and follows BusDK CLI conventions for deterministic output and diagnostics.
The init command creates the baseline entity dataset and schema when they are absent. If both entities.csv and entities.schema.json already exist and are consistent, init prints a warning to standard error and exits 0 without modifying anything. If only one of them exists or the data is inconsistent, init fails with a clear error to standard error, does not write any file, and exits non-zero (see bus-init FR-INIT-004).
The add command accepts entity identity parameters. Documented parameters are --id <entity-id> and --name <display-name>, with no positional arguments. The list command accepts no module-specific filters and returns the full entity registry in stable identifier order.
Interface IF-ENT-002 (path accessors, Go library). The module exposes Go library functions that return the workspace-relative path(s) to its owned data file(s) (e.g. entities CSV and schema). Given a workspace root path, the library returns the path(s); resolution MUST allow future override from workspace or data package configuration. Other modules use these accessors for read-only access only; all writes and entity logic remain in this module.
Usage examples:
bus entities init
bus entities list
bus entities add --id ENT-ACME --name "Acme Corp"
Data Design
The module reads and writes entities.csv with a beside-the-dataset JSON Table Schema entities.schema.json in the accounts area at the workspace root. Entity data does not use a dedicated subdirectory: entities.csv and entities.schema.json sit at the same level as accounts.csv and other canonical datasets, as defined in the minimal workspace baseline. The entity identifier is treated as a stable key referenced by other datasets.
Other modules that need read-only access to the entity registry MUST obtain the path from this module’s Go library (IF-ENT-002). All writes and entity-domain logic remain in this module.
Assumptions and Dependencies
Bus Entities depends on the workspace layout and schema conventions. Missing datasets or schemas result in deterministic diagnostics.
Security Considerations
Entity reference data may include sensitive personal or business details and should be protected by repository access controls. Corrections are recorded as new rows.
Observability and Logging
Command results are written to standard output, and diagnostics are written to standard error with deterministic references to dataset paths and identifiers.
Error Handling and Resilience
Invalid usage exits with a non-zero status and a concise usage error. Schema violations exit non-zero without modifying datasets.
Testing Strategy
Unit tests cover entity validation and identifier stability, and command-level tests exercise init, add, and list against fixture workspaces.
Deployment and Operations
Not Applicable. The module ships as a BusDK CLI component and relies on the standard workspace layout.
Migration/Rollout
Not Applicable. Schema evolution is handled through the standard schema migration workflow for workspace datasets.
Risks
Not Applicable. Module-specific risks are not enumerated beyond the general need for deterministic reference data handling.
Glossary and Terminology
Entity: a counterparty or reference subject represented as a stable identifier in workspace datasets.
Entity registry: the dataset storing entity identifiers and metadata.