Design decisions

The reasoning behind Census's design is recorded in the repository. This page summarizes the decisions that shape the behaviour described in this documentation, and links to the records, which remain the reference.

• Decision records (ADRs) are in dev/adr/: decisions that constrain future work.
• Notes on how the system works are in dev/knowledge/.
• Each feature's design is in specs/. Named inventories, the current model, are feature 008; its research.md holds decisions D1 to D25. Features 001 to 007 are partly replaced by feature 008.

0001. Identify entities by an inventory-scoped HFID

Before feature 008, Census matched records automatically by ordered identity keys such as serial number, FQDN and management IP. Census now groups records only by their cleaned HFID, within one inventory. An administrator can predict from the configuration which records form one entity, and every identity problem becomes a record that can be found and fixed in the source.

Consequences:

• Records are keyed by inventory, contribution, view, object type and native id; entities by inventory, view and HFID. An HFID change moves a record to another entity.
• Objects that sources name differently are not joined. The sources, or a mapping, must agree on the HFID.
• An HFID change gives a new entity, with no redirect from the old one.

Record: 0001-identify-entities-by-inventory-scoped-hfid.md

0002. Publish each full refresh in one transaction, buffered in memory

Before feature 008, a refresh that failed part-way left the pages it had written visible, mixed with older data. A full refresh is now held in memory and written in one Memgraph transaction, so a failed refresh changes nothing and reads never filter on publication state.

Consequences:

• The storage contract has one write method, commit(ChangeSet), applied in one transaction.
• A refresh's memory grows with the contribution's size. An inventory much larger than the 10,000-entity validation target may need staged publication instead.
• A publication at the target took 1.5 to 2 seconds, during which other writes to the inventory wait.

Record: 0002-publish-full-refreshes-in-one-transaction-from-memory.md

Other decisions of feature 008

These decisions are recorded in feature 008's research file and described on the pages of this section:

Decision	Summary	Page
D2, D3	Records that fail identity checks are stored and flagged; removed records and empty entities are deleted.	Add a contribution
D4	A cache layout version replaces migrations.	Cache layout
D6	One writer per inventory.	The write path
D7	A webhook observation received during a refresh wins over that refresh.	The write path
D8	A webhook triggers a fetch of the object for each contribution that uses it.	The write path
D9 to D13	Field states, no conversion between types, per-field priority, vocabularies and defaults.	Choose which source supplies each field, Normalize source values
D15, D16	Locations declared as paths; a more specific location from a lower-priority source is used only inside the winner's location.	Declare the location hierarchy
D17, D18	Filters, sorting and counts run on resolved values; filters use the filter. prefix and pages use an opaque cursor.	Query entities
D19	One problem type per error case.	Errors
D20	Two hashes decide between recomputing and fetching again.	Definition changes
D22	Branch views are built per inventory, and a branching source that cannot be reached fails the view.	Branch views

Limits that follow from these decisions

• Configuration changes need a restart; there is no reload and no configuration API.
• There is no authentication; Census runs on a trusted network. crates/server/src/main.rs marks the place where an authentication layer would be added.
• Pagination is best effort over current data, not over a consistent snapshot.
• Memgraph is the only cache backend. crates/stores/sqlite is a placeholder.