DEV Community: Alireza Nourbakhsh

Guide on Rhino's Notifications Module

Alireza Nourbakhsh — Tue, 28 Oct 2025 21:09:21 +0000

About Rhino

Rhino is a framework built around Model-Driven Development (MDD), which is the core of its "vibe-coding" friendly approach. Instead of making you write repetitive boilerplate code, Rhino automatically generates secure API endpoints and routes directly from your data models. This allows you to just focus on defining your application's logic—like your Category, Blog, and BlogPost models—and trust the framework to handle the rest. This model-first philosophy is also naturally AI-friendly, as the well-defined models give AI tools the precise context they need to understand your intent and help you build features with minimal friction.

Overview

The Rhino Notifications module (rhino_project_notifications) is a Rails engine that wraps and extends the activity_notification gem (v2.3.3) to provide a complete notification system for Rhino-based applications. It provides both backend (Rails API) and frontend (React) components for managing user notifications.

This guide will first explain the base activity_notification gem capabilities, then detail what Rhino adds on top, and finally walk through setup and usage.

Part 1: The Base `activity_notification` Gem

Before understanding what Rhino adds, let's understand the underlying gem's capabilities.

Core Concepts

The activity_notification gem provides a flexible notification system with these key features:

1. Target (Receiver of Notifications)

Models that can receive notifications use acts_as_target:

class User < ApplicationRecord
  acts_as_target email: :email
end

This makes User a notification recipient and provides methods like:

user.notifications - All notifications
user.unopened_notification_count - Count of unread
user.notification_opened?(notification) - Check if opened
user.open_notification(notification) - Mark as read

2. Notifiable (Trigger of Notifications)

Models that trigger notifications use acts_as_notifiable:

class Comment < ApplicationRecord
  belongs_to :user
  belongs_to :post

  acts_as_notifiable :users,
    targets: ->(comment, key) { [comment.post.user] },
    group: :post,
    printable_name: ->(comment) { comment.body.truncate(30) }
end

3. Automatic Triggering

Notifications can be created automatically on model actions:

acts_as_notifiable :users,
  tracked: { only: [:create] }  # Auto-notify on creation

Or manually triggered:

comment.notify :users, key: "comment.create"

4. Grouping & Keys

Keys: String identifiers for notification types (e.g., "comment.create")
Grouping: Consolidate related notifications to prevent spam

acts_as_notifiable :users,
  group: :post,  # Group all comments on same post
  dependent_notifications: :update_group_and_destroy

Result: Multiple comments on the same post = 1 notification

5. Multiple Delivery Channels

Database (default) - Store in DB
Email - Send email notifications
Push - Web push notifications
ActionCable - Real-time WebSocket updates

Example: Rails App Without Rhino

Here's how you'd use activity_notification in a standard Rails app:

Step 1: Installation

bundle add activity_notification
rails generate activity_notification:install
rails db:migrate

Step 2: Configuration

# config/initializers/activity_notification.rb
ActivityNotification.configure do |config|
  config.email_enabled = true
  config.mailer = "ActivityNotification::Mailer"
  config.action_cable_enabled = true
  config.group_expiry_threshold = 5.minutes
end

Step 3: Models

# app/models/user.rb
class User < ApplicationRecord
  acts_as_target email: :email
  has_many :posts
  has_many :comments
end

# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :user
  belongs_to :post

  acts_as_notifiable :users,
    targets: ->(comment, key) { [comment.post.user] },
    notifier: :user,
    group: :post,
    printable_name: ->(comment) { comment.body.truncate(30) }
end

Step 4: Controller

# app/controllers/comments_controller.rb
class CommentsController < ApplicationController
  def create
    @comment = @post.comments.build(comment_params.merge(user: current_user))

    if @comment.save
      @comment.notify :users, key: "comment.create"
      redirect_to @post, notice: "Comment added!"
    else
      render :new
    end
  end
end

Step 5: Views

<!-- app/views/layouts/application.html.erb -->
<% current_user.notifications.unopened.each do |notification| %>
  <%= render_notification notification %>
<% end %>

<!-- app/views/activity_notification/notifications/_comment_create.html.erb -->
<%= link_to notification.notifier.name, user_path(notification.notifier) %>
commented on your
<%= link_to "post", post_path(notification.group) %>:
"<%= notification.notifiable.body.truncate(20) %>"

How Everything Connects

Step	What Happens
1	User adds a comment
2	`Comment` triggers `notify :users, key: "comment.create"`
3	Gem finds targets (post author via lambda)
4	Notification record created in DB
5	Delivery channels execute (email, ActionCable)
6	Author sees it in their notifications list
7	When viewed, `opened_at` timestamp is set

