Plutonium

Plutonium Development Guide

Read this first when working on a Plutonium application.

Core Rules

1. Always use generators - Never manually create resources, packages, or portals
2. Check relevant skills first - Each concept has a dedicated skill with details
3. Definitions over controllers - UI customization belongs in definitions, not controllers
4. Policies for authorization - All permission logic goes in policies

Key Generators

rails g pu:res:scaffold Post title:string --dest=main_app    # Create resource
rails g pu:res:conn Post --dest=admin_portal                 # Connect to portal
rails g pu:pkg:package blogging                              # Create feature package
rails g pu:pkg:portal admin                                  # Create portal

Always specify --dest to avoid interactive prompts.

Resource Architecture

A resource is four layers working together for full CRUD with minimal code:

┌─────────────────────────────────────────────────────────────────┐
│                           Resource                              │
├─────────────────────────────────────────────────────────────────┤
│  Model          │  Definition      │  Policy        │ Controller│
│  (WHAT it is)   │  (HOW it looks)  │  (WHO can act) │ (HOW it   │
│                 │                  │                │  responds) │
├─────────────────────────────────────────────────────────────────┤
│  - attributes   │  - field types   │  - permissions │ - CRUD    │
│  - associations │  - inputs/forms  │  - scoping     │ - redirects│
│  - validations  │  - displays      │  - attributes  │ - params  │
│  - scopes       │  - actions       │                │           │
│  - callbacks    │  - filters       │                │           │
└─────────────────────────────────────────────────────────────────┘

Auto-Detection

Plutonium automatically detects from your model:

• All database columns with appropriate field types
• Associations (belongs_to, has_one, has_many)
• Attachments (Active Storage)
• Enums

You only need to declare when overriding defaults.

Creating Resources

New Resources (from scratch)

rails g pu:res:scaffold Post user:belongs_to title:string 'content:text?' published:boolean --dest=main_app

See plutonium-create-resource skill for full generator options.

From Existing Models

1. Include Plutonium::Resource::Record in your model (or inherit from a class that does)
2. Generate supporting files: rails g pu:res:scaffold Post --no-migration
3. Connect to a portal: rails g pu:res:conn Post --dest=admin_portal

Connecting to Portals

Resources must be connected to a portal to be accessible:

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

See plutonium-portal skill for portal details.

Portal-Specific Customization

Each portal can override the base definition, policy, and controller:

# Admin portal sees more
class AdminPortal::PostDefinition < ::PostDefinition
  scope :draft
  scope :pending_review
  action :feature, interaction: FeaturePostInteraction
end

Workflow Summary

1. Generate - rails g pu:res:scaffold Model attributes... --dest=main_app
2. Migrate - rails db:migrate
3. Connect - rails g pu:res:conn Model --dest=portal_name
4. Customize - Edit definition/policy as needed

Skill Reference

Converted and distributed by TomeVault — claim your Tome and manage your conversions.