plutonium 0.50.0 → 0.52.0

data/docs/guides/multi-tenancy.md

@@ -1,48 +1,51 @@
 # Multi-tenancy
 
-This guide covers isolating data by organization, account, or other entity.
+Isolate data by organization, account, or any other "entity". Plutonium handles the URL strategy, query scoping, form injection, and `belongs_to` auto-detection automatically.
 
-## Overview
+## Goal
 
-Multi-tenancy means each tenant (organization, company, account) sees only their own data. Plutonium supports this through:
+Each tenant sees only their own records. Queries are filtered, forms inject the tenant on create, URLs include the tenant id, and policies receive the tenant for authorization.
 
-- **Entity Scoping** - Automatic query filtering via portal configuration
-- **Path or Custom Strategies** - Flexible entity resolution
-- **Policy Integration** - Authorization automatically respects tenancy
+## 🚨 Critical
 
-## Setting Up Multi-tenancy
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!` at runtime. Make sure `default_relation_scope(relation)` is called somewhere in the chain — explicitly here, or via `super` to a parent policy (e.g., a package base) that calls it.
+- **Always declare an association path from the model to the entity.** Direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope. If `associated_with` can't resolve, fix the **model**, not the policy.
+- **Compound uniqueness scoped to the tenant FK.** `validates :code, uniqueness: {scope: :organization_id}` — without this, uniqueness leaks across tenants.
 
-### 1. Create the Entity Model
+After login, users with memberships in multiple entities land on a workspace selector:
 
-```ruby
-# app/models/organization.rb
-class Organization < ApplicationRecord
-  include Plutonium::Resource::Record
+![Workspace selector after login](/images/guides/multi-tenancy-welcome.png)
 
-  has_many :users
-  has_many :posts
-end
+Picking one lands them on the entity-scoped dashboard — note the entity slug in the URL:
+
+![Tenant-scoped dashboard](/images/guides/multi-tenancy-dashboard.png)
+
+## Quickest path: `pu:saas:setup`
+
+```bash
+rails g pu:saas:setup --user Customer --entity Organization
 ```
 
-### 2. Add Entity Reference to Resources
+This **meta-generator** creates the user + entity + membership trio AND runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install` in one shot. The portal is fully wired for entity scoping.
 
-Resources must have an association path to the entity:
+See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup-pu-saas-setup).
 
-```ruby
-# Direct association (preferred)
-class Post < ResourceRecord
-  belongs_to :organization
-  belongs_to :user
-end
+## Manual setup
 
-# Through association
-class Comment < ResourceRecord
-  belongs_to :post
-  has_one :organization, through: :post
-end
+### 1. Create the entity model
+
+```bash
+rails g pu:res:scaffold Organization name:string:uniq slug:string:uniq --dest=main_app
+```
+
+### 2. Add the FK to each tenant-scoped resource
+
+```bash
+rails g pu:res:scaffold Post organization:belongs_to title:string content:text --dest=main_app
+rails db:migrate
 ```
 
-### 3. Configure the Portal Engine
+### 3. Scope the portal to the entity
 
 ```ruby
 # packages/customer_portal/lib/engine.rb
@@ -51,252 +54,186 @@ module CustomerPortal
     include Plutonium::Portal::Engine
 
     config.after_initialize do
-      # Path strategy - entity ID in URL
       scope_to_entity Organization, strategy: :path
     end
   end
 end
 ```
 
-Routes become: `/organizations/:organization_id/posts`
-
-## Scoping Strategies
-
-### Path Strategy (Default)
+Or pass `--scope=Organization` to `pu:pkg:portal` and the engine wires this automatically.
 
-Entity ID is included in the URL path:
+### 4. Mount the portal
 
 ```ruby
-config.after_initialize do
-  scope_to_entity Organization, strategy: :path
-end
+# config/routes.rb
+mount CustomerPortal::Engine, at: "/customer"
 ```
 
-The user must have access to the organization (via `associated_with` scope).
+URLs now include the entity id: `/customer/organizations/42/posts`.
 
-### Custom Strategy
-
-Define a method that returns the current entity:
-
-```ruby
-# packages/customer_portal/lib/engine.rb
-config.after_initialize do
-  scope_to_entity Organization, strategy: :current_organization
-end
-```
+### 5. Compound uniqueness
 
 ```ruby
-# packages/customer_portal/app/controllers/customer_portal/concerns/controller.rb
-module CustomerPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:user)
-
-      private
-
-      # Method name must match strategy
-      def current_organization
-        @current_organization ||= current_user.organization
-      end
-    end
-  end
+class Post < ResourceRecord
+  belongs_to :organization
+  validates :slug, uniqueness: {scope: :organization_id}
 end
 ```
 