Key Features Summary

Feature	Description
Target (receiver)	`acts_as_target` in User
Notifiable (trigger)	`acts_as_notifiable` in Comment
Grouping	`group: :post` consolidates notifications
Key-based templates	`"comment.create"` maps to view partial
Channels	DB, email, ActionCable configurable
Persistence	Stored in `notifications` table
Read state	Managed via `.open!`, `.unopened`, `.opened`
Deletion	Manual (not automatic)

Part 2: What Rhino Adds to `activity_notification`

Rhino wraps activity_notification to provide a modern SPA architecture with these additions:

1. 🎯 RESTful JSON API Endpoints

Base gem: Provides HTML views and controllers for traditional Rails apps

Rhino adds: Automatic JSON API endpoints

# rhino/rhino-project/gems/rhino_project_notifications/config/routes.rb
Rails.application.routes.draw do
  scope Rhino.namespace do
    notify_to :users, api_mode: true, with_devise: :users
  end
end

Creates these endpoints:

GET /api/users/:user_id/notifications - List with filtering
GET /api/users/:user_id/notifications/:id - Show single
PUT /api/users/:user_id/notifications/:id/open - Mark as opened
POST /api/users/:user_id/notifications/open_all - Mark all opened
DELETE /api/users/:user_id/notifications/:id - Delete

JSON Response Format:

{
  "data": {
    "count": 3,
    "notifications": [
      {
        "id": 1,
        "notifiable_type": "Comment",
        "notifiable_id": 42,
        "notifiable_path": "/articles/10/comments/42",
        "printable_notifiable_name": "Comments on Article Title",
        "key": "comment.create",
        "group_owner_id": 10,
        "opened_at": null,
        "created_at": "2025-10-17T10:30:00.000Z",
        "parameters": {
          "article_id": 10
        }
      }
    ]
  }
}

Query Parameters:

filter=unopened - Only unopened notifications
filter=opened - Only opened notifications
filter=all - All notifications
limit=10 - Limit results

2. 🎨 Complete Frontend React Integration

Base gem: No frontend - you build your own

Rhino provides:

React Query Hooks

// rhino/rhino-project/packages/core/src/queries/notifications.js
import { useQuery, useMutation } from '@tanstack/react-query';
import { networkApiCall } from '../lib/networking';
import { useUserId } from '../hooks/auth';

const basePath = (userId) => `/api/users/${userId}/notifications`;
const fullPath = (userId, queryPath) => `${basePath(userId)}/${queryPath}`;

// Fetch unopened notifications
export const useNotifications = () => {
  const userId = useUserId();

  return useQuery({
    queryKey: ['notifications-index'],
    queryFn: ({ signal }) =>
      networkApiCall(fullPath(userId, '?filter=unopened&limit=10'), { signal }),
    enabled: !!userId
  });
};

// Mark all as opened
export const useNotificationsOpenAll = () => {
  const userId = useUserId();

  return useMutation({
    mutationFn: () =>
      networkApiCall(fullPath(userId, 'open_all'), { method: 'post' })
  });
};

// Mark single notification as opened
export const useNotificationsOpen = () => {
  const userId = useUserId();

  return useMutation({
    mutationFn: (notificationId) =>
      networkApiCall(fullPath(userId, `${notificationId}/open`), {
        method: 'put'
      })
  });
};

Pre-built NotificationMenu Component

// rhino/rhino-project/packages/core/src/components/app/NotificationMenu.js
import { NavLink } from 'react-router-dom';
import {
  Badge,
  DropdownItem,
  DropdownMenu,
  DropdownToggle,
  UncontrolledDropdown
} from 'reactstrap';
import { NavIcon } from '../icons';
import {
  useNotifications,
  useNotificationsOpen,
  useNotificationsOpenAll
} from '../../queries/notifications';

