Data model

Data model

Atlas owns the canonical record of the print business. Each entity is modeled once, versioned, tenant-scoped, and content-addressed, instead of being parsed from a request and dropped.

Canonical entities

The canonical entity set is published in GET /v1/contract as canonical_entities. The core types:

Entity	What it is
customer	The print buyer — the print customer, distinct from the platform tenant.
order	A commercial order placed by a customer.
job	A unit of production work tied to an order. The canonical “job” the stack never had.
estimate / quote	Priced work read from the MIS.
substrate / material	Stock and material records, with availability.
shipment	Outbound fulfilment for an order.
margin	Derived: planned cost vs. quoted price (and, later, actuals).

Each entity is addressed as GET /v1/entities/{type}/{id} and listed with GET /v1/entities/{type}?limit&offset (limit ≤ 200). See the API reference.

The canonical id

Atlas mints a stable canonical id per entity. This id is the join key the whole stack uses — a prepress tool resolves a job by the canonical id, not by any one system’s internal key. The id rides existing opaque fields in the other systems; it never collides with an execution-job id (a synergy job run, a lint job, an artwork render) — those are unrelated id spaces.

Cross-references

Every canonical entity carries a cross-system “where is this” view, returned by GET /v1/entities/{type}/{id}/cross-references:

{
  "references": [ /* {system, external_id} per source system */ ],
  "provenance": [ /* which source set each field, and when */ ],
  "openDrift":  [ /* fields where sources currently disagree */ ]
}

• references — the map from this canonical id to each source system’s own key (MIS, ERP, 3PL, and each prepress tool).
• provenance — per-field lineage: which source last wrote each value.
• openDrift — fields where two systems currently disagree and reconciliation hasn’t resolved a winner. Drift is surfaced, not silently overwritten.

Tenancy

The tenant identity root is the platform tenant (tenants.id). Atlas provisions a tenant lazily on first use (the trove/synergy pattern) and isolates all entity, cross-reference, and mapping data per tenant with Postgres RLS. In standalone mode Atlas runs single-tenant with no platform reachable.