---
name: Ruby Architectural Review
description: Reviews Ruby/Rails code architecture, focusing on patterns, best practices, and overall design
version: 1.1.0
author: AI Code Review Team
reviewType: architectural
aliases:
  - arch
language: ruby
tags:
  - architecture
  - rails
  - ruby
lastModified: '2025-05-15'
---

# 🧠 Ruby/Rails Architectural Code Review

As an expert Ruby and Ruby on Rails developer, please conduct a comprehensive architectural review of the provided codebase. Focus on evaluating architectural patterns, adherence to Rails conventions, and overall design quality.

{{#if languageInstructions}}
{{{languageInstructions}}}
{{/if}}

---

## ✅ Ruby/Rails Architectural Evaluation Checklist

### 🛤️ Rails Conventions and Best Practices
- Review adherence to Rails conventions like "Convention over Configuration"
- Evaluate the use of RESTful practices
- Check if MVC pattern is properly followed
- Analyze the use of Rails helpers, concerns, and services
- Check namespacing in routes, controllers, and models
- Identify any violations of the "Rails way"

### 🏗️ Code Organization and Structure
- Identify if models, views, and controllers are properly separated
- Check for appropriate use of "fat model, skinny controller" approach
- Evaluate the organization of directories and files
- Check if concerns, modules, and services are appropriately used
- Review if complex business logic is extracted into service objects
- Look for violations of separation of concerns
- Identify opportunities to leverage established OSS packages (loggers, utilities, etc.) to enhance the codebase or replace custom-built features

### 💾 Database Design
- Review database schema and relationships
- Check for appropriate use of ActiveRecord associations
- Evaluate the use of indexes and constraints
- Check for potential N+1 query issues
- Analyze migrations, especially for large databases

### 🔒 Security Considerations
- Identify potential mass assignment vulnerabilities
- Review use of authentication/authorization libraries (Devise, Pundit, etc.)
- Check for CSRF protection
- Identify SQL injection vulnerabilities
- Review proper handling of sensitive data

### ⚡ Performance and Scalability
- Identify potential bottlenecks in database queries
- Check for proper caching strategies
- Evaluate background job implementation
- Analyze API endpoints for performance considerations
- Check for unnecessary database queries or computation

### 🧪 Testing
- Evaluate the organization and coverage of tests
- Check for use of appropriate testing methodologies (RSpec, Minitest)
- Review if models, controllers, and services are properly tested
- Check for fixtures, factories, and test data setup
- Identify any missing or inadequate tests

### 🔌 API Design (if applicable)
- Review API endpoints for RESTful design
- Check versioning strategy
- Evaluate the use of serializers for JSON responses
- Check authentication/authorization for API endpoints
- Analyze error handling and response formats

### 💎 Ruby/Rails Ecosystem & Version Compatibility
- Evaluate if the project is using an appropriate Ruby version (2.7+, 3.0+, 3.1+)
- Assess if the Rails version is appropriate and current (6.x, 7.x)
- Check for deprecated gem usage or APIs that will cause issues in future upgrades
- Review Gemfile for appropriate version specifications and constraints
- Evaluate compatibility between key gems and the Ruby/Rails versions
- Identify opportunities to leverage newer Ruby/Rails features
- Assess if the application is ready for upcoming Ruby/Rails versions

### 📦 Dependency Health & Security Analysis
- Identify any gems with known security vulnerabilities
- Check for outdated or unmaintained gems
- Evaluate the impact of security issues in current dependencies
- Review gems for appropriate security practices (e.g., strong params usage)
- Check for overuse of third-party gems where Ruby/Rails standard libraries would suffice
- Analyze potential licensing issues with current dependencies
- Review for secrets or credentials management best practices

---

## 📤 Output Format

Please provide a thorough review with the following sections:

1. **Overall Architecture Assessment**: Provide a high-level assessment of the overall architecture, highlighting key strengths and weaknesses

2. **Design Patterns and Practices**: Identify the design patterns and practices used, and evaluate their implementation

3. **Key Issues**: List architectural issues in order of priority, with:
   - Description of the issue
   - Impact on the codebase
   - Recommendation for improvement
   - Code example (if applicable)

4. **Positive Aspects**: Highlight what's well-designed in the architecture

5. **Recommendations**: Provide specific recommendations for architectural improvements

6. **Ruby/Rails Ecosystem Insights**: Include detailed version recommendations with:
   - Ruby/Rails version upgrade paths (with specific version numbers)
   - Benefits of newer versions (e.g., pattern matching in Ruby 3.0)
   - Key gem updates needed and their compatibility considerations
   - Security vulnerability mitigations
   - Performance improvements available in newer versions

7. **Long-term Considerations**: Suggest long-term architectural improvements that should be considered as the application grows

When providing Ruby/Rails ecosystem and version recommendations:
- Specify exact version numbers (e.g., Ruby 3.4.x, Rails 8.0.x)
- Note specific benefits of newer Ruby versions (e.g., performance improvements in Ruby 3.2)
- Highlight any breaking changes or migration challenges with version upgrades
- Consider deployment environment constraints (hosting platforms, etc.)
- Recommend stable, well-supported gems rather than beta or experimental ones
- Address security implications of outdated dependencies
- Consider the effort vs. benefit ratio for version upgrades

Focus on providing actionable feedback that will help improve the architecture of the codebase while maintaining the spirit and best practices of Ruby and Ruby on Rails development.

NOTE: Your suggestions are for manual implementation by the developer. This tool does not automatically apply fixes - it only provides recommendations that developers must review and implement themselves.