export const NotificationMenu = () => {
  const { data: { data: notifications } = {}, refetch } = useNotifications();
  const { mutate: openAll } = useNotificationsOpenAll();
  const { mutate: openOne } = useNotificationsOpen();
  const hasNotifications = notifications?.count > 0;

  const handleItemClick = (notificationId) =>
    openOne(notificationId, {
      onSuccess: () => refetch()
    });

  const handleClick = () => openAll({ onSuccess: () => refetch() });

  return (
    <UncontrolledDropdown nav direction="up">
      <DropdownToggle nav caret className="d-flex align-items-center text-light no-arrow">
        <NavIcon icon="bell" extraClass="flex-shrink-0" />
        <span className="d-block ms-2 overflow-hidden flex-grow-1">
          Notifications
        </span>
        {hasNotifications && <Badge pill>{notifications?.count}</Badge>}
      </DropdownToggle>

      <DropdownMenu dark end>
        {notifications?.notifications?.map((n) => (
          <DropdownItem
            key={n.id}
            tag={NavLink}
            to={n.notifiable_path}
            onClick={() => handleItemClick(n.id)}
          >
            {n.printable_notifiable_name}
          </DropdownItem>
        ))}

        {hasNotifications ? (
          <>
            <DropdownItem divider />
            <DropdownItem disabled={!hasNotifications} onClick={handleClick}>
              Mark All Opened
            </DropdownItem>
          </>
        ) : (
          <DropdownItem disabled>
            <em>No unread notifications</em>
          </DropdownItem>
        )}
      </DropdownMenu>
    </UncontrolledDropdown>
  );
};

3. 🔗 Rhino Routing Integration

Base gem: You manually define notifiable_path

Rhino adds: route_frontend helper that auto-generates hierarchical frontend paths

class Comment < ApplicationRecord
  belongs_to :article
  belongs_to :user

  # Rhino ownership integration
  rhino_owner :article
  rhino_references %i[article user]

  acts_as_notifiable :users,
    targets: ->(comment, _key) { [comment.article.user] },
    notifiable_path: :comment_notifiable_path,
    printable_name: ->(comment) { "Comment on #{comment.article.title}" }

  # Uses Rhino's routing helper
  def comment_notifiable_path
    route_frontend  # Auto-generates: "/123/articles/456/comments/789"
  end
end

The route_frontend method integrates with Rhino's ownership model (rhino_owner) to build hierarchical URLs based on your base owner (e.g., Organization).

4. 🚀 Simplified Installation

Base gem: Multiple manual steps

Rhino provides: One-command generator

rails generate rhino_notifications:install

This single command:

✅ Runs activity_notification:install (creates initializer)
✅ Runs activity_notification:migration (creates DB tables)
✅ Adds acts_as_target email: :email to User model

5. ⚙️ API-Optimized Defaults

Base gem defaults:

Email enabled by default
Subscriptions enabled by default
ActionCable optional

Rhino defaults (API-first):

# config/initializers/activity_notification.rb
config.email_enabled = false              # Disabled for API-only
config.subscription_enabled = false       # Disabled for simplicity
config.action_cable_enabled = false       # Disabled by default
config.action_cable_api_enabled = false   # Disabled by default

This creates a cleaner API-only setup without email/WebSocket complexity unless you explicitly enable them.

6. 🔐 Authorization Integration

The notify_to :users, with_devise: :users route configuration integrates with Rhino's authentication system to ensure users can only access their own notifications.

Comparison: Base Gem vs. Rhino

Feature	Base `activity_notification`	Rhino Addition
Model configuration	✅ `acts_as_target`, `acts_as_notifiable`	✅ Same (manual)
Grouping	✅ Yes	✅ Same
Notification keys	✅ Yes	✅ Same
Parameters	✅ Custom JSON data	✅ Same
HTML Views	✅ Provided	❌ Not used (API-only)
JSON API	⚠️ Basic (optional)	⭐️ Full RESTful API
Frontend	❌ Build your own	⭐️ React components + hooks
Routing Helper	❌ Manual	⭐️ `route_frontend` integration
Ownership Model	❌ None	⭐️ Rhino owner hierarchy
Installation	⚠️ Multiple steps	⭐️ One-command generator
Email Delivery	✅ Enabled by default	⚠️ Disabled by default
ActionCable	✅ Optional	⚠️ Disabled by default
Subscriptions	✅ Enabled by default	⚠️ Disabled by default

Part 3: Setup and Usage in a Rhino Project

Installation

Step 1: Run the Generator

rails generate rhino_notifications:install

This creates:

File 1: config/initializers/activity_notification.rb

Configuration for the notification system
Contains ~100+ configuration options
Rhino sets sensible API-first defaults

File 2: db/migrate/TIMESTAMP_create_activity_notification_tables.rb

Creates notifications table (stores all notifications)
Creates subscriptions table (for subscription management if enabled)

File 3: Modifies app/models/user.rb

Adds acts_as_target email: :email

Step 2: Run Migrations

rails db:migrate

This creates the database tables.

Database Schema

Notifications Table

create_table :notifications do |t|
  t.belongs_to :target,     polymorphic: true, index: true, null: false  # Who receives it (User)
  t.belongs_to :notifiable, polymorphic: true, index: true, null: false  # What it's about (Comment, etc.)
  t.string     :key,                                        null: false  # Notification type identifier
  t.belongs_to :group,      polymorphic: true, index: true              # Groups related notifications
  t.integer    :group_owner_id,                index: true              # Owner of notification group
  t.belongs_to :notifier,   polymorphic: true, index: true              # Who triggered it
  t.text       :parameters                                              # Custom data (JSON)
  t.datetime   :opened_at                                               # Read/unread tracking
  t.timestamps null: false
