Multi‑tenancy & host seams

Motivation

Most invite packages make codes globally unique. That breaks the moment two customers of the same
SaaS both want the intuitive code WELCOME2025, and it risks rows leaking across customer boundaries
— a GDPR catastrophe. A package that wants to power a multi‑tenant product has to make the tenant
the unit of isolation, not the global table.

At the same time, the engine must stay vendor‑neutral: it cannot hard‑code your User model, your
tenancy package, or your permission system. It solves both with one idea — tenant‑scoped rows behind
three small host seams.

Theory — the isolation boundary

Every domain table carries a tenant_id column, and every composite unique constraint starts with
it:

Uniqueness is therefore per tenant. Two tenants $t_1 \ne t_2$ may both hold a code with the same
string c:

Every read and write is scoped through a forTenant($tenantId) query scope (the BelongsToTenant
trait), and the active tenant comes from a single resolver. The application‑layer scope — not a
foreign key — is the cross‑tenant boundary, exactly as in the host AskMyDocs codebase (rule R30).

Design — the three seams

TenantResolver

interface TenantResolver
{
    public function current(): string; // the active tenant id
}

DefaultTenantResolver always returns the configured default_tenant ('default'), so a
single‑tenant app needs zero configuration. A multi‑tenant host binds its own:

$this->app->bind(
    \Padosoft\Invitations\Contracts\TenantResolver::class,
    fn () => new MyTenantResolver(app(MyTenantContext::class)),
);

Provisioner (GRANT‑never‑REVOKE)

On a fresh claim, the engine provisions the redeemer from the invite’s grant (a per‑code override
falling back to the campaign default). Provisioners are additive only — an invite can raise
access (grant a role, firstOrCreate a membership) but never downgrade it. Provisioning is
best‑effort: a provisioner fault is swallowed and logged, never failing an already‑committed
redemption.

$this->app->tag([MyProjectMembershipProvisioner::class], 'invitations.provisioners');

The default SpatiePermissionProvisioner grants a role when spatie/laravel-permission is present;
project / team membership is the one genuinely host‑specific seam and ships as a host‑supplied
provisioner.

InvitedAccount

interface InvitedAccount
{
    public function getInviteEmail(): ?string;
}

The InteractsWithInvitations trait satisfies it from the model’s email attribute. The engine never
references a concrete App\Models\User; the class is configurable via INVITATIONS_USER_MODEL.

Data model / contract

Every tenant‑aware table follows the same shape:

$table->string('tenant_id', 50)->default('default')->index();
// …domain columns…
$table->unique(['tenant_id', /* natural key */], 'uq_…');

The default('default') keeps single‑tenant and legacy rows valid with no migration dance, mirroring
the host platform’s backward‑compatibility convention.

ADR

Worked example — two tenants, same code

// Tenant "acme"
app()->bind(TenantResolver::class, fn () => new FixedTenant('acme'));
$a = app(CodeGenerator::class)->mintVanity('WELCOME2025');

// Tenant "globex"
app()->bind(TenantResolver::class, fn () => new FixedTenant('globex'));
$g = app(CodeGenerator::class)->mintVanity('WELCOME2025'); // ✅ not a collision

assert($a->code === $g->code);          // same human string
assert($a->tenant_id !== $g->tenant_id); // different isolation boundary