SOLID Ruby - Modular Architecture

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

• fuse-ai-pilot:explore-codebase - Analyze existing architecture

• fuse-ai-pilot:research-expert - Verify Ruby/Rails docs via Context7

• fuse-ai-pilot:sniper - Post-implementation validation

DRY - Reuse Before Creating (MANDATORY)

Before writing ANY new code:

• Grep the codebase for similar modules, services, or logic

• Check shared locations: app/modules/core/services/ , app/modules/core/contracts/

• If similar code exists -> extend/reuse instead of duplicate

• If code will be used by 2+ features -> create it in app/modules/core/

Architecture (Modules MANDATORY)

Layer Location Max Lines

Controllers app/modules/[feature]/controllers/

50

Services app/modules/[feature]/services/

100

Repositories app/modules/[feature]/repositories/

100

Contracts app/modules/[feature]/contracts/

30

Models app/modules/[feature]/models/

50

Shared app/modules/core/{services,contracts,concerns}/

NEVER use flat app/ structure - always app/modules/[feature]/

Critical Rules (MANDATORY)

Rule Value

File limit 100 lines (split at 90)

Controllers < 50 lines, delegate to services

Contracts contracts/ directory ONLY (duck typing modules)

YARD doc Every public method documented

Frozen string

frozen_string_literal: true

in every file

Concerns Use for shared behavior (like interfaces)

Reference Guide

Concepts

Topic Reference When to consult

SOLID Overview solid-principles.md Quick reference

SRP single-responsibility.md Fat classes

OCP open-closed.md Adding strategies

LSP liskov-substitution.md Contracts

ISP interface-segregation.md Fat modules

DIP dependency-inversion.md Injection

Architecture architecture-patterns.md Modular Rails

Templates

Template When to use

module.md Feature module structure

service.md Business logic service

contract.md Duck typing contracts

model.md Active Record model

error.md Custom exceptions

test.md RSpec tests

Forbidden

Anti-Pattern Fix

Files > 100 lines Split at 90

Business logic in models Extract to service

Fat controllers Delegate to services

Flat app/ structure Use app/modules/[feature]/

God classes Split by responsibility