end

Key Fields:

target: Who receives the notification (polymorphic, typically User)
notifiable: What the notification is about (polymorphic, can be any model)
key: String identifier (e.g., "comment.create")
group: Optional grouping to consolidate related notifications
notifier: Who/what caused the notification
parameters: JSON text field for custom data
opened_at: NULL = unread, NOT NULL = read

Subscriptions Table

create_table :subscriptions do |t|
  t.belongs_to :target,     polymorphic: true, index: true, null: false
  t.string     :key,                           index: true, null: false
  t.boolean    :subscribing,                                null: false, default: true
  t.boolean    :subscribing_to_email,                       null: false, default: true
  t.datetime   :subscribed_at
  t.datetime   :unsubscribed_at
  t.datetime   :subscribed_to_email_at
  t.datetime   :unsubscribed_to_email_at
  t.text       :optional_targets
  t.timestamps null: false
end
add_index :subscriptions, [:target_type, :target_id, :key], unique: true

Configuration

After installation, review and customize:

# config/initializers/activity_notification.rb
ActivityNotification.configure do |config|
  config.enabled = true
  config.orm = :active_record
  config.notification_table_name = "notifications"
  config.subscription_table_name = "subscriptions"

  # Email notifications (disabled by default in Rhino)
  config.email_enabled = false

  # Subscription management (disabled by default in Rhino)
  config.subscription_enabled = false

  # ActionCable/WebSocket (disabled by default in Rhino)
  config.action_cable_enabled = false
  config.action_cable_api_enabled = false

  config.opened_index_limit = 10
end

Note on acts_as_target email: :email:
This parameter tells the gem where to find the email field (field mapping), NOT whether to send emails. The config.email_enabled = false is what actually disables email sending.

Model Configuration

Target Model (User)

The generator already configured this:

# app/models/user.rb
class User < Rhino::User
  acts_as_target email: :email

  # This provides methods:
  # - user.notifications
  # - user.notification_index(filter: 'unopened', limit: 10)
  # - user.unopened_notification_count
  # - user.notification_opened?(notification)
  # - user.open_notification(notification)
  # - user.open_all_notifications
end

Notifiable Models (Manual Configuration)

Configure any model that should trigger notifications:

# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :article
  belongs_to :user

  # Rhino ownership (if using organizations/multi-tenancy)
  rhino_owner :article
  rhino_references %i[article user]

  # Notification configuration
  acts_as_notifiable :users,
    # Who receives notifications (lambda returns array of Users)
    targets: ->(comment, _key) {
      ([comment.article.user] + comment.article.reload.commented_users.to_a).uniq
    },

    # Group notifications by article (prevents spam)
    group: :article,

    # Which actions trigger notifications
    tracked: { only: [:create] },  # or { except: [:update] }

    # How to handle deletion
    dependent_notifications: :update_group_and_destroy,
    # Options: :delete_all, :destroy, :restrict_with_error, :update_group_and_destroy

    # Frontend path (uses Rhino routing)
    notifiable_path: :comment_notifiable_path,

    # Display name
    printable_name: :comment_printable_name,

    # Enable real-time updates (if ActionCable enabled)
    action_cable_api_allowed: true,

    # Additional data to store
    parameters: { article_id: :article_id }

  # Method for frontend routing
  def comment_notifiable_path
    route_frontend  # Rhino helper
    # Returns: "/123/articles/456/comments/789"
  end

  # Method for display name
  def comment_printable_name
    "Comments on #{article.title}"
  end
end

Group Model (Optional)

If using grouping, mark the group model:

# app/models/article.rb
class Article < ApplicationRecord
  belongs_to :user
  has_many :comments, dependent: :destroy
  has_many :commented_users, through: :comments, source: :user

  rhino_owner_base  # If Article is your base owner
  rhino_references [:user]

  acts_as_notification_group  # Marks as a group model
end

Usage Patterns

1. Automatic Notification Creation

With tracked: { only: [:create] }, notifications are created automatically:

# In your controller - no explicit notification call needed!
def create
  @comment = @article.comments.build(comment_params.merge(user: current_user))

  if @comment.save
    # Notification automatically created via acts_as_notifiable
    redirect_to @article, notice: "Comment added!"
  else
    render :new
  end
end

2. Manual Notification Creation

You can also trigger notifications manually:

