Entity Scoping

Multi-tenant data isolation. Built on three cooperating pieces — portal, policy, model — that together ensure queries never leak across tenants.

🚨 Critical

Never bypass default_relation_scope. Overriding relation_scope with where(organization: ...) or manual joins to the entity triggers verify_default_relation_scope_applied! — make sure the chain ends up calling default_relation_scope(relation) somewhere (explicitly, or via super to a parent that calls it — Plutonium::Resource::Policy does).
Fix the MODEL, not the policy. If associated_with can't resolve, declare an association path (belongs_to, has_one :through) OR a custom associated_with_<entity> scope on the model. Never paper over it with a where in the policy.
Compound uniqueness scoped to the tenant FK — validates :code, uniqueness: {scope: :organization_id}.
Multiple associations to the same entity class require overriding scoped_entity_association on the controller.

The three pieces

Piece	Role	Where
Portal	Declares the entity class and resolution strategy	`scope_to_entity Organization, strategy: :path` in the engine
Policy	Applies the scope to every collection query	`default_relation_scope(relation)` (auto-called)
Model	Resolves the scope path	Direct `belongs_to`, `has_one :through`, or custom scope

default_relation_scope is enforced — if you override relation_scope without calling it, verify_default_relation_scope_applied! raises at runtime.

`associated_with` resolution

Model.associated_with(entity) resolves in this order:

Custom scope associated_with_<entity_name> (e.g. associated_with_organization) — highest priority, full SQL control.
Direct belongs_to to the entity class — WHERE <entity>_id = ?, most efficient.
has_one / has_one :through to the entity class — JOIN + WHERE, auto-detected via reflect_on_all_associations.
Reverse has_many from the entity — JOIN required, logs a warning (less efficient).

If none apply:

Could not resolve the association between 'Model' and 'Entity'

Fix on the model — either declare an association path (belongs_to, has_one :through) OR define a custom associated_with_<entity> scope. Never work around this by overriding relation_scope in the policy.

Three model shapes

The associated_with resolver handles three common shapes. Pick the lightest that fits.

Shape 1: Direct child (`belongs_to` the entity)

ruby

class Organization < ResourceRecord
  has_many :projects
end

class Project < ResourceRecord
  belongs_to :organization
end

Project.associated_with(org)
# => Project.where(organization: org)    — simple WHERE, most efficient

Auto-detected. Use this when the model naturally has a direct FK to the entity.

Shape 2: Join table (membership-style)

A join table linking users to entities, where the entity is reachable via one of the belongs_to:

ruby

class User < ResourceRecord
  has_many :memberships
  has_many :organizations, through: :memberships
end

class Organization < ResourceRecord
  has_many :memberships
  has_many :users, through: :memberships
end

class Membership < ResourceRecord
  belongs_to :user
  belongs_to :organization    # ← auto-detection finds :organization via belongs_to
end

Membership.associated_with(org)
# => Membership.where(organization: org)

If the join table is itself a parent and the scoped target is two hops away, add has_one :through:

ruby

class ProjectMember < ResourceRecord
  belongs_to :project
  belongs_to :user
  has_one :organization, through: :project   # ← enables auto-scoping
end

Now ProjectMember.associated_with(org) resolves via the has_one :through.

Shape 3: Grandchild (multi-hop via `has_one :through`)

ruby

class Organization < ResourceRecord
  has_many :projects
end

class Project < ResourceRecord
  belongs_to :organization
  has_many :tasks
end

class Task < ResourceRecord
  belongs_to :project
  has_one :organization, through: :project   # ← critical
end

# Deeper
class Comment < ResourceRecord
  belongs_to :task
  has_one :project, through: :task
  has_one :organization, through: :project   # ← enables auto-scoping at 3 hops
end

Task.associated_with(org) and Comment.associated_with(org) both auto-resolve.

Declaring has_one :through is the lightest fix

For grandchildren, the has_one :through on the model is all you need — associated_with finds it automatically. No policy override needed.

When to fall back to a custom scope

