Signup and Billing: Addi Architecture Disclosure

Overview · Modules · Signup and Billing

What it is

Turning a stranger into a tenant

Signup and billing is the module that turns a stranger into a tenant and keeps that tenant's commercial state true. It owns two things: the public self-serve signup path on the user lane, and credit-based billing on Stripe. Identity itself is not ours to build; Clerk owns authentication and organization membership, and this module listens to the identity provider's webhook to provision the tenant on our side. Provisioning is idempotent by design, because webhooks retry and a retried event must never mint a second tenant. A newly provisioned tenant is born with a default module policy, so there is no window in which a fresh account exists with an undefined shape.

On the billing side we deliberately keep the module thin. Stripe, as the billing processor, owns plans, payment collection, and the customer portal; our side records the business facts that fall out of those interactions and feeds them to the rest of the platform. What we keep in our own hands are the rules that are product decisions, not payment mechanics: credits as the unit of consumption, downgrades deferred to the end of the paid period so a customer never loses mid-period what they paid for, and a billing pause switch that lets us run a surface dark, exercising the whole path without charging anyone.

The questions it answers

What it must be able to answer

How does someone become a customer without talking to us?
What does a brand-new tenant look like the moment it exists, and who decided that?
What happens when a customer changes plans, and when does the change bite?
How do we launch a paid surface before we are ready to charge for it?

Scope and boundaries

What it owns, and what it does not

In scope: the self-serve signup path, idempotent tenant provisioning from the identity provider's webhook, the default module policy applied at birth, credit-based plan state, deferred downgrades, and the billing pause switch. Out of scope: authentication and membership (the identity provider owns those), entitlement resolution (the entitlements-and-config unit resolves what a tenant may do, fail-closed, at one choke point; this module only supplies the commercial facts that resolution reads), and everything downstream of a tenant existing.

What it is NOT

It is not an identity system, not an entitlement engine, and not a revenue analytics surface. It does not decide what a plan permits; it records what plan a tenant is on and lets the configuration kernel and entitlement resolution turn that into permitted behavior.

Withheld by design Tier 3

Commercial terms are withheld by design: prices, plan names, coupon structure, and margins are held at Tier 3.

The contract

The unit's public shape

What it is responsible for, the commands its write door accepts, the facts it announces, what it guarantees, and what it refuses. Fields, schemas, and payloads are held at Tier 2.

Responsibilities

Provision a tenant when the identity provider reports a new self-serve organization, exactly once per organization regardless of delivery retries.
Apply the default module policy at the moment of provisioning, so a tenant is never observable in an unshaped state.
Hold the tenant's commercial facts: current plan, credit balance state, and any scheduled change, sourced from Stripe interactions and our own product rules.
Operate the billing pause switch, so a surface can run dark end to end without a charge.
Supply commercial facts to entitlement resolution. It supplies; it never resolves.

The write door

One write door, a small set of commands named by the business action, covering the provisioning of a tenant, the lifecycle of its subscription and plan, and the billing pause switch.

There is no command for editing entitlements, moving deals, or touching another module's data, because those are not this unit's business actions. Like every module, the door is the only way in: human surfaces and the agent use the same commands, under the same rules.

Withheld by design Tier 2

The roster and the shapes are held at Tier 2.

Events announced

Events carry identity plus the fact, never a data dump. In plain words, the unit announces that a tenant was provisioned, that a subscription's state changed, and that billing was paused or resumed. The event roster is held at Tier 2.

Other modules react to these facts through their own doors. Nothing subscribes to this unit's tables, because no module reads another module's tables.

Guarantees

Idempotent provisioning: the same identity-provider event, delivered any number of times, yields one tenant with one default module policy.
Birth with shape: there is no interval in which a tenant exists without a module policy.
Deferred downgrades: a downgrade takes effect at the end of the current paid period, never mid-period. The customer keeps what they paid for until the period closes.
Processor boundary: payment collection and the customer portal belong to Stripe. We do not reimplement payment mechanics; we record their business outcomes.
Pause honesty: while billing is paused, the full path executes and no charge occurs.
Tenancy: every record this unit writes carries the tenant, like every record in the platform.

Refusals

It refuses to create a second tenant for an organization it has already provisioned.
It refuses to apply a downgrade mid-period; the only path is the scheduled, period-end change.
It refuses to answer entitlement questions. A caller asking "may this tenant do X" is redirected to entitlement resolution, which fails closed; this unit only states the commercial facts resolution reads.
It refuses writes into any other module's domain, and accepts none into its own except through the door above.

What done means

The gates a change passes

Done for this unit is not "signup works on the happy path". Done is the set of properties below holding under the cases that would break them, proven by real tests and by the live surface holding up against the real backend in its loading, empty, error, and content states.

The provisioning convergence gate. Provisioning must converge: one organization, one tenant, one default module policy, however many times or in whatever order the identity provider's event arrives. This gate exists because webhook delivery is at-least-once by nature, and any design that assumes exactly-once is a latent duplicate-tenant bug.
The birth-shape gate. A freshly provisioned tenant's module policy must be the published default from the first observable moment, and every surface that renders for it must render from that published configuration. No tenant is observable unshaped.
The period-boundary gate. Capability must persist to the end of the paid period and change only when it closes.
The choke-point gate. No surface or module may decide behavior by reading this unit's data directly. Commercial facts influence the platform only through entitlement resolution, which fails closed when it cannot resolve.
The pause gate. With billing paused, the whole path must run end to end with no charge produced, so a dark launch is a real rehearsal of the live path rather than a mock of it.

Withheld by design Tier 2

The gate descriptions are here; their concrete test inventories are held at Tier 2.

The failing cases

A replayed provisioning event that creates a second tenant is a failing build.
A tenant that exists, for any observable interval, without its default module policy is a failing build.
A downgrade that removes capability before the paid period ends is a failing build.
Any surface that reads billing state directly instead of going through entitlement resolution is a failing build, even if its answer happens to be correct.
A paused billing path that still produces a charge, or a pause that silently skips part of the path instead of running it without charging, is a failing build.

Honest-state behaviors

Denial is the honest default. When entitlement resolution cannot determine a tenant's standing, the platform fails closed. A guess in the customer's favor is still a guess.
A scheduled downgrade is a visible fact, not a silent future: the tenant's commercial state carries the scheduled change until it applies.
The pause switch is a stated mode, not an ambiguity. A path is either live or dark; the switch records which, and the rehearsal value of a dark run depends on that record being true.
Provisioning failures surface as failures. A signup that could not complete is reported as such rather than leaving a half-born tenant, because the birth-shape guarantee makes partial existence a defect, not a state.

Where it connects

The spine sections this unit realizes

Section 5, one product, two lanes: signup exists only on the public self-serve lane; the internal lane is invite-only.
Section 6, the configuration kernel: the default module policy a new tenant is born with is configuration, published and versioned like all configuration.
Section 7, modules and boundaries: this unit owns its tables, exposes one write door, and announces business facts as events.
Section 13, tenancy and isolation: the tenant this module creates is the identity stamped on every record platform-wide, and entitlements resolve fail-closed at one choke point.