# Basic manual trigger
comment.notify_to(users)

# With options
comment.notify_to(
  users,
  key: 'custom.notification.key',
  parameters: { custom_field: 'value' }
)

# Notify single user
comment.notify_to(user)

3. Dynamic Notification Targets

Complex target logic in the lambda:

acts_as_notifiable :users,
  targets: ->(comment, key) {
    targets = []

    # Notify article author
    targets << comment.article.user

    # Notify other commenters
    targets += comment.article.comments.map(&:user)

    # Notify mentioned users (custom method)
    targets += comment.extract_mentions

    # Remove duplicates and commenter themselves
    (targets.uniq - [comment.user])
  }

4. Custom Parameters

Store additional context with notifications:

acts_as_notifiable :users,
  parameters: {
    article_id: :article_id,
    comment_count: ->(comment) { comment.article.comments.count },
    is_urgent: ->(comment) { comment.body.include?('URGENT') }
  }

# Access in frontend/API
notification.parameters['article_id']
notification.parameters['comment_count']
notification.parameters['is_urgent']

5. Notification Grouping

Prevent notification spam by grouping:

acts_as_notifiable :users,
  group: :article,
  dependent_notifications: :update_group_and_destroy

# Result: Multiple comments on same article = 1 notification
# The notification updates with latest comment info

Frontend Integration

Using the Pre-built Component

// In your Rhino app layout/navigation
import { NotificationMenu } from '@rhino-project/core';

function AppNavigation() {
  return (
    <nav>
      {/* Your other nav items */}
      <NotificationMenu />
    </nav>
  );
}

That's it! The component handles:

Fetching unopened notifications
Displaying count badge
Click-to-navigate to notification target
Mark as opened
Mark all as opened

Custom Frontend Implementation

If building your own frontend:

import { 
  useNotifications, 
  useNotificationsOpen 
} from '@rhino-project/core';

function CustomNotifications() {
  const { data: { data: notifications } = {}, refetch } = useNotifications();
  const { mutate: openOne } = useNotificationsOpen();

  const handleClick = (notificationId, path) => {
    openOne(notificationId, {
      onSuccess: () => {
        refetch();
        navigate(path);
      }
    });
  };

  return (
    <div>
      <h2>Notifications ({notifications?.count || 0})</h2>
      {notifications?.notifications?.map((n) => (
        <div key={n.id} onClick={() => handleClick(n.id, n.notifiable_path)}>
          {n.printable_notifiable_name}
        </div>
      ))}
    </div>
  );
}

API Endpoints

The following endpoints are automatically available:

List Notifications

GET /api/users/:user_id/notifications?filter=unopened&limit=10

Response:

{
  "data": {
    "count": 3,
    "notifications": [
      {
        "id": 1,
        "notifiable_type": "Comment",
        "notifiable_id": 42,
        "notifiable_path": "/articles/10/comments/42",
        "printable_notifiable_name": "Comments on Article Title",
        "key": "comment.create",
        "opened_at": null,
        "parameters": { "article_id": 10 }
      }
    ]
  }
}

Query Parameters:

filter=unopened (default) - Only unopened
filter=opened - Only opened
filter=all - All notifications
limit=10 - Limit results

Show Single Notification

GET /api/users/:user_id/notifications/:id

Mark as Opened

PUT /api/users/:user_id/notifications/:id/open

Mark All as Opened

POST /api/users/:user_id/notifications/open_all

Delete Notification

DELETE /api/users/:user_id/notifications/:id

Advanced Features (Optional)

These features are disabled by default but can be enabled:

Email Notifications

# config/initializers/activity_notification.rb
config.email_enabled = true
config.mailer_sender = 'notifications@yourapp.com'

# app/models/user.rb
acts_as_target email: :email, email_allowed: true

# app/models/comment.rb
acts_as_notifiable :users,
  email_allowed: true,
  notifier: :user,
  email_subject: ->(notification) { 
    "New comment on #{notification.notifiable.article.title}" 
  }

ActionCable Real-time Updates

# config/initializers/activity_notification.rb
config.action_cable_enabled = true
config.action_cable_api_enabled = true

# app/models/comment.rb
acts_as_notifiable :users,
  action_cable_api_allowed: true

# Frontend will receive real-time notification updates

Subscription Management

# config/initializers/activity_notification.rb
config.subscription_enabled = true

# Users can manage subscriptions
user.create_subscription(key: 'comment.create')
user.subscribe_to_email('comment.create')
user.unsubscribe('comment.create')

Testing

Example test for notification creation:

# test/models/comment_test.rb
require 'test_helper'

