The sovereign methodology, explained.

Four principles the codebase enforces. Every module conforms to them, or the conformance suite fails the build. These are not aspirational comments in a README — they are architectural constraints the framework checks at install time.

1. Modules are sovereign. Each module owns its own data, its own API, its own lifecycle, and can run on its own deployment. Nothing else reaches into a module’s collections. Modules talk to each other only through declared SMI endpoints.
2. The contract is small and non-negotiable. Every module implements the same Standard Module Interface — same lifecycle hooks, same authorization surface, same event-publish rules. A module that lies about any of these fails the conformance suite.
3. Permissions flow through four layers, checked in three steps. Users, Companies, Workspaces, Modules. Every request runs Module access → Function access → Data access. Any check can deny. No module invents its own permission plumbing.
4. Every seam is a swappable adapter. Auth provider, database driver, cache/queue backend, deployment target — each is behind a small typed interface. Swap one, and every module comes along unchanged. Vendor choices are not baked into the code.

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 four layers, the three-check sequence, and the deliberate absences are documented at overview depth. The capability vocabulary, the effective-role computation ("highest rank wins"), the per-record attachment scope, and the full operator-composition model ship with Sovereign Platform.

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.

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 sections, method signatures, and the AuthAdapter interface are documented at overview depth. The full spec, worked examples, and the conformance suite ship with Sovereign Platform.

The Sovereign Platform ships as running code, not a whitepaper. Here is what is actually inside the repositories you receive on day one.

Every choice on this table is behind an adapter. You are not locked into MongoDB, Redis, Cloud Run, or Google — see §5.

The technology stack in §4 is the reference implementation. It is not the only implementation. Every seam between the framework and a vendor technology is a small typed interface. Write a new adapter, and every module comes along for free — no module code changes.

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

Four adapters ship with the platform:

Why this matters for due diligence. The most common reviewer objection to a small-vendor codebase is “this locks us into their stack.” The Sovereign Platform answers: no, the code you own doesn’t import Google, Mongo, or Redis directly — it imports adapters. Switching vendors is an adapter-sized project, not a rewrite.

What is not swappable: the four-layer permission model, the SMI contract, and the anti-pattern catalog. Those are the architecture. Everything else is a choice you can change later.

Sovereign deployment means each module can run on its own compute, in its own network, in its own region — independent of every other module. Coupling between modules is architectural (they share the SMI contract), not operational (they do not share a process, a container, or a database).

The reference deployment uses Google Cloud Run. Every module has its own Dockerfile, its own Cloud Run service, its own IAM identity, its own environment variables, and its own log stream. A push to main on any module's repository triggers a Cloud Build that produces a new image, pushes to Artifact Registry, and promotes it to Cloud Run. About three minutes end to end.

Sovereign deployment is not about cost or performance — it is about reviewability. An acquirer can point at any module and ask “can we run this by itself, on our infrastructure, in our region?” The answer is yes, because that is how it was already designed to run.

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. When one of these patterns lands in your codebase, you know exactly what to name and how to unwind it.

This page lists the twenty titles at overview depth. The full narratives — the mistake in code, why it breaks, the fix with diffs, and the exact warning sign — ship with Sovereign Platform.

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 registry fields and the four Settings sections are documented at overview depth. The full field reference, worked examples, per-record attachment-scope model, and implementation checklist ship with Sovereign Platform.

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.

What this means for how you build. A solid architecture is what makes vibe coding safe. When the module boundaries, permission model, and data ownership are enforced by the framework — not by a convention your team keeps in their heads — Cursor, Claude, and Copilot can generate code inside those boundaries without breaking them. Vibe-code the features, the UX, the workflows, the reports. The architecture underneath was designed to hold. That is the difference between a codebase that gets faster as it grows and one that gets slower.