The sovereign methodology, explained.

The methodology on this page is not a whitepaper. There is a working reference portal on GitHub — Apache 2.0, cloneable, runnable in about ten minutes. It implements Users, Companies, and Workspaces as sovereign modules and demonstrates the SMI in code.

The public repository documents the architecture at overview depth. The full Standard Module Interface, the twenty anti-patterns in full narrative, the capability vocabulary, and the operator-composition model ship with Sovereign Foundation. Continuous audit of your team's modules against the full spec ships with Sovereign Dev Pass.

Every sovereign module conforms to one contract. Same lifecycle hooks, same authorization surface, same event-publish rules. The framework reads modules through their registry manifest and treats every module the same way. Modules talk to each other through SMI endpoints, never through each other's internals.

The interface is small on purpose. v0.1 has nine sections — Identity Context, Authorization, Lifecycle, Registry, API Surface, Events, Data Ownership, Auth Adapter, and Supporting Types. v0.2 adds four amendments covering role catalogs and operator composition. Every module exports about fifteen methods.

The Auth Adapter is the seam. It is the only place in the framework that touches headers, cookies, or external identity providers. Every downstream module sees a resolved IdentityContext. Swap Auth0 for Okta by writing a new adapter — every module comes along for free, unchanged. The adapter interface has four methods: resolve, startSignIn, completeSignIn, signOut. Adapters are typically 100–300 lines.

What the SMI enforces: declared events are the only events a module may emit (§6). Owned collections cannot be read by another module (§7). The uninstall contract is non-negotiable (§3). A module that lies about any of these fails the conformance suite.

The public repo documents the sections, method signatures, and the AuthAdapter interface verbatim. The full spec, worked examples, and the conformance suite ship with Sovereign Foundation. Read the public SMI overview →

The four layers are Users, Companies, Workspaces, and Modules. They are sovereign and they compose. They are not a strict hierarchy. A User can belong to many Companies. A Company can host many Workspaces. Modules install into Workspaces but govern themselves. This is what makes zero-touch customer expansion possible.

Every request passes through three runtime checks, in order: Module access (can this user reach this module at all?) → Function access (can this user do this specific thing?) → Data access (can this user act on this specific record?). Any check can deny. Audit logs stay honest because the reasons are separable.

A concrete example. Alex is a Dispatcher at Northwind Logistics (Company) in the Chicago hub (Workspace) using the Orders module. When Alex opens order #4472, the framework runs: Module access — does Alex's role at Northwind grant Orders access? Yes. Function access — does Dispatcher have orders.view? Yes. Data access — is #4472 in the Chicago workspace Alex can act in? Yes. Handler runs. Change any of those three and the request fails at exactly the layer that said no.

What this model deliberately does not have: no global admin, no Workspace-tier "Admin" role, no implicit User → Company attachment, no hierarchical role inheritance. Every absence is deliberate. Operators use the same model as customers — the operator claim composes with tenant roles, it does not bypass them.

The public repo documents the four layers, the three-check sequence, and the deliberate absences. The capability vocabulary, the effective-role computation ("highest rank wins"), the per-record attachment scope, and the full operator-composition model ship with Sovereign Foundation. Read the public permission model overview →

Twenty documented mistakes we caught and fixed while building sovereign modules. Each one is a specific class of bug we made hard enough to write down. They are grouped into five categories: Routing and Identity, Authorization, Data Ownership, Events and Side Effects, UI, and Agents.

One example, in shape. Anti-pattern §17 — Treating Users, Companies, or Workspaces as framework primitives. The mistake: writing code that imports a User type from a shared framework package. Why it breaks: the moment a customer needs a second identity provider, or a new user type, or a different auth flow, the primitive has to change and every module that imported it breaks. The fix: Users is a sovereign module that conforms to the SMI like any other. Modules call /smi/users/*, not import User. The warning sign: any module has from '@framework/user' in its imports.

That is what all twenty look like: the mistake in code, why it breaks, the fix, and the warning sign. This catalog is the training set Sovereign Dev Pass audits your PRs against — when one of these patterns lands in your codebase, the audit flags it.

The public catalog lists the twenty titles with one-line summaries. The full narratives — the mistake in code, why it breaks, the fix with diffs, and the exact warning sign — ship with Sovereign Foundation. Read the public catalog →

Every sovereign module carries a declarative Module Registry — a small descriptor that says what the module is, what it depends on, what events it publishes, what collections it owns, and what capabilities it exposes. The framework consumes the registry at install time. It never trusts anything the module says at runtime that contradicts it. If the registry says the module publishes order.completed and the module tries to emit order.finished, the conformance suite fails the build.

Every module also gets an auto-rendered Settings page with four sections: Module Admins (who can configure this module in this Workspace), Available Roles (the module's role catalog), Default Role (the role auto-assigned when a member joins), and Module Registry (a read-only view of what the module declared). Module authors do not build a Settings page. They ship a registry.

The reward: adding a new module to a running portal is configuration, not a code change. No new Settings page to design. No new permission plumbing to wire. No new audit-log fields to add. The framework already knows.

The public repo documents the registry fields and the four Settings sections. The full field reference, worked examples, per-record attachment-scope model, and implementation checklist ship with Sovereign Foundation. Read the public registry overview →

We use "sovereign" deliberately. It means four things:

• Sovereign data — each module owns its own schema, its own collections, its own migrations. Nothing else reaches into them.
• Sovereign API — each module owns its own endpoints. Modules talk to each other only through declared SMI surfaces.
• Sovereign lifecycle — each module can be installed, upgraded, and uninstalled independently. The uninstall contract is non-negotiable.
• Sovereign deployment — each module can run on its own Cloud Run service, its own VPC, its own region. Coupling is architectural, not operational.

The opposite of sovereign is what most legacy software is — tightly coupled, shared-database, can't-remove-one-piece-without-breaking-three-others. That is the software this methodology is designed to replace.