rails-architecture
Skill665 starsChanged 6 months agoMITView on GitHub
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.
In this repository43 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude_37signals/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- accessibility-reviewSkill
- action-cable-patternsSkill
- active-storage-setupSkill
- api-versioningSkill
- authentication-flowSkill
- behavioral-guidelinesSkill
- caching-strategiesSkill
- code-reviewSkill
- codex-reviewSkill
- dependabot-reviewSkill
- extraction-timingSkill
- friction-reviewSkill
- i18n-patternsSkill
- mutation-testingSkill
- performance-optimizationSkill
- postgres-patternsSkill
- rails-architectureSkill
- rails-concernSkill
- security-auditSkill
- solid-queue-setupSkill
- accessibility-reviewSkill
- action-cable-patternsSkill
- active-storage-setupSkill
- api-versioningSkill
- authentication-flowSkill
- behavioral-guidelinesSkill
- caching-strategiesSkill
- code-reviewSkill
- codex-reviewSkill
- dependabot-reviewSkill
- extraction-timingSkill
- friction-reviewSkill
- i18n-patternsSkill
- mutation-testingSkill
- performance-optimizationSkill
- postgres-patternsSkill
- rails-concernSkill
- security-auditSkill
- solid-queue-setupSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 97
All services return a consistent Result object:
- Distinctive: line 142
Policy: - Add authorization rules (@policy-agent)
- Distinctive: line 143
Service: - Create for complex logic (@service-agent)
- Distinctive: line 144
Query: - Add for complex queries (@query-agent)
- Distinctive: line 145
Controller: - Keep it thin (@controller-agent)
- Distinctive: line 148
Mailer: - Add transactional emails (@mailer-agent)
- Distinctive: line 149
Job: - Add background processing (@job-agent)
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
| Situation | Keep It Simple | Don't Create |
| Simple CRUD (< 10 lines) | Keep in controller | Service object |
| Used only once | Inline the code | Abstraction |
| Simple query with 1-2 conditions | Model scope | Query object |
| Basic text formatting | Helper method | Presenter |
| Single model form | form_with model: | Form object |
| Simple partial without logic | Partial | ViewComponent |
When TO Abstract
| Signal | Action |
| Same code in 3+ places | Extract to concern/service |
| Controller action > 15 lines | Extract to service |
| Model > 300 lines | Extract concerns |
| Complex conditionals | Extract to policy/service |
| Query joins 3+ tables | Extract to query object |
| Form spans multiple models | Extract to form object |
See /extraction-timing skill for detailed extraction guidance.
Core Patterns
Skinny Controllers
# GOOD: Thin controller delegates to service
class OrdersController < ApplicationController
def create
result = Orders::CreateService.call(user: current_user, params: order_params)
if result.success?
redirect_to result.data, notice: t(".success")
else
flash.now[:alert] = result.error
render :new, status: :unprocessable_entity
end
end
endResult Objects for Services
All services return a consistent Result object:
Result = Data.define(:success, :data, :error) do
def success? = success
def failure? = !success
endMulti-Tenancy by Default
# GOOD: Scoped through account
def index
@events = current_account.events.recent
endRails 8 Specific Features
| Feature | Purpose | Skill/Agent |
| Authentication | has_secure_password generator | /authentication-flow |
| Background Jobs | Solid Queue (database-backed) | /solid-queue-setup, @job-agent |
| Real-time | Action Cable + Solid Cable | /action-cable-patterns |
| Caching | Solid Cache (database-backed) | /caching-strategies |
| Assets | Propshaft + Import Maps | (built-in) |
| Deployment | Kamal 2 + Thruster | (built-in) |
Testing Strategy by Layer
| Layer | Test Type | Focus |
| Model | Unit | Validations, scopes, methods |
| Service | Unit | Business logic, edge cases |
| Query | Unit | Query results, tenant isolation |
| Presenter | Unit | Formatting, HTML output |
| Controller | Request | Integration, HTTP flow |
| Component | Component | Rendering, variants |
| Policy | Unit | Authorization rules |
| System | E2E | Critical user paths |
New Feature Checklist
- Model - Define data structure (@migration-agent, @model-agent)
- Policy - Add authorization rules (@policy-agent)
- Service - Create for complex logic (@service-agent)
- Query - Add for complex queries (@query-agent)
- Controller - Keep it thin (@controller-agent)
- Presenter - Format for display (@presenter-agent)
- Component - Build reusable UI (@viewcomponent-agent)
- Mailer - Add transactional emails (@mailer-agent)
- Job - Add background processing (@job-agent)
References
- See layer-interactions.md for layer communication patterns
- See service-patterns.md for service object patterns
- See query-patterns.md for query object patterns
- See error-handling.md for error handling strategies
- See testing-strategy.md for comprehensive testing
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