class CommentTest < ActiveSupport::TestCase
  test "creates notification for article author" do
    article = articles(:one)
    author = article.user

    assert_difference 'author.notifications.count', 1 do
      Comment.create!(
        article: article,
        user: users(:commenter),
        body: "Great article!"
      )
    end

    notification = author.notifications.last
    assert_equal 'Comment', notification.notifiable_type
    assert_nil notification.opened_at  # Unopened
  end

  test "groups multiple comments on same article" do
    article = articles(:one)
    author = article.user

    # First comment creates notification
    Comment.create!(
      article: article,
      user: users(:commenter),
      body: "First comment"
    )

    initial_count = author.notifications.count

    # Second comment updates existing notification (grouped)
    Comment.create!(
      article: article,
      user: users(:another_commenter),
      body: "Second comment"
    )

    # Count should be same (grouped)
    assert_equal initial_count, author.notifications.count
  end
end

Best Practices

Always define printable_name - Makes notifications readable in the UI
Always define notifiable_path - Enables click-through navigation
Use grouping for related notifications - Prevents notification spam
Be specific with targets lambda - Only notify relevant users
Use parameters for context - Store data needed for display/linking
Track only necessary actions - Don't over-notify users
Clean up old notifications - Archive or delete periodically
Test notification creation - Verify targets and data
Consider notification fatigue - Less is more
Use meaningful keys - Follow convention like "model.action"

Troubleshooting

Notifications Not Creating

Check:

✅ config.enabled = true in initializer
✅ acts_as_notifiable configured correctly
✅ targets lambda returns array of users
✅ Action is in tracked list (or manually calling notify_to)
✅ Database migration ran successfully

Frontend Not Showing Notifications

Check:

✅ User is authenticated (useUserId() returns value)
✅ API endpoint permissions correct
✅ Network tab for API errors
✅ NotificationMenu included in layout
✅ React Query devtools for cache status

Too Many Notifications

Solutions:

Use group option to consolidate
Adjust tracked to limit actions
Implement filtering logic in targets lambda
Consider digest/summary notifications

Performance Issues

Solutions:

Add database indexes on target_id, opened_at, notifiable_type
Limit query results with limit parameter
Use dependent_notifications: :delete_all for bulk operations
Archive old notifications to separate table
Use database queries instead of loading all notifications

Summary

The Rhino Notifications module provides:

✅ Polymorphic notifications (any model can notify any target)

✅ RESTful JSON API endpoints

✅ React Query hooks and UI components

✅ Notification grouping and consolidation

✅ Read/unread tracking

✅ Custom notification paths and display names

✅ Optional email and real-time support

✅ Subscription management (optional)

✅ Flexible target and parameter configuration

✅ Integration with Rhino's ownership model

✅ One-command installation

What you configure manually (same as base gem):

acts_as_notifiable on notifiable models
targets lambda defining who gets notified
group, tracked, parameters options
printable_name and notifiable_path methods
Notification keys and types

What Rhino provides automatically:

JSON API endpoints
Frontend components and hooks
Routing integration
Authentication/authorization
API-optimized defaults
Simplified installation

The system is production-ready and follows Rails/React best practices for maintainability and extensibility.

A Deep Dive into the Rhino Framework: Part 2 ( Authorization and the CrudController)

Alireza Nourbakhsh — Tue, 14 Oct 2025 21:15:10 +0000