Use a custom associated_with_<entity> scope when:

The path is polymorphic.
The path needs conditional logic.
You want explicit SQL for performance (e.g. avoid a multi-join chain).

ruby

class Comment < ResourceRecord
  scope :associated_with_organization, ->(org) do
    joins(task: :project).where(projects: {organization_id: org.id})
  end
end

Plutonium picks this up before trying association detection.

`relation_scope` — safe override patterns

default_relation_scope(relation) does two things:

If a parent is present (nested resource), scopes via the parent association.
Otherwise, applies relation.associated_with(entity_scope).

Correct

ruby

# ✅ Best — don't override at all. The inherited scope already calls default_relation_scope.

# ✅ Extra filters on top
relation_scope do |relation|
  default_relation_scope(relation).where(archived: false)
end

# ✅ Role-based
relation_scope do |relation|
  relation = default_relation_scope(relation)
  user.admin? ? relation : relation.where(author: user)
end

Wrong

ruby

# ❌ Manually filtering by entity — bypasses default_relation_scope
relation_scope { |r| r.where(organization: current_scoped_entity) }

# ❌ Manual joins — same problem
relation_scope { |r| r.joins(:project).where(projects: {organization_id: current_scoped_entity.id}) }

# ❌ Missing default_relation_scope entirely — raises at runtime
relation_scope { |r| r.where(published: true) }

super works too

Plutonium::Resource::Policy's relation_scope block calls default_relation_scope(relation), so super(relation) from a subclass picks it up and the runtime check passes. Use whichever reads more clearly — super(relation).where(archived: false) and default_relation_scope(relation).where(archived: false) are equivalent when extending the framework base. Call default_relation_scope explicitly when you're not chaining via super (e.g. replacing the scope entirely).

Intentionally skipping the scope

Rare, but possible:

ruby

relation_scope do |relation|
  skip_default_relation_scope!
  relation
end

Before reaching for this, consider a separate, unscoped portal.

Portal entity strategies

The portal declares how the current entity is resolved from the request.

Path strategy (most common)

ruby

module CustomerPortal
  class Engine < Rails::Engine
    include Plutonium::Portal::Engine

    config.after_initialize do
      scope_to_entity Organization, strategy: :path
    end
  end
end

Routes become /<mount>/:organization_scoped/posts (resolving to /<mount>/42/posts at request time — the entity id is the first path segment after the mount). The portal extracts params[:organization_scoped] and loads the entity automatically.

Custom strategy (subdomain, session, etc.)

ruby

module CustomerPortal::Concerns::Controller
  extend ActiveSupport::Concern
  include Plutonium::Portal::Controller

  private

  def current_organization
    @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
  end
end

# Engine
scope_to_entity Organization, strategy: :current_organization

The strategy symbol must match a method name on the controller concern.

Custom param key

The default param_key derives from the entity class — <singular_route_key>_scoped (e.g. :organization_scoped) — to avoid colliding with a belongs_to :organization on child models when reading params[:organization]. The URL itself just uses the entity id as the first segment after the mount:

mount CustomerPortal::Engine, at: "/customer"
# → /customer/:organization_scoped/posts   (route definition)
# → /customer/42/posts                     (request URL)

Override when you want a different param name (e.g. for readability when reading params in custom controllers):

ruby

scope_to_entity Organization, strategy: :path, param_key: :org_id
# → params[:org_id] instead of params[:organization_scoped]

Accessing the scoped entity

ruby

# Controller / views
current_scoped_entity     # => current Organization
scoped_to_entity?         # => true / false

# Policy
entity_scope              # => current Organization

Cross-tenant operations

Super-admin portal — no scoping

Create a separate portal without scope_to_entity:

ruby

module SuperAdminPortal
  class Engine < Rails::Engine
    include Plutonium::Portal::Engine

    # No scope_to_entity — sees all tenants
  end
end

This portal's policies see everything. Don't enable public signup here.

Conditional scoping

ruby

