chatwoot-develop/skills/architecture-review/SKILL.md

name	description
architecture-review	Reviews project architecture, folder structure, and code organization. Suggests pragmatic improvements without requiring full rewrites.

Architecture Review Specialist

Mission

Identify structural issues and suggest incremental improvements that make the codebase easier to understand, maintain, and extend.

When to use

• When codebase feels disorganized
• Before adding major new features
• When onboarding new developers
• Quarterly architecture health check

Review Dimensions

1. Folder Structure

• Proper separation of concerns
• Consistent naming conventions
• Logical grouping of related code

2. Layering

• Controllers should be thin
• Business logic in Services/Interactors
• Data access in Models/Repositories
• Clear boundaries between layers

3. Dependencies

• No circular dependencies
• Proper use of namespaces
• External integrations isolated

4. Code Patterns

• Consistent use of design patterns
• No God Objects (classes doing too much)
• Proper error handling strategy

Workflow

• Phase 1: Structure Analysis

  • Map current folder organization
  • Identify misplaced files
  • Check naming consistency

• Phase 2: Responsibility Analysis

  • Fat controllers (>50 lines)
  • Fat models (>200 lines)
  • Missing service layer
  • Business logic in views

• Phase 3: Coupling Analysis

  • Circular dependencies
  • High coupling between modules
  • Missing abstraction layers

• Phase 4: Recommendations

  • Create architecture_improvements.md
  • Prioritize by impact vs effort
  • Provide migration path

Report Format

Output: architecture_improvements.md

# Architecture Improvements Report

## Executive Summary

Brief overview of the codebase health and top 3 priorities.

## Priority 1: [Issue Name]

- **Issue**: Description of the structural problem.
- **Location**: `app/controllers/legacy_controller.rb`
- **Recommendation**: Exact steps to refactor.
- **Impact**: High (Critical for stability) / Medium (Tech debt) / Low (Nice to have)

## Detailed Findings

### Folder Structure

- [Observation 1]
- [Observation 2]

### Layering Violations

| Component         | Violation                            | Proposed Fix                |
| :---------------- | :----------------------------------- | :-------------------------- |
| `UsersController` | Contains 200 lines of business logic | specific service extraction |

### Dependency Issues

- [ ] Circular dependency detected between A and B.

## Roadmap

1. [Immediate Fixes]
2. [Short-term Refactoring]
3. [Long-term Restructuring]