rails-architecture

Guide Rails 8 code organization across controllers, services, queries, and views.

Updated Nov 1, 2025
One-click install
npx skills add https://github.com/nschneble/rails-superstack --skill rails-architecture-nschneble
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: rails-architecture
Source: https://github.com/nschneble/rails-superstack/tree/main/.agents/skills/rails-architecture
Command: npx skills add https://github.com/nschneble/rails-superstack --skill rails-architecture-nschneble

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Architects of Rails 8 apps often struggle with where to place code, how to choose between patterns, and how to keep the codebase maintainable as the project grows. This guide clarifies responsibilities and patterns to use across controllers, services, queries, models, presenters, policies, jobs, mailers, and views.

Core Features & Use Cases

  • Layered architecture guidance for Rails 8 (Controller, Model, Service, Query, Presenter, Policy, Job, Form, Mailer, Channel) with clear responsibilities.
  • Decision trees and patterns to help decide where to place business logic, how to compose services and queries, and how to structure feature architecture.
  • Comprehensive patterns for testing, multi-tenancy, and layer interactions to improve maintainability and evolution of large Rails apps.

Quick Start

Provide a high-level Rails 8 architecture plan for organizing controllers, services, queries, models, and views in a maintainable, scalable pattern.

Frequently Asked Questions about rails-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I organize business logic in Rails 8 to keep the codebase maintainable?

Organize Rails 8 business logic using a layered architecture with clear responsibilities across controllers, services, queries, models, and presenters. This structure isolates domain logic into distinct layers, preventing fat controllers and models as the application grows.

What is the best way to structure service objects and query objects in a Rails application?

Structure service objects to encapsulate business actions and query objects to isolate database retrieval logic. Composing these patterns in Rails separates persistence concerns from workflows, yielding cleaner, testable, and more maintainable application layers.

When should I use presenters and policies instead of helpers in Rails?

Use presenters and policies instead of helpers when you need to encapsulate view-specific display logic and authorization rules. This layered approach assigns clear responsibilities to UI components, preventing logic leakage into views and keeping presentation code maintainable.

How do I structure a multi-tenant Rails 8 application with clear architectural patterns?

Structure multi-tenant Rails 8 applications by applying consistent layer interactions across services, queries, and models. Architectural guidance for multi-tenancy ensures tenant isolation is handled systematically within the correct layers rather than scattered throughout the codebase.

Where do I put business logic in Rails when it does not belong in the model?

Place business logic that does not fit cleanly in the model into service objects or form objects. Rails architecture decision trees guide placing workflows, validations, and interactions into appropriate layers to maintain strict separation of concerns.

What testing strategies work best for layered Rails architecture with services and queries?

Test layered Rails architecture by isolating tests for services, queries, and presenters according to their specific layer responsibilities. Comprehensive patterns for testing ensure each architectural layer is validated independently, improving overall application maintainability and reliability.