01.5 — Atlas

Architectural invariants,
verified in CI.

Atlas declares what every Portiko app must be true about — tenancy posture, schema discipline, cross-app references, polymorphic dispatch — and verifies them mechanically against the live repo. Fails closed on drift; composes the library as one library, not four.

Apply for early access How it works

Status: Preview
For: Multi-app deployments
Invariants: Five, verified in CI
Pricing: TBD

A — Who Atlas is for

For multi-app deployments that need to compose coherently.

Atlas is calibrated for engineering teams running multiple Portiko apps (Cadence + Relay, Cadence + Quorum, or all of them) who want architectural drift caught at CI time, not at the next inspection.

Engineering leads of multi-app deployments

When Cadence + Relay + Quorum run together, the tenancy posture, schema discipline, and cross-app references have to hold. Atlas turns 'we agreed on this' into 'CI verifies this'.

Architecture review teams

Architectural decisions become enforceable — not just documented. Each invariant is declared, verified, and revisited explicitly. Drift is observable, not implicit.

Future-platform teams

When Portiko adds a fifth app (or a partner adds their own app alongside ours), Atlas declares what that app must be true about to compose. New apps inherit the invariants; the library stays coherent.

B — How it works

Four pillars: declare, verify, fail-closed, compose.

Atlas is organised around the discipline of cross-system architectural enforcement. Each invariant is declared in writing, verified in code, fails closed when it drifts, and composes with the others without redundancy.

Declare

Every invariant is a markdown file in `atlas/invariants/` naming scope, source ADR, exemptions, and verification path. The declaration is the contract; the script is the enforcement.

Verify

Each invariant has an executable verifier that reads live repo state — schemas, READMEs, configs, seeded data — and checks the invariant. Verification runs in CI on every push.

Fail closed

If an app drifts from a declared invariant, the gate fails the build. There is no 'we'll fix it next sprint' mode. The library composes coherently because every app is held to its declared posture, mechanically.

Compose

Cadence, Relay, Quorum, Beacon each own their own substrate; Atlas owns what they have in common. The result: four apps that compose as one library, not four parallel codebases.

C — Invariants

Five invariants, verified across four apps.

Each invariant is a markdown declaration plus an executable verifier. The set is small by design — every invariant has to justify its presence, and every app it applies to has to satisfy it. New invariants are added when the architectural concern is genuinely cross-cutting.

01
I1 — Tenancy posture
Every app declares its tenancy model (org-id-multi-tenant, institutional-identity, single-tenant) in its README; declarations are non-empty and well-formed.
02
I2 — `org_id` conformance
Apps declaring `org-id-multi-tenant` carry `org_id NOT NULL` on every non-exempt schema table. Exemptions are explicit.
03
I3 — Shared schemas package
`org-id-multi-tenant` apps depend on `@portiko/schemas` rather than reinventing tenancy primitives.
04
I4 — Internal reference resolution
Every soft-FK column in Relay's SQLite resolves against a live row. Polymorphic (kind, id) references are typed-dispatched; vocabulary drift fails closed.
05
I5 — Cross-app reference resolution
References from one app's data into another's (e.g. Relay safety-net → Cadence incident) resolve via the published snapshot contracts, not direct DB access.

D — What Atlas shows

Two real outputs from the running verifiers.

Atlas has no UI. The artefacts are the verifier scripts and their CLI output, captured against the live repo state. Both outputs below are verbatim from a recent run — green where every app satisfies the declared invariant, red where any one drifts.

$ pnpm atlas:verify-invariants

[atlas-verify-invariants] ok —
  I1: 5 apps declare posture;
  I2: 44 tables verified (5 exempt);
  I3: 2 apps depend on @portiko/schemas.

Fig. 01 — atlas:verify-invariants across the live repo. I1 + I2 + I3 green; 44 tables conforming, 5 documented exemptions.

$ pnpm atlas:verify-references

[atlas-verify-references] ok —
  20 fixed edge(s) verified (154 non-null, 0 dangling);
  3 polymorphic edge(s) verified
    (22 resolved, 4 institutional-fact skipped,
     0 dangling, 0 unknown kinds).

Fig. 02 — atlas:verify-references against the seeded Relay SQLite. 154 fixed references + 22 polymorphic references all resolve; no dangling refs.

E — Honest notes

Things worth saying explicitly.

Atlas is not a database or query layer.

It does not federate queries across apps, broker cross-app data access, or own any persistent state. It verifies; it does not store.

Atlas is not a fifth product surface.

There is no Atlas UI. The artefact is the invariant declarations + executable verifiers. The value is architectural integrity, not a dashboard.

Atlas does not replace ADRs or design reviews.

Architectural decisions still get made by humans, with judgement, in written ADRs. Atlas mechanically enforces the decisions once made — the substance is yours, the enforcement is Atlas's.

Atlas is preview, not GA.

Five invariants, 13 acceptance tests, verified across all four apps. Engineering-verified; pilot access for teams running multi-app Portiko deployments is by application.

F — Access

Pilot by application.

Atlas — pilot access

By application

Pricing follows multi-app deployment validation.

· Founder-level support during pilot
· Invariant calibration for your specific app set
· CI integration with your deployment pipeline
· Direct influence over the GA invariant vocabulary
· Preferential GA pricing when published

Pilot partners commit to approximately two hours per month of feedback time across the first three months — an invariant-calibration session at month one, a CI integration review at month two, an architectural-drift debrief at month three.

Apply for pilot access

G — Common questions

Frequently asked.

Why is Atlas a separate thing, not just unit tests?: Unit tests verify code behaviour within an app. Atlas verifies architectural posture across apps — that Cadence's `org_id` discipline still holds, that Relay's shared-schemas dependency hasn't been forked, that cross-app references resolve. These are not in-app concerns; they are library-wide invariants, and they need to be declared and enforced at that level.
What happens when an invariant fails?: The verifier exits non-zero with a diagnostic naming which app, which invariant, and which line of code drifted. CI fails the build; the team fixes the drift or amends the invariant declaration. There is no 'override' or 'temporary exception' — the architectural posture either holds or it doesn't.
Can I use Atlas without the rest of Portiko?: Atlas's current invariants are calibrated to the Portiko library's apps. The pattern — declared invariants + executable verifiers — generalises, but the specific I1–I5 are about the four-app library. Use Atlas as a model; the invariants themselves are coupled to the library they verify.
Who configures the invariants?: An invariant is added when the same architectural concern surfaces across multiple apps and would otherwise be discovered too late. The pattern: declaration in `atlas/invariants/<INV-id>.md`, verifier in `scripts/atlas-verify-<topic>.mjs`, acceptance tests in `scripts/test-atlas.mjs`. New invariants are reviewed against the existing ones for orthogonality.

Architectural invariants,verified in CI.