-## How Entity Scoping Works
+🚨 Without the `scope:`, the same slug in different orgs would collide.
 
-### Automatic Query Filtering
+## Strategies
 
-All resource queries are automatically scoped via `associated_with`:
+### Path strategy (default)
 
 ```ruby
-# In a scoped portal
-Post.all  # Returns only current entity's posts
+scope_to_entity Organization, strategy: :path
+# → /organizations/:organization_id/posts
 ```
 
-### Helper Methods
-
-Inside controllers:
+### Custom param key
 
 ```ruby
-current_scoped_entity  # The current Organization/Account/etc.
-scoped_to_entity?      # true if scoping is active
-scoped_entity_class    # Organization (the entity class)
+scope_to_entity Organization, strategy: :path, param_key: :org_id
+# → /orgs/:org_id/posts
 ```
 
-### Model Requirements
-
-Models must have an association path to the scoped entity. Plutonium automatically resolves:
-
-1. **Direct belongs_to** - `Post belongs_to :organization`
-2. **Through association** - `Comment has_one :organization, through: :post`
-3. **Custom scope** - For complex cases, define a named scope:
+### Subdomain / session / custom
 
 ```ruby
-class AuditLog < ResourceRecord
-  # When automatic resolution fails, define this scope
-  scope :associated_with_organization, ->(org) {
-    joins(:user).where(users: { organization_id: org.id })
-  }
-end
+scope_to_entity Organization, strategy: :current_organization
 ```
 
-## User Membership Patterns
-
-### Single Organization per User
+Then implement the method on the portal's controller concern:
 
 ```ruby
-class User < ApplicationRecord
-  belongs_to :organization
-end
+module CustomerPortal::Concerns::Controller
+  extend ActiveSupport::Concern
+  include Plutonium::Portal::Controller
+
+  private
 
-# Custom strategy
-def current_organization
-  current_user.organization
+  def current_organization
+    @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
+  end
 end
 ```
 
-### Multiple Organizations per User
+## Three model shapes
 
-```ruby
-class User < ApplicationRecord
-  has_many :memberships
-  has_many :organizations, through: :memberships
-end
+How tenant scoping resolves depends on how the model relates to the entity. Three shapes, pick the lightest:
+
+### 1. Direct `belongs_to`
 
-# Custom strategy with session storage
-def current_organization
-  @current_organization ||=
-    current_user.organizations.find_by(id: session[:organization_id]) ||
-    current_user.organizations.first
+```ruby
+class Post < ResourceRecord
+  belongs_to :organization
 end
+# Post.associated_with(org) → Post.where(organization: org)
 ```
 
-### Organization Switcher
+Auto-detected. Use when the model naturally has a direct FK to the entity.
+
+### 2. Join table (`belongs_to` AND `belongs_to`)
 
 ```ruby
-class OrganizationSwitchController < ApplicationController
-  def update
-    org = current_user.organizations.find(params[:id])
-    session[:organization_id] = org.id
-    redirect_back(fallback_location: root_path)
-  end
+class Membership < ResourceRecord
+  belongs_to :user
+  belongs_to :organization   # auto-detected
 end
 ```
 
-## Policy Integration
-
-Entity scoping is automatic. The base `Plutonium::Resource::Policy` includes:
+### 3. Grandchild — `has_one :through`
 
 ```ruby
-relation_scope do |relation|
-  next relation unless entity_scope
-
-  relation.associated_with(entity_scope)
+class Post < ResourceRecord
+  belongs_to :user
+  has_one :organization, through: :user   # ← critical
 end
 ```
 
-The `entity_scope` context is automatically set to `current_scoped_entity`.
+Auto-detected via `reflect_on_all_associations`. Declaring `has_one :through` is the lightest fix when the path is two hops.
 
-### Additional Filtering
+Full mechanics: [Reference › Tenancy › Entity scoping › Three model shapes](/reference/tenancy/entity-scoping#three-model-shapes).
 
-Add role-based filtering on top of entity scoping:
+## Custom scope (when the path is polymorphic or needs SQL control)
 
 ```ruby
