Rails Atlas is an architecture analysis and dependency visualization tool for Ruby on Rails applications.
It uses fast, static AST parsing (via Ruby's prism parser) to extract ActiveRecord models and associations without booting Rails or connecting to a database. Atlas provides both a comprehensive Command Line Interface (CLI) and an interactive Web UI to explore model relationships, discover architectural hotspots, detect design smells, and analyze change impact.
- Features
- Requirements
- Installation
- Command Line Interface (CLI)
- Interactive Web UI
- Architectural Metrics & Smells
- How It Works
- Development
- License
-
Static Analysis (Fast & Safe): Parses Rails models using Ruby 3.3+
prismAST parser. No need to boot Rails, load the database, or execute application code. -
Zeitwerk-Aware Namespace Resolution: Accurately resolves namespaced model associations (e.g.
Treasurer::Request→has_many :line_itemsresolves toTreasurer::LineItemwhen present). -
Association Extraction: Identifies
belongs_to,has_many,has_one, andhas_and_belongs_to_many(HABTM) associations while ignoring non-model concerns (app/models/concerns). -
Graph & Dependency Analysis:
- Shortest path routing between any two models.
- Blast radius & transitive impact analysis.
- Inbound and outbound dependency breakdown.
- Architectural hotspots detection (most connected models).
-
Design Smell Detection:
-
God Models: Models with high coupling (
$\ge 10$ total connections). -
Orphan / Leaf Models: Models with
$\le 1$ connection.
-
God Models: Models with high coupling (
-
Export Formats: Export architecture graphs to
atlas.jsonand Graphvizatlas.dot. -
Interactive Web Visualizer: Built-in Sinatra web server with interactive
vis-networkgraph, real-time search, association filters, path finder, and smells panel.
- Ruby:
>= 3.2.0 - Target Rails App: Rails 5/6/7/8 applications structured with standard
app/models.
Add rails-atlas to your Rails application's Gemfile (typically in the development group):
group :development do
gem 'rails-atlas'
endAnd install:
bundle installYou can also run Atlas directly against any Rails application directory:
git clone https://github.com/bosseschum/rails-atlas.git
cd rails-atlas
bundle install
bin/atlas helpRun commands using bundle exec atlas <command> (or bin/atlas <command>):
Commands:
atlas graph PATH # Generate graph files (atlas.dot)
atlas help [COMMAND] # Describe available commands or one specific command
atlas hotspots PATH [LIMIT] # Show architecture hotspots
atlas impact PATH MODEL # Analyze impact of a model
atlas model PATH MODEL # Inspect a model
atlas neighbors PATH MODEL # Show directly connected neighbors
atlas path PATH START END # Find path between two models
atlas scan PATH # Scan a Rails application
atlas serve PATH # Serve the architecture graph
atlas smells PATH # Show architectural smells
atlas stats PATH # Show graph statistics
Note:
PATHcan be a relative or absolute path to the root directory of your Rails application (e.g.,.or../my-rails-app).
Scans the target Rails application and writes the entire architecture graph (nodes and edges) to atlas.json.
atlas scan .Output:
Scan complete. Atlas graph saved to atlas.json
Displays a high-level summary of the application's domain model architecture, including total models, total associations, most connected models, association type breakdowns, and top architecture hotspots.
atlas stats .Example Output:
Atlas Statistics
----------------
Models: 42
Associations: 98
Most Connected Models:
----------------
User: 24
Organization: 18
Project: 12
Order: 10
Association Types:
----------------
belongs_to: 52
has_many: 38
has_one: 6
has_and_belongs_to_many: 2
Architecture Hotspots:
----------------
User
Organization
Project
Order
Exports the architecture model graph to a Graphviz DOT format file (atlas.dot), which can be converted to PNG, SVG, or PDF using Graphviz dot.
atlas graph .Output:
Generate atlas.dot
Convert to image using Graphviz:
dot -Tpng atlas.dot -o architecture.pngInspects a specific model, listing its incoming and outgoing associations.
atlas model . UserExample Output:
Model: User
Outgoing Associations:
----------------------
belongs_to organization
has_many projects
has_many orders
Incoming Associations:
----------------------
Comment belongs_to author
Membership belongs_to user
Calculates and displays the shortest dependency path between two models using breadth-first search (BFS).
atlas path . Order InvoiceExample Output:
Order
↓
Payment
↓
Invoice
If no path connects the two models, it outputs No path found.
Lists all directly connected models, indicating directional flow ([IN] or [OUT]) and association details.
atlas neighbors . OrganizationExample Output:
Model: Organization
Directly Connected Models
-------------------------
[OUT] has_many members → Member
[OUT] has_many projects → Project
[IN] User belongs_to organization
Ranks and displays the top architectural hotspots (models with the highest degree of connectivity).
atlas hotspots . 5Example Output:
Architectural Hotspots
---------------------
User (24)
Organization (18)
Project (12)
Order (10)
Account (8)
Runs heuristic smell detection across the model graph:
-
Potential God Models: Models with
$\ge 10$ incoming and outgoing connections. -
Leaf / Orphan Models: Models with
$\le 1$ connection (isolated or peripheral models).
atlas smells .Example Output:
Architectural Smells
-------------------
Potential God Models
-------------------
User - 24 connections
Organization - 18 connections
Leaf Models
-----------
AuditLog
FeatureFlag
Setting
Performs blast radius / reachability analysis. Displays all models transitively reachable from the target model across the graph component, along with the total reach count.
atlas impact . OrganizationExample Output:
Impact Analysis: Organization
-------------------------
Account
Invoice
Member
Order
Payment
Project
Subscription
User
Total Reach: 8 models
Starts the interactive Atlas Web UI backed by Sinatra at http://localhost:4567.
atlas serve .Output:
== Sinatra (v4.0.0) has taken the stage on 4567 for development with backup from WEBrick
[2026-11-02 13:46:00] INFO WEBrick::HTTPServer#start: pid=... port=4567
Open http://localhost:4567 in your browser.
The web visualizer renders your Rails architecture graph using vis-network and provides real-time interaction.
- Graph Exploration: Pan, zoom, and drag nodes to inspect relationships.
- Model Search: Filter models by name dynamically using the top search bar.
-
Association Filters: Toggle checkboxes to filter visible edge types:
belongs_tohas_manyhas_one-
habtm(has_and_belongs_to_many)
- Edge Labels: Checkbox to toggle association relationship names on edges.
-
Model Details & Metrics Sidebar: Click any model node to view:
- Metrics: Total connections (Degree), Incoming count, Outgoing count, Impact reach count.
-
Connections: Inbound (
$\leftarrow$ ) and Outbound ($\rightarrow$ ) associations. - Impact Reach: All reachable models in the dependency graph.
-
Shortest Path Finder:
- Shift + Click node A to set start point.
- Shift + Click node B to set end point and visualize the highlighted shortest path.
- Architectural Smells Panel: Click the Smells button in the top bar to inspect God Models, Orphan Models, and Hotspots in the sidebar.
- Resizable Sidebar: Drag the sidebar handle to adjust view widths.
The Sinatra backend exposes the following JSON endpoints:
| Endpoint | Description |
|---|---|
GET /api/graph |
Full graph data with nodes, degrees, and edges |
GET /api/models |
List of all model node objects |
GET /api/models/:name |
Direct incoming and outgoing connections for :name |
GET /api/model/:name |
Graph metrics for :name (degree, impact, incoming, outgoing, hotspot, orphan) |
GET /api/impact/:name |
Array of transitively reachable models starting from :name |
GET /api/path/:from/:to |
Array of nodes representing the shortest path between :from and :to |
GET /api/smells |
Architectural smells summary (god_models, orphans, high_impact) |
| Metric / Smell | Definition | Purpose |
|---|---|---|
| Degree | Total incoming + outgoing associations | Measures model coupling and centrality |
| Impact Reach | Number of reachable models via graph traversal | Evaluates blast radius when refactoring or migrating a model |
| God Model | Total connections |
Identifies bloated models that may violate Single Responsibility Principle |
| Orphan / Leaf Model | Total connections |
Identifies isolated models, auxiliary tables, or dead domain concepts |
| Hotspots | Models sorted by descending degree | Highlights primary domain aggregates and integration points |
- Scanner (
Atlas::Scanner): Finds all.rbfiles inapp/models/while excluding non-model files such asapp/models/concerns. - AST Association Extraction (
Atlas::AssociationExtractor): Uses Ruby'sPrismparser to walk the AST and extract macro calls (belongs_to,has_many,has_one,has_and_belongs_to_many). - Namespace Resolution (
Atlas::GraphBuilder): Resolves associations using Zeitwerk/ActiveRecord scoping rules (e.g., scoping under enclosing module namespaces before falling back to top-level constants). - Graph Engine (
Atlas::Graph): Builds an in-memory graph representation with BFS path finding, reachable component traversal, degree calculations, and smell detectors.
# Clone the repository
git clone https://github.com/bosseschum/rails-atlas.git
cd rails-atlas
# Install development dependencies
bundle install
# Run RuboCop
bundle exec rubocopThis gem is available as open source under the terms of the MIT License.