In the first part of this series (link here), we introduced Rhino’s Model-Driven Development (MDD) approach, how this eases the vibecoding process, and explored how its dynamic routing system generates API endpoints directly from your models. This architecture allows for rapid development, but it requires an equally robust system to secure those endpoints. This post will dissect that next layer, breaking down how Rhino handles authentication (verifying a user's identity) and authorization (determining what that user can do).At the core of Rhino's security model are established and trusted Ruby gems: devise_token_auth for token-based authentication and pundit for fine-grained authorization. When the optional rhino_organizations module is installed for multi-tenancy, the rolify gem is introduced to enable sophisticated role-based access control (RBAC). We will explore how these components are seamlessly integrated within Rhino's default CrudController and CrudPolicy to provide a secure-by-default foundation for all your API resources, allowing you to build with confidence from the start.

The Foundation: Authentication with Devise

Before an application can determine what a user is allowed to do, it must first know who the user is. Rhino entrusts this critical function to devise_token_auth, a gem designed for handling token-based authentication in Rails APIs. It manages the entire authentication lifecycle, including user registration, secure sign-in, and session management using authentication tokens that are exchanged with the client on each request.From the perspective of the authorization system, Devise's most critical function is to provide a verified current_user object within the context of the controller for every authenticated API request. This object, representing the logged-in user, is the cornerstone upon which all subsequent permission checks and data scoping decisions are built. The Rhino::Authenticated concern, included in the CrudController, ensures that an unauthenticated request is rejected before any action is executed.

The Gatekeeper: Authorization with Pundit and Rolify

Once a user has been authenticated, Rhino must determine their permissions. This is the responsibility of the authorization layer, which is powered by the Pundit gem. Pundit provides a clean, object-oriented approach to managing permissions through dedicated "policy" classes.In a simple, single-user application, Pundit's authorization rules can be based directly on a user's ownership of a resource. However, for most real-world applications, a multi-tenant structure is required, where data is partitioned between different groups of users. This is where the rhino_organizations module becomes essential. When installed, it fundamentally shifts the ownership model:* Resources are owned by an Organization, not directly by an individual user. This aligns the data structure with a typical B2B SaaS model.

The rolify gem is utilized to manage a user's permissions within each organization. A User is connected to an Organization through a specific Role (e.g., admin, editor, viewer). Users can have different roles in different organizations.This structure provides a powerful and flexible foundation for Role-Based Access Control (RBAC), allowing permissions to be managed at the organization level rather than on a per-user basis, which is crucial for scalability and maintainability.

Secure by Default: The Principle of Least Privilege

Rhino's entire authorization model is built on a "deny by default" philosophy, a security best practice known as the Principle of Least Privilege (PoLP). This principle is first established in Rhino::BasePolicy, the abstract class from which all other policies in the framework inherit.By default, BasePolicy does two critical things:1) It defines all standard Pundit action methods (index?, show?, create?, update?, destroy?) and makes them return false.

2) It defines a Scope class with a resolve method that returns scope.none, an empty ActiveRecord relation.This means that out of the box, an unconfigured policy grants no permissions and allows a user to see no data. Permission must always be explicitly granted.This is where Rhino::CrudPolicy, the default policy for all resources, comes into play. It inherits from BasePolicy but overrides its restrictive defaults with an intelligent, role-based logic.* With the Organizations Module: The default behavior is collaborative. A User who has been assigned an admin role within an Organization is granted full CRUD permissions on all resources owned by that organization. Furthermore, any user who is simply a member of that organization is granted viewer permissions. This means if two users are in the same organization, they can both list and view the organization's blogs, regardless of who created them. This provides a sensible starting point for team-based applications.

Without the Organizations Module: In a simpler setup, the User who is designated as the rhino_owner_base of a resource hierarchy is granted full CRUD permissions.

Tying It All Together: The `Rhino::CrudController` in Action

The Rhino::CrudController is the workhorse that exposes the standard RESTful API endpoints (index, show, create, update, destroy) for a given resource. It is designed to be lean and highly effective, seamlessly integrating Devise, Pundit, and Rolify to enforce the authorization rules defined in the policies. Every action within the controller is rigorously protected by Pundit. # rhino/crud_controller.rb

    module Rhino
      class CrudController < BaseController
        include Rhino::Authenticated
        include Rhino::Permit

        # Confirm we are calling authorize and scope correctly
        after_action :verify_authorized
        after_action :verify_policy_scoped, only: %i[index show]

        # ... controller actions ...
      end
    end

Before we even get to the actions, notice the Pundit safety nets:* after_action :verify_authorized: This ensures that the authorize method is called in every controller action. If you forget to authorize an action, Pundit will raise an error, preventing you from accidentally creating an insecure endpoint.

after_action :verify_policy_scoped: This applies only to actions that return collections of data, like index. It ensures that you have used policy_scope to filter the data, preventing accidental data leaks.Let's examine the update action to see how these pieces come together: # rhino/crud_controller.rb

    def update
      @model = authorize find_resource
      @model.update!(permit_and_transform)

      permit_and_render
    end

This compact code performs a sequence of critical security and data-handling steps:

1) find_resource: This private helper method retrieves the specific record from the database based on the id in the URL parameters.

2) authorize @model: This is the core authorization check. Pundit is invoked here. It automatically infers that it should look for a policy corresponding to the @model's class (e.g., BlogPolicy). Since one likely doesn't exist, it falls back to the default, Rhino::CrudPolicy. It then calls the update? method on an instance of that policy, passing in the current_user and the @model record.

3) permit_and_transform: If authorization succeeds, this method from the Rhino::Permit concern is called. It consults the same policy to get a list of attributes that are permitted for the update action and sanitizes the incoming parameters, ensuring that a user cannot update fields they are not supposed to.

4) @model.update!(...): The model is updated with the sanitized parameters.

5) permit_and_render: Finally, the updated record is serialized back to JSON, again using the policy to determine which attributes are safe to show, and sent as the response.

