Creating Packages

Organize your app into feature and portal packages.

Goal

Domain code (models, policies, definitions, interactions) lives in feature packages. Web interfaces (controllers, views, routes, auth) live in portal packages. Both are Rails engines with Plutonium conventions on top.

Two types

Type	Purpose	Generator	Examples
Feature	Business logic	pu:pkg:package NAME	blogging, billing, inventory
Portal	Web interface	pu:pkg:portal NAME	admin_portal, customer_portal, public_portal

🚨 Don't mix the two. Feature packages own the domain code — models, interactions, policies/definitions for resources owned by that feature. Portal packages own the web surface — controllers, routes, auth, and portal-specific policy/definition overrides for resources they expose.

Feature package

1. Generate

rails g pu:pkg:package blogging

2. Structure

packages/blogging/
├── app/
│   ├── models/blogging/             # Blogging::Post
│   ├── definitions/blogging/        # Blogging::PostDefinition
│   ├── policies/blogging/           # Blogging::PostPolicy
│   └── interactions/blogging/       # Blogging::PublishPostInteraction
├── db/migrate/
└── lib/engine.rb

3. Create resources inside it

rails g pu:res:scaffold Blogging::Post title:string --dest=blogging
rails db:prepare

4. Expose it via a portal

rails g pu:res:conn Blogging::Post --dest=admin_portal

Portal package

1. Generate

rails g pu:pkg:portal admin --auth=user

Options:

• --auth=NAME — Rodauth account to authenticate with.
• --public — public access, no auth.
• --byo — bring your own auth.
• --scope=CLASS — entity class for multi-tenancy.

The generator mounts the engine for you — at /admin in this case, wrapped in constraints Rodauth::Rails.authenticate(:user) because you passed --auth=user. Open packages/admin_portal/config/routes.rb to see the generated mount.

2. Connect resources

rails g pu:res:conn Blogging::Post --dest=admin_portal

You can connect multiple resources in one command:

rails g pu:res:conn Blogging::Post Blogging::Comment --dest=admin_portal

See Reference › App › Portals for the full portal surface.

Auto-namespacing

Every file under app/<kind>/blogging/ resolves to Blogging::*:

• app/models/blogging/post.rb → Blogging::Post
• app/policies/blogging/post_policy.rb → Blogging::PostPolicy

Each feature package gets base classes — Blogging::ApplicationRecord, Blogging::ResourceRecord, Blogging::ResourcePolicy, Blogging::ResourceDefinition, Blogging::ResourceInteraction — that inherit from the main app's.

Cross-package references

rails g pu:res:scaffold Comment user:belongs_to blogging/post:belongs_to body:text --dest=comments

The blogging/post syntax expands to Blogging::Post.

When to use which

Feature package

When the code:

• Could be reused across multiple portals (admin and customer both edit Blogging::Post).
• Has no inherent UI / auth.
• You want isolated from other domains (billing shouldn't depend on blogging).

Portal package

When the code:

• Has a specific auth flow (admin vs customer vs public).
• Renders different views of the same underlying resources.
• Needs different policies / definitions per audience.

When NOT to make a package

For an app that doesn't need cross-portal sharing, just put resources in --dest=main_app. Packages add organization, not power.

Typical architecture

packages/
├── blogging/                # Feature: blog functionality
├── billing/                 # Feature: payments/invoicing
├── admin_portal/            # Portal: admin interface
└── customer_portal/         # Portal: customer dashboard

The portals expose the features. A single feature can be exposed by multiple portals — usually with different policies and definitions per portal.

Package loading

Generated by pu:core:install:

# config/packages.rb
Dir.glob(File.expand_path("../packages/**/lib/engine.rb", __dir__)) do |package|
  load package
end

Loaded from config/application.rb. Migrations from all packages are picked up by rails db:migrate automatically.

Per-portal overrides

# Definition — different fields per portal
class AdminPortal::PostDefinition < ::PostDefinition
  input :internal_notes, as: :text     # admins see this; customers don't
  scope :pending_review
end

# Policy — different rules per portal
class AdminPortal::PostPolicy < ::PostPolicy
  include AdminPortal::ResourcePolicy

  def destroy? = true
  def permitted_attributes_for_create = %i[title content featured internal_notes]
end

Common issues

• Class not loading — namespace must match the directory: app/models/blogging/post.rb MUST be Blogging::Post.
• Migration not running — package migrations are auto-included. If they aren't running, check config/packages.rb is loaded from application.rb.
• Cross-package association fails — use blogging/post:belongs_to in pu:res:scaffold, OR manually set class_name: "Blogging::Post" on the belongs_to.

Related

• Reference › App › Packages — full package surface
• Reference › App › Portals — portal-specific configuration
• Adding resources — pu:res:scaffold and pu:res:conn
• Authentication — portal auth setup