Entitlements and Config: Addi Architecture Disclosure

Overview · Modules · Entitlements and Config

What it is

Where the platform's shape stops being code

This unit is the configuration kernel: the place where the platform's shape stops being code and becomes data. The tenant's entire product shape is authored here as configuration, not compiled in; the classes of configuration are defined once, in the data dictionary. An admin drafts a change, the draft is validated, and the whole thing publishes as one atomic versioned set. Every surface in the product renders the published set and nothing else; drafts never leak into what anyone sees. Rollback is a forward roll: reverting means publishing a new set that restates the old truth, and the rollback path never edits a prior version.

We built it this way because the alternative is the one every platform team knows: behavior scattered across code branches, feature flags, and environment switches, where answering "what is actually on for this tenant" requires an archaeologist. We wanted one answer to that question, and we wanted it to be data an admin can change without a developer. That is the configurability-without-code quality goal made concrete: the same codebase serves many tenant postures because posture is configuration, not a fork.

The unit also owns a load-bearing safety property: entitlement resolution is fail-closed at one choke point. When a surface, a scheduled job, or the agent asks "may this tenant do this", the answer comes from one place, and when that place cannot say yes with certainty, the answer is no. The composed module set is the one switch, and switching a module off means dead server-side: its writes refuse, its scheduled jobs deactivate, its notifications drop. Off that only hides a surface is not off, and we do not ship it.

The questions it answers

For the operator and the admin

What is actually switched on for this tenant, right now, on one screen I can trust?
Can I reshape a tenant's product, its modules, pipeline, stages, and fields, without a code change or a deploy?
When I publish a change, does everything change together, or can a surface render a half-applied state?
If a change was wrong, how do I get back?

Scope and boundaries

What it owns, and what it does not

The unit owns configuration authorship, validation, the versioned publish, entitlement resolution, and a read-only truth view of every switch. It does not own the behaviors it switches: each module owns its own capability and merely consults this unit for permission and shape. It does not own identity or membership; the identity provider owns who a person is and which organization they belong to, and this unit owns what that organization's product looks like and what it may do. The lane fork also lives outside it: the internal and self-serve lanes are separated at the infrastructure layer, and within each lane this unit shapes every tenant the same way.

What it is NOT

It is not a feature-flag service bolted on the side; it is the single definition of the tenant's shape, and everything else defers to it. It is not an admin panel in the sense of a bag of toggles; changes travel as validated, versioned sets, not individual switch flips. It is not identity: authentication and membership live with the identity provider. And its configuration schema is not part of this package.

Withheld by design Tier 2

The configuration schema itself is held at Tier 2.

The contract

The unit's public shape

What it is responsible for, how it is written to, what it announces, what it guarantees, and what it refuses. The configuration schema, field lists, and payloads are held at Tier 2.

Responsibilities

Hold the platform's shape as data, authored rather than coded; the classes of configuration it holds are defined once, in the data dictionary.
Carry a draft through validation to an atomic, versioned publish, and keep the published set as the single truth every surface renders.
Resolve every entitlement question at one choke point, fail-closed: when the answer is not certainly yes, it is no.
Enforce that a disabled module is dead server-side: its writes refuse, its scheduled jobs deactivate, its notifications drop.
Serve a read-only truth view of every switch, so the state of the platform can be read without being able to change it from the same place.
Keep rollback non-destructive: rollback is a forward roll to a new set restating the old truth; the rollback path never edits a prior version.

The write door

Like every module, this unit has one write door, and it admits a small set of business-named commands. At this altitude the door admits three kinds of action:

Draft authorship. An admin shapes the change in a working draft that no rendering surface can see.
Publication. The validated draft becomes the live versioned set, atomically, everywhere at once. Rolling back is the same act pointed at a prior truth: publishing the set that restates it.
Composition. Granting or withdrawing a module, or reshaping a tenant's composed set, is a business action in its own right and travels through the same publish discipline.

Agent writes arrive through this same door under the same rules as human writes; agents get the door, never the tables.

Withheld by design Tier 2

The command roster, with its inputs, is held at Tier 2.

Events announced

The unit announces business facts, carrying identity plus the fact, never a data dump:

A new configuration set was published, and which version is now live.
A tenant's module composition changed.

Modules react through their own contracts: a module learning it is now off for a tenant deactivates its own jobs and refuses its own writes; surfaces re-render from the new published set. This unit does not reach into another module's tables to switch anything off, and no module reads its tables; permission is asked at the choke point, not read from storage.

Guarantees