-class PostPolicy < ResourcePolicy
-  relation_scope do |relation|
-    relation = super(relation)  # Apply entity scoping first
-
-    if user.role == "viewer"
-      relation.where(published: true)
-    else
-      relation
-    end
-  end
+class Comment < ResourceRecord
+  scope :associated_with_organization, ->(org) {
+    joins(task: :project).where(projects: {organization_id: org.id})
+  }
 end
 ```
 
-## Subdomain-Based Tenancy
+Plutonium picks this up **before** trying association detection.
 
-Route to different organizations by subdomain:
-
-### Routes
+## Accessing the scoped entity
 
 ```ruby
-# config/routes.rb
-constraints subdomain: /[a-z]+/ do
-  mount CustomerPortal::Engine, at: "/"
-end
+# Controller / views
+current_scoped_entity
+scoped_to_entity?
+
+# Policy
+entity_scope
 ```
 
-### Custom Strategy
+## Policy filtering on top of default
 
 ```ruby
-# Engine configuration
-scope_to_entity Organization, strategy: :current_organization
-
-# Controller concern
-def current_organization
-  @current_organization ||=
-    Organization.find_by!(subdomain: request.subdomain)
+relation_scope do |relation|
+  default_relation_scope(relation).where(archived: false)
 end
 ```
 
-## Cross-Tenant Operations
+🚨 `default_relation_scope(relation)` must be called somewhere in the chain — otherwise the runtime verification raises. Calling it explicitly here is safest; `super` works only if the parent policy also calls it.
 
-Sometimes admins need to see all data:
+## Cross-tenant operations — super-admin portal
 
-### Super Admin Portal (No Scoping)
+Create a separate portal **without** `scope_to_entity`:
 
 ```ruby
-# packages/super_admin_portal/lib/engine.rb
 module SuperAdminPortal
   class Engine < Rails::Engine
     include Plutonium::Portal::Engine
-    # No scope_to_entity = sees everything
+    # No scope_to_entity — sees all tenants
   end
 end
 ```
 
-### Conditional Scoping
+This portal's policies see everything. Don't enable public signup here.
 
-```ruby
-# Custom strategy that returns nil for super admins
-def current_organization
-  return nil if current_user.super_admin?
-  current_user.organization
-end
-```
+## Multiple associations to the same entity
 
-When `current_scoped_entity` returns `nil`, scoping is bypassed.
+If a model has two `belongs_to` to the entity class (e.g. `Match belongs_to :home_team, :away_team`), Plutonium raises:
 
-## Data Isolation Patterns
-
-### Shared Database, Scoped Queries (Recommended)
+```
+Match has multiple associations to Competition::Team: home_team, away_team.
+Plutonium cannot auto-detect which one to use for entity scoping.
+```
 
-All tenants share tables, queries filter by entity association:
+Override on the controller:
 
 ```ruby
-scope_to_entity Organization, strategy: :path
+class MatchesController < ::ResourceController
+  private
+  def scoped_entity_association = :home_team
+end
 ```
 
-Pros:
-- Simple setup
-- Easy migrations
-- Efficient for many small tenants
-
-Cons:
-- Risk of data leakage if scoping fails
-- Complex queries for cross-tenant reports
-
-### Schema-Based Isolation
+## Common issues
 
-Each tenant has separate database schema. This requires additional setup beyond Plutonium's built-in scoping.
+- **`verify_default_relation_scope_applied!` raises** — your custom `relation_scope` doesn't call `default_relation_scope(relation)`. Fix by composing: `default_relation_scope(relation).where(...)`.
+- **`Could not resolve the association between 'Model' and 'Entity'`** — the model has no path to the entity. Fix on the **model** (declare `has_one :through` or a custom `associated_with_<entity>` scope). Never paper over with `where` in the policy.
+- **Records leak across tenants** — likely a missing compound-uniqueness scope on the model. Add `validates :code, uniqueness: {scope: :organization_id}`.
+- **Forms show the entity field anyway** — check `present_scoped_entity?` / `submit_scoped_entity?` on the controller (defaults are `false`).
+- **Want to bypass scoping in one place** — use `skip_default_relation_scope!` explicitly, NOT a silent `where` bypass.
 
 ## Related
 
-- [Authorization](./authorization)
-- [Creating Packages](./creating-packages)
-- [Authentication](./authentication)
+- [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — full surface
+- [Reference › Behavior › Policies](/reference/behavior/policies) — `relation_scope` syntax
+- [Reference › App › Portals](/reference/app/portals) — `scope_to_entity` engine config
+- [Nested resources](./nested-resources) — parent scoping (takes precedence over entity scoping)
+- [User invites](./user-invites) — invitation-based membership onboarding