class PostPolicy < ResourcePolicy
  relation_scope do |relation|
    return default_relation_scope(relation).where(category: :public) if user.guest?
    default_relation_scope(relation)
  end
end

Multiple associations to the same entity class

Example: Match belongs_to :home_team, :away_team both pointing at Team. Plutonium raises:

Match has multiple associations to Competition::Team: home_team, away_team.
Plutonium cannot auto-detect which one to use for entity scoping.
Override `scoped_entity_association` in your controller to specify the association.

Override on the controller:

ruby

class MatchesController < ::ResourceController
  private
  def scoped_entity_association = :home_team
end

`param_key` differs from association name

Plutonium matches by class, not param key:

ruby

# Portal config
scope_to_entity Competition::Team, param_key: :team

# Model — association name differs from param_key, but Plutonium finds by class
class Match < ApplicationRecord
  belongs_to :competition_team   # ← Plutonium auto-detects this
end

How the pieces fit together

An admin opens /organizations/42/projects.
Portal's scope_to_entity Organization, strategy: :path extracts 42, loads the Organization, sets current_scoped_entity.
The controller calls the policy. The policy's inherited relation_scope calls default_relation_scope(relation).
default_relation_scope has no parent (top-level nested-from-portal), so it calls relation.associated_with(current_scoped_entity).
Project.associated_with(org) resolves via the direct belongs_to :organization → Project.where(organization: org).
Only that organization's projects render. Records from other orgs are invisible.

Any model that can't be reached from the entity via these rules MUST declare a has_one :through or a custom scope.

Compound uniqueness

Always scope tenant-affecting uniqueness constraints:

ruby

class Property < ResourceRecord
  belongs_to :organization
  validates :code, uniqueness: {scope: :organization_id}    # ← critical
end

Without the scope, uniqueness leaks across tenants — Org A and Org B could collide on the same code.

Gotchas

Policy tries to filter by entity directly. Wrong — bypasses default_relation_scope. Add the association path to the model instead.
Multiple associations to the same entity class. Override scoped_entity_association.
param_key differs from association name. Fine — Plutonium finds the association by class.
Forgetting compound uniqueness. A unique constraint on :code alone leaks across tenants.
"Temporary" where bypass for debugging. Use skip_default_relation_scope! explicitly — never leave a where bypass in code.

Nested resources — parent scoping takes precedence over entity scoping
Invites — membership-based onboarding
Resource › Model — associated_with, model conventions
Behavior › Policy — relation_scope syntax
App › Portals — scope_to_entity engine config

Entity Scoping ​

🚨 Critical ​

The three pieces ​

associated_with resolution ​

Three model shapes ​

Shape 1: Direct child (belongs_to the entity) ​

Shape 2: Join table (membership-style) ​

Shape 3: Grandchild (multi-hop via has_one :through) ​

When to fall back to a custom scope ​

relation_scope — safe override patterns ​

Correct ​

Wrong ​

Intentionally skipping the scope ​

Portal entity strategies ​

Path strategy (most common) ​

Custom strategy (subdomain, session, etc.) ​

Custom param key ​

Accessing the scoped entity ​

Cross-tenant operations ​

Super-admin portal — no scoping ​

Conditional scoping ​

Multiple associations to the same entity class ​

param_key differs from association name ​

How the pieces fit together ​

Compound uniqueness ​

Gotchas ​

Related ​

Entity Scoping

🚨 Critical

The three pieces

`associated_with` resolution

Three model shapes

Shape 1: Direct child (`belongs_to` the entity)

Shape 2: Join table (membership-style)

Shape 3: Grandchild (multi-hop via `has_one :through`)

When to fall back to a custom scope

`relation_scope` — safe override patterns

Correct

Wrong

Intentionally skipping the scope

Portal entity strategies

Path strategy (most common)

Custom strategy (subdomain, session, etc.)

Custom param key

Accessing the scoped entity

Cross-tenant operations

Super-admin portal — no scoping

Conditional scoping

Multiple associations to the same entity class

`param_key` differs from association name

How the pieces fit together

Compound uniqueness

Gotchas

Related