One live version at a time, everywhere. No surface, job, or agent call can observe a half-applied set; publish is atomic and versioned.
Drafts never leak. Until publish, a draft is invisible to every rendering surface and every enforcement path.
Entitlement resolution is fail-closed. Errors, gaps, and ambiguity all resolve to no, at the one choke point every caller uses.
Concurrent publishes are caught. Two admins racing to publish is a detected conflict, never a silent overwrite of either's intent.
Feature off means dead, server-side, uniformly: refused writes, deactivated jobs, dropped notifications. The composed module set is the one switch.
The truth view matches enforcement. What the read-only view says is on is what the choke point enforces, because both read the same published set.
Rollback is a forward roll. Reverting publishes a new set that restates the prior truth, adding a version rather than editing one; the rollback path never touches a prior version.

Refusals

It refuses to apply a change partially. There is no path that flips one switch out of a draft; the set publishes whole or not at all.
It refuses to publish a draft that fails validation.
It refuses to answer an entitlement question with a guess. No certain yes means no.
It refuses to let any caller bypass the choke point; there is no second place to ask and no direct read of its tables from other modules.
It refuses a destructive rollback. Reverting means publishing a new set that restates the prior truth, never editing a prior version.
It refuses to take agent writes on any other terms than human ones: they arrive through the same door under the same rules, under the write law.

What done means

The gates a change passes

Done for this unit is not "the switches render". Done is the unit keeping its promises in the cases that would break them, proven mechanically, on the live surface. Every module's off switch and every tenant's shape depend on this unit being right.

The spec gate. No code before the outcome and the logic are settled with an explicit go-ahead: what publishing must feel like to an admin, what the choke point must guarantee to every caller, and the rules that keep those promises in the breaking cases, are written down first.
Load-bearing rules as code. The rules that carry this unit's promises, that publish is atomic, that resolution fails closed, that drafts cannot reach a rendering path, that concurrent publishes conflict, are expressed as typed contracts, server-side checks, and failing tests, never as prose a future change can quietly ignore.
The program review. A reviewer walks the breaking cases by category: publish atomicity under concurrency and partial-load conditions, entitlement resolution under failure, the off switch under in-flight work, and recovery after a bad publish. The code must keep every promise in each, proven by real tests, not by narrative.
The code review. A separate pass for security, understandability, and consistency with the codebase. The writer is never the auditor.
The live-surface check. Done includes the authoring and truth-view surfaces holding up against the real backend in all four states: loading, empty, error, and content.

The failing cases

A partial publish fails. If any surface, job, or agent call can observe some of a new set and some of the old one, the publish was not atomic and the unit's central promise is broken.
A draft that reaches a rendering surface fails. However briefly, an unpublished value seen by anyone other than its author is a leak.
An entitlement check that fails open fails. An error, a timeout, or a gap in the data that resolves to yes is the worst defect this unit can have; uncertainty must land as no.
A silently merged or silently lost concurrent publish fails. Two admins racing must produce a detected conflict, not a quiet winner.
A disabled module that still acts fails. A write that lands, a job that runs, or a notification that sends for a switched-off module means off was cosmetic, and feature off means dead server-side.
A bypass of the choke point fails. A caller that answers its own entitlement question from cached state or a direct read has forked the truth.
A rollback that edits a prior version fails. Reverting is a forward roll to a new set that restates the prior truth; a rollback path that mutates a previously published version is a rewrite, not a rollback.
A truth view that disagrees with enforcement fails. A read-only view that says on while the choke point says off, or the reverse, makes the one trustworthy screen a liar.
An error state that does not name the exact blocker and its fix fails. This is the platform-wide error-state bar applied here: error paths are designed, not caught. A publish refused for validation must say which part of the draft failed and what would satisfy it; "something went wrong" is not a state we ship.

Honest-state behaviors

The truth view presents itself as exactly what it is: a read of the published set, the same set enforcement uses, with the live version identified. It offers no edit affordance, so nobody mistakes reading the state for permission to change it.
A refused publish states its reasons in the admin's own terms: which part of the draft failed validation and what would satisfy it.
A detected publish conflict is surfaced as a conflict, naming that another publish landed first; neither admin is left believing their change went live when it did not.
Empty is a real state. A tenant with a minimal composed set sees that plainly; the unit does not render disabled capability as if it were merely unconfigured, or dress an off switch up as a loading one.

Where it connects

The spine sections this unit realizes

Section 6, the configuration kernel: draft, atomic versioned publish, rollback, and feature-off-means-dead, of which this unit is the owner.
Section 2, quality goals: configurability without code, and one codebase serving many postures, are this unit's reason to exist.
Section 7, modules and boundaries: the composed module set this unit publishes is the shape every module renders and enforces.
Section 13, tenancy and isolation: fail-closed entitlement resolution at one choke point is part of the tenancy enforcement story.
Section 5, one product, two lanes: the lane fork is infrastructure; within a lane, this unit is how tenants differ.