atlas

Canonical print-data integration hub — mappings, cross-references, and sync for print MIS / ERP / prepress / shipping systems.

atlas gives a print operation one canonical model of its commercial and production data — customers, products, substrates, estimates, orders, jobs, operations, cost/price lines, shipments, invoices, margins, and availability snapshots — and keeps that model in sync with the systems that produce and consume it. It is API-first and runs standalone: connect a system, define sync rules and mapping pipelines, and trigger syncs manually or over the API.

What it does

Canonical model — a semver-versioned schema for the twelve v1 entities, with per-field provenance (which system, which field, which transform, when) on every canonical field.
Cross-references (xref) — atlas mints every canonical id; a typed, indexed xref layer maps those ids to the keys of every connected system, with forward and reverse lookup.
Mapping pipelines — declarative source↔canonical↔target maps with a transform library (units, currency, dates/timezones, enum lookups, computed expressions), versioning, and dry-run/replay against captured payloads.
Sync rules — per-field source-of-truth precedence (never last-write-wins), deterministic and probabilistic matching with a review queue, drift detection, and a dead-letter queue with replay.
Integration flows — a read surface for flow status, sync lag, and divergence flags, including a “where is this job” view across systems.

Status

Beta (0.x, through M10 hardening). In place: the schema and tenancy/RLS layer, the operational surface, the mapping engine (versioned mapping pipelines + dry-run over /v1/mappings), the event spine (signed webhook ingest over /v1/ingest, the canonical event log + replay over /v1/envelopes), and the first source integration — lintPDF preflight events flow into canonical jobs with cross-references and per-field provenance, and findings render into customer / operator / MIS views over /v1/findings/views — plus the print job-ticket engine: JDF 1.x / XJDF 2.x parsing with vendor dialect detection and JMF messaging over /v1/jdf/*. Several system adapters run on the shared adapter base with per-entity capability tiers surfaced over /v1/adapters: the Tharstern MIS (round-trip), ShipStation — the first webhook-native fulfilment integration, which takes the canonical Shipment entity live — and LabelTraxx, whose Cloud API (customers / tickets→orders / products / packing-slips→shipments / AR-invoices) is read-mapped from LabelTraxx’s official OpenAPI spec. ShipStation’s notification pings are pulled back over authenticated REST (credentials held in tenant-scoped connections, managed over /v1/connections), with a same-origin guard protecting the credentialed fetch. EFI Radius’s and HiFlow Solutions’ JDF/JMF lanes are surfaced too — HiFlow’s Product + Job tickets parse green against real vendor samples. On top of all this sits the MDM layer (opt-in): per-field source-of-truth precedence, deterministic→probabilistic entity matching with a review queue (/v1/matches), drift detection (/v1/drift), and a dead-letter replay surface (/v1/dead-letters) — configured via /v1/precedence-rules and /v1/match-rules. New REST systems can be connected without shipping code via config-driven connector definitions (/v1/connector-definitions — resource paths, pagination, and a read-mapping, dry-runnable, with vendor presets installable in one call); the per-vendor adapters run on this same generic engine. A read-only public read surface exposes every canonical entity (/v1/entities/{type}) plus the cross-system “where is this” view (/{id}/cross-references — xrefs, per-field provenance, and divergence). The HTTP surface is hardened (security headers, a request body-size cap, an env-gated CORS allowlist, and the no-SSRF outbound-fetch invariant). All documented in docs/openapi.yaml. Further system adapters land milestone by milestone — see CHANGES.md.

Stack

Hono + TypeScript + Drizzle + PostgreSQL (row-level security) + pg-boss. pnpm 10 monorepo with turbo + Biome.

apps/
  api/        HTTP API — health/contract/metrics + the /v1 surface
  worker/     async runner (scheduled syncs, drift detection, replay)
packages/
  core/       shared primitives: canonical vocabulary, envelope, errors
  db/         Drizzle schema, migrations, RLS helpers

Operational surface

Endpoint	Purpose
`GET /healthz`	liveness
`GET /readyz`	readiness
`GET /v1/contract`	published versions + vocabulary consumers pin against
`GET /metrics`	Prometheus

Deployment modes

Mode	Auth	Tenancy
`saas`	per-tenant JWT (JWKS or static public key)	rooted at the hosting control plane
`standalone`	shared bearer token (`ATLAS_API_TOKEN`)	self-issued
`dev`	none (header only)	self-issued

Pin with ATLAS_MODE, or let it infer from which auth env is configured. The mode is surfaced in GET /v1/contract.

Local dev

corepack enable && corepack prepare [email protected] --activate
pnpm install
pnpm lint && pnpm build && pnpm typecheck && pnpm test
# DB-backed tests (RLS isolation + coverage) need DATABASE_URL; they skip without it.
cd apps/api && pnpm dev

License

AGPL-3.0-or-later. Every source file carries an SPDX header; CI enforces it.