The `CrudPolicy` as a Dispatcher

The most elegant part of this design is that CrudPolicy does not contain the final authorization logic itself. Instead, it acts as a dispatcher. Its primary job is to determine the user's role and then delegate the authorization check to a more specific role-based policy.Let's look at the check_action helper method within CrudPolicy, which is called by methods like update?: # rhino/crud_policy.rb

    def check_action(action)
      # For each role the user has for this record...
      Rhino.base_owner.roles_for_auth(auth_owner, record).each do |role, _base_owner_array|
        # Find the policy for that role (e.g., AdminPolicy)
        policy_class = Rhino::PolicyHelper.find_policy(role, record)
        next unless policy_class

        # If that role-policy allows the action, authorize immediately.
        return true if policy_class.new(auth_owner, record).send(action)
      end

      # If no role granted permission, deny.
      false
    end

This method is a clear illustration of the dispatcher pattern:1) roles_for_auth: It first asks the system, "What roles does this auth_owner (the current_user) have in the organization that owns this record?" This might return { "admin" => [Organization(id:1)] }.

2) find_policy: For each role found (e.g., "admin"), it looks up the corresponding policy class (e.g., AdminPolicy). Rhino has a convention for this: it will first look for a highly specific policy like AdminBlogPolicy, and if not found, fall back to the general AdminPolicy.

3) send(action): It then instantiates that specific role-policy and calls the original action method (e.g., update?) on it.

4) First true Wins: The moment any role-policy returns true, the CrudPolicy short-circuits and grants access. If it checks all roles and none grant access, it returns false.This design is powerful because it decouples the generic controller from the specific business logic. The CrudController doesn't need to know anything about admins, editors, or viewers. It only needs to know how to talk to the CrudPolicy, which handles the routing of the authorization query.

Applying the Dispatcher Pattern to Data Scoping

The same dispatcher pattern is applied to data scoping, which is arguably even more critical for preventing data leaks in a multi-tenant system. This logic resides in the nested Scope class inside CrudPolicy.When the CrudController's index action calls policy_scope(klass), Pundit invokes the resolve method on CrudPolicy::Scope. # rhino/crud_policy.rb

    class Scope < ::Rhino::BasePolicy::Scope
      def resolve
        role_scopes = []

        # Get every role for the auth owner across all their orgs
        Rhino.base_owner.roles_for_auth(auth_owner).each do |role, base_owner_array|
          base_owner_array.each do |base_owner|
            # Find the scope class for that role (e.g., AdminPolicy::Scope)
            scope_class = Rhino::PolicyHelper.find_policy_scope(role, scope)
            next unless scope_class

            # Instantiate the role's scope and get its resolved relation
            scope_instance = scope_class.new(auth_owner, scope)
            resolved_scope = scope_instance.resolve

            # Add the SQL for this specific role and organization to our list
            role_scopes << resolved_scope.where(tnpk(Rhino.base_owner) => base_owner.id)
          end
        end

        return scope.none unless role_scopes.present?

        # Combine all the individual SQL queries into one using UNION
        scope.where("#{tnpk(scope)} in (#{role_scopes.map(&:to_sql).join(' UNION ')})")
      end
      # ...
    end

The logic is analogous to the action check but operates on collections of data:

1) It iterates through every role the user has across all their organizations.

2) For each role in each organization, it finds the corresponding policy scope (e.g., AdminPolicy::Scope, ViewerPolicy::Scope).

3) It calls resolve on that specific scope. AdminPolicy::Scope might return scope.all (can see everything in the org), while a hypothetical AuthorPolicy::Scope might return scope.where(user: auth_owner) (can only see their own posts).

4) It collects the SQL query for each of these resolved scopes.

5) Finally, it combines all the individual SQL queries into a single, efficient database query using UNION. This returns a single ActiveRecord::Relation containing every record the user is permitted to see across all their roles and organizations, which is then passed back to the controller.

Conclusion

The Rhino framework provides a layered, secure, and highly scalable architecture for API authorization. By composing the strengths of Devise for authentication, Pundit for authorization policies, and Rolify for role management, it creates a robust system that is secure by default. The CrudController and CrudPolicy act as the central nervous system, applying these security principles consistently to every resource you define. This elegant abstraction means developers can build feature-rich, multi-tenant applications with minimal boilerplate, focusing on their unique business logic while trusting that the foundation is secure. You only need to create a custom policy when the default "admin," "editor," and "viewer" roles are not sufficient for your needs.In our next post, we will dive deeper into customizing Rhino's behavior by overriding the default policies and exploring the various configuration options available on the model objects themselves.