sustainable-rails

Sustainable Rails

Design and review Rails applications for long-term sustainability.

Quick Start

Sustainable Rails organizes code to minimize carrying costs — the ongoing cost of keeping code working as requirements change. The core architecture:

┌─────────────────────────────────────────┐
│            BOUNDARY LAYER               │
│  Controllers, Jobs, Mailers, Rake Tasks │
│  (receive input, trigger logic, output) │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│           SERVICE LAYER                 │
│  app/services/ — Business Logic Classes │
│  (isolated, low fan-in, high churn OK)  │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│            MODEL LAYER                  │
│   Active Records — Database Access Only │
│   (high fan-in, must stay simple/stable)│
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│            DATABASE LAYER               │
│  PostgreSQL — Source of Truth            │
│  (constraints enforce correctness)      │
└─────────────────────────────────────────┘

Core Rule: Business logic does NOT go in Active Records. Keep high fan-in classes simple and stable.

What Would You Like To Do?

1. Review code changes — Run /sustainable:review for sustainability-focused review
2. Analyze codebase — Run /sustainable:analyze for full sustainability analysis
3. Plan feature implementation — I'll guide you using sustainable patterns
4. Apply specific pattern — I'll help with service layer, database design, testing, etc.

Core Principles

Sustainability = Changes Tomorrow Are As Easy As Changes Today

Three values in priority order:

1. Sustainability — code is easy to change over time
2. Consistency — team follows shared conventions
3. Quality — code is well-tested and correct

Opportunity Cost vs Carrying Cost

• Opportunity cost = not building the feature (revenue lost)
• Carrying cost = ongoing cost of maintaining the code (the real danger)
• High carrying costs compound over time and can make an app unmaintainable
• Cut scope, never cut quality — reduce features before reducing sustainability

The Fan-In Argument

Business logic is complex, has high churn, and therefore has more bugs. Classes used widely (high fan-in) amplify bug impact. Therefore:

• DO NOT put business logic in Active Records (high fan-in)
• DO put business logic in isolated service classes (low fan-in)
• Bugs in service classes are contained; bugs in models break everything

See Business Logic Separation.

Common Violations

Violation	Example	Fix
Business logic in model	Widget#purchase method with conditionals	Extract to WidgetPurchaser service class
Fat model	Model growing with every feature	Separate service per domain concept
Validation as data integrity	Relying on validates for correctness	Add database constraints (NOT NULL, CHECK, FK)
Complex controller	Business logic in actions	Delegate to service, controller is "configuration"
Callback abuse	after_commit :send_notification	Move side effects to service layer
Scopes as business logic	Complex scopes encoding domain rules	Move to service class methods
Active Job indirection	Using Active Job when you can use backend directly	Use Sidekiq/SolidQueue API directly

Pattern Catalog

Pattern	Location	Use When	Reference
Service Classes	app/services/	Any business logic beyond CRUD	service-layer-design.md
Rich Result Objects	Service return values	Service methods need to communicate outcomes	service-layer-design.md
Database Constraints	Migrations	Data must be correct regardless of code path	database.md
Thin Controllers	Controllers	HTTP handling only	controllers.md
Thin Models	Models	Database access + simple derived attributes	models-database-access.md
Boundary Classes	Jobs, Mailers, Rake	Receive input, delegate to services	boundary-classes.md
Canonical Routes	Routes	RESTful resources with only:	routes.md
Semantic HTML	Views	Build with meaningful tags, style with CSS	html-templates.md

"Where Should This Code Go?"

If you have...	Put it in...
Domain-specific logic (conditionals, rules, workflows)	Service class in app/services/
Database access patterns	Active Record class/scope method
Simple derived attribute from DB columns	Active Record instance method
HTTP request handling	Controller (keep it "configuration")
Parameter type conversion	Controller private method
Email formatting	Mailer (no business logic)
Deferred/fault-tolerant execution	Job that delegates to service
One-off or recurring automation	Rake task that delegates to service
Reusable markup	Partial with locals (not layouts)
Markup formatting	Helper (for small inline components)
Data correctness rules	Database constraints + validations for UX

Commands Reference

Command	Purpose
/sustainable:review	Review code changes for sustainability patterns
/sustainable:analyze	Full codebase sustainability analysis

Topic References

Topic	Reference
Sustainability Principles	sustainability-principles.md
Rails Architecture	rails-architecture.md
Business Logic Separation	business-logic-separation.md
Database Design	database.md
Service Layer Design	service-layer-design.md
Authentication & Authorization	auth.md
API Endpoints	api-endpoints.md
Operations & Observability	operations.md
Process & Workflows	process-workflows.md
CSS Strategy	css.md
JavaScript (Minimize)	javascript-minimization.md
JavaScript (Manage)	javascript-management.md
Monoliths & Microservices	monoliths-microservices.md
Technical Leadership	technical-leadership.md

Pattern References

Pattern	Reference
App Setup (bin/setup, bin/ci)	app-setup.md
Routes	routes.md
HTML Templates	html-templates.md
Helpers	helpers.md
View Testing	view-testing.md
Models (Database Access)	models-database-access.md
Models (Validations & Callbacks)	models-validations-callbacks.md
Controllers	controllers.md
Jobs	jobs.md
Boundary Classes	boundary-classes.md
End-to-End Example	end-to-end.md

Sustainability Checklist

Well-sustained code:

• Business logic is in service classes, not Active Records
• Active Records are for database access only (validations, associations, simple derived attributes)
• Database constraints enforce data correctness (NOT NULL, CHECK, FK, unique indexes)
• Validations exist for user experience, not data integrity
• Controllers are "configuration" — no business logic
• Callbacks limited to normalization (before_validation) and operational tracking
• Jobs delegate to service classes (no business logic in jobs)
• Mailers only format emails (no business logic)
• Routes use resources with only: — no unused routes
• Tests exist at appropriate levels (system tests for flows, unit tests for services)
• bin/setup, bin/run, and bin/ci scripts are maintained
• Dependencies updated regularly (monthly cadence)

Guidelines

• Boring is good — Write simple procedural code in services. No cleverness needed.
• Rails conventions are valuable — Use strong params, validations, resources routing. Don't fight Rails.
• Database is more important than code — Spend extra time on data modeling and constraints.
• Cut scope, not quality — If under pressure, build fewer features, not sloppier ones.
• Consistency over perfection — A consistent codebase is more sustainable than a brilliant but inconsistent one.
• Minimize JavaScript — Use server-rendered views by default. JS only when truly needed.
• Name things explicitly — WidgetEditingService#edit_widget over generic call methods.