# Rails Architecture

Guides modern Rails 8 code architecture decisions and patterns.

- Repository: https://github.com/ThibautBaissac/rails_ai_agents (671 stars)
- Category: Design
- License: MIT
- Last updated: 2026-06-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ThibautBaissac/rails_ai_agents --skill rails-architecture -g -a claude-code -y`
Codex: `npx skills add ThibautBaissac/rails_ai_agents --skill rails-architecture -g -a codex -y`
Cursor: `npx skills add ThibautBaissac/rails_ai_agents --skill rails-architecture -g -a cursor -y`
Gemini CLI: `npx skills add ThibautBaissac/rails_ai_agents --skill rails-architecture -g -a gemini-cli -y`

## Description

Guides modern Rails 8 code architecture decisions and patterns. Use when deciding where to put code, choosing between patterns (service objects vs concerns vs query objects), designing feature architecture, refactoring for better organization, or when user mentions architecture, code organization, design patterns, or layered design. WHEN NOT: Implementing specific patterns (use specialist agents like service-agent or query-agent), writing tests, or debugging runtime errors.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Modern Rails 8 Architecture Patterns

## Architecture Decision Tree

```
Where should this code go?
|
+- View/display formatting?       -> Presenter (@presenter-agent)
+- Complex business logic?        -> Service Object (@service-agent)
+- Complex database query?        -> Query Object (@query-agent)
+- Shared behavior across models? -> Concern (/rails-concern skill)
+- Authorization logic?           -> Policy (@policy-agent)
+- Reusable UI with logic?        -> ViewComponent (@viewcomponent-agent)
+- Async/background work?         -> Job (@job-agent, /solid-queue-setup skill)
+- Complex form (multi-model)?    -> Form Object (@form-agent)
+- Transactional email?           -> Mailer (@mailer-agent)
+- Real-time/WebSocket?           -> Channel (/action-cable-patterns skill)
+- Data validation only?          -> Model (@model-agent)
+- HTTP request/response only?    -> Controller (@controller-agent)
```

## Layer Responsibilities

| Layer | Responsibility | Should NOT contain |
|-------|---------------|-------------------|
| **Controller** | HTTP, params, response | Business logic, queries |
| **Model** | Data, validations, relations | Display logic, HTTP |
| **Service** | Business logic, orchestration | HTTP, display logic |
| **Query** | Complex database queries | Business logic |
| **Presenter** | View formatting, badges | Business logic, queries |
| **Policy** | Authorization rules | Business logic |
| **Component** | Reusable UI encapsulation | Business logic |
| **Job** | Async processing | HTTP, display logic |
| **Form** | Complex form handling | Persistence logic |
| **Mailer** | Email composition | Business logic |
| **Channel** | WebSocket communication | Business logic |

## When NOT to Abstract

The rest: https://github.com/ThibautBaissac/rails_ai_agents/blob/HEAD/.claude/skills/rails-architecture/SKILL.md