Architecture
This section describes how Census works internally: the components, how data moves from a source system through the cache to an API response, how the cache is laid out, and the decisions behind that design. It is written for people who change Census or who need to predict its behaviour beyond what the administration and API guides describe.
Components
Census is one server process and one Memgraph database.
- Connectors fetch source objects as JSON. They do not map them to inventory fields.
- The sync layer applies each contribution's mapping, groups records by HFID, resolves the entities, and writes the result to the cache. Each inventory has one writer.
- The query API reads resolved entities from the cache, and computes completeness and freshness at read time. The web UI is a browser application that calls the same API.
Crates of the Cargo workspace
| Crate | Responsibility |
|---|---|
crates/core (fic-core) | Inventory definitions and their validation, source field paths, HFID cleaning, normalization, field resolution, locations, freshness and completeness. No I/O. |
crates/connector-api | The SourceConnector trait: fetch every object of a type, fetch one object, parse webhooks, bind to a branch, build a record's references to its source object. |
crates/connectors/infrahub | Infrahub over GraphQL, with signed webhooks and branches. |
crates/connectors/netbox | NetBox over REST. Full refreshes only. |
crates/store-api | The CacheStore trait, its value types, and the conformance checks every storage backend passes. |
crates/stores/memgraph | The Memgraph backend: one transaction per change, queries on resolved values. |
crates/stores/sqlite | A placeholder for a future backend. Not used. |
crates/sync | The write path: one writer per inventory, full-refresh publication, webhook events, branch views, definition changes at startup. |
crates/server (fic-server) | The binary: configuration, background tasks, the axum API with its OpenAPI document, and the web UI built into the binary. |
web/ | The web UI: a read-only React application served under /ui/. |
Dependencies point one way: core is used by connector-api and store-api; connectors and
stores implement those traits; sync uses the traits; only server knows the concrete
connectors and the Memgraph store. Domain rules live in core so they can be tested without
a database or a source.
Pages of this section
- From source to response: the path of one value.
- The write path: full refreshes, webhooks and the writer of each inventory.
- Cache layout: the nodes Census stores in Memgraph.
- Definition changes: how Census decides between recomputing and fetching again.
- Branch views: how a view of a branch is built and kept.
- Design decisions: the decision records and where the reasoning lives.