Architecture
Architecture
Section titled “Architecture”Atlas is the canonical print-data integration hub: a tenant-scoped service that holds the business record (jobs, orders, customers, estimates, substrates, margins) and reconciles it across every source system. It is a data-integration plane, not a storage backend — consumers reach it over HTTP exactly like the other engines, never as a storage driver.
Where Atlas sits
Section titled “Where Atlas sits”customer → platform → (engines) codex · lint · compile · lens · sift → atlas ← the canonical business record ↕ connectors MIS · ERP · 3PL · JDF/JMF → trove ← the byte plane (artwork, dies, proofs)- platform is the auth + billing authority. It mints the per-tenant JWTs Atlas verifies.
- trove owns bytes. Atlas owns the business record and holds a cross-reference from a canonical entity to the trove asset (by id + sha256), never the bytes themselves.
- The engines (codex/lint/compile/lens/sift) resolve a job’s facts against Atlas by a stable canonical id.
Runtime
Section titled “Runtime”Atlas follows the same blueprint as trove and the rest of the TypeScript tier:
| Layer | Technology |
|---|---|
| Runtime | Node.js 22, TypeScript, ESM |
| API | Hono + zod validation |
| ORM | Drizzle ORM |
| Database | PostgreSQL with row-level security (RLS) |
| Queue | pg-boss (ingest reconciliation runs on a worker) |
| Fan-out | Postgres LISTEN/NOTIFY for SSE |
| Auth | Per-tenant JWT verified via JWKS |
| Errors | RFC 7807 Problem Details |
Every tenant-scoped query runs inside a withTenant(db, tenantId, fn) wrapper
that sets the RLS GUC — see Security.
The two planes
Section titled “The two planes”Atlas separates read from integration:
- Read plane (per-tenant JWT).
GET /v1/entities/*, cross-references, mapping dry-run, adapters, contract. Tenant-isolated; the JWT-scoped tenant is the Atlas tenant. - Ingest plane (endpoint HMAC).
POST /v1/ingest/{endpoint_id}is authenticated by a per-endpoint HMAC secret, not the JWT — each source MIS maps to its own endpoint id + secret. Delivered envelopes are mapped and reconciled asynchronously on a worker. See Ingest.
Deployment modes
Section titled “Deployment modes”Like trove, Atlas surfaces a deployment_mode in GET /v1/contract:
saas— multi-tenant, fronted by platform auth + billing.standalone— single-tenant self-host; works with no platform reachable.dev— local development.
Health & contract endpoints
Section titled “Health & contract endpoints”GET /healthz— liveness.GET /readyz— readiness (DB reachable).GET /v1/contract— the version/schema lattice consumers floor-pin. See Contract.