Rails Architecture Patterns

Architectural planning frameworks and decision guidance. Coordinate across domain skills and agents.

See patterns.md for detailed decision frameworks and profile-aware anti-pattern fixes.

Stack Profile Awareness

Before recommending patterns, determine the project's stack profile. See rails-stack-profiles for detection logic.

Available Domain Skills and Agents

Quick Decision Matrix

Implementation Order

For a typical feature:

1. Migration + Model     (rails-model)
2. Routes + Controller   (rails-controller or rails-api)
3. Views or Serializer   (rails-views or rails-api)
4. Service objects        (rails-service) -- if complex logic
5. Background jobs        (rails-jobs) -- if async work needed
6. Tests                  (rails-testing-patterns)

Architecture Health Checks

Universal (all profiles):

• No business logic in controllers or views
• Controllers have 7 or fewer actions
• No N+1 queries (check with Bullet gem)
• Background jobs are idempotent
• Test coverage on critical paths
• No circular dependencies between models

Omakase:

• Models decomposed via concerns (not monolithic god models)
• Callbacks are simple and predictable (data integrity, not workflows)
• Using Rails defaults (Solid Queue, etc.) where possible

Service-oriented:

• Models under 200 lines (extract services if larger)
• All external API calls go through service objects
• Service objects have single responsibility
• Result pattern used consistently

API-first:

• All responses use serializers (never raw ActiveRecord)
• API versioned from day one
• Authentication is token-based
• Error responses follow consistent envelope format

Output Format

## Architecture Plan: [feature_name]

**Detected Profile:** [omakase | service-oriented | api-first]
**Layers Involved:** Models, Controllers, Services, Tests

**Implementation Steps:**
1. [step] -- delegate to [skill/agent]
2. ...

**Design Decisions:**
- [decision]: [rationale]

**Risks:**
- [risk]: [mitigation]