Rails Flow Map 🚀

🎯 Comprehensive Rails Application Architecture Visualization Tool

Rails Flow Map is a powerful gem that analyzes your Rails application structure and generates beautiful, interactive visualizations to help understand architecture, dependencies, and data flow patterns.

日本語 | 中文

✨ Features

🎨 Multiple Visualization Formats

🌊 Mermaid Diagrams - GitHub-friendly markdown diagrams
🏗️ PlantUML - Detailed UML class diagrams
🔗 GraphViz - Network-style relationship graphs
⚡ Interactive D3.js - Zoomable, draggable web visualizations
📊 Metrics Reports - Code quality and complexity analysis
🔄 Sequence Diagrams - API endpoint flow visualization
📋 OpenAPI Specs - Auto-generated API documentation
📈 ERD Diagrams - Database schema visualization
🔍 Git Diff Views - Architecture change comparisons

🛡️ Enterprise-Grade Security

Path Traversal Protection - Prevents malicious file access
XSS Prevention - Sanitizes all HTML outputs
Input Validation - Comprehensive parameter checking
Security Event Logging - Tracks potential threats

⚡ Performance & Reliability

Structured Logging - Performance metrics and debugging info
Error Handling - Robust exception management with context
Retry Logic - Automatic recovery from transient failures
Memory Optimization - Efficient processing for large applications

🔧 Developer Experience

Zero Configuration - Works out of the box
Flexible Integration - Rake tasks, Ruby API, CI/CD support
Comprehensive Documentation - Examples and best practices
VS Code Integration - Built-in task definitions

🚀 Quick Start

Installation

Add to your Gemfile:

gem 'rails-flow-map'

bundle install
rails generate rails_flow_map:install

Basic Usage

# Generate architecture overview
graph = RailsFlowMap.analyze
RailsFlowMap.export(graph, format: :mermaid, output: 'docs/architecture.md')

# Create interactive visualization
RailsFlowMap.export(graph, format: :d3js, output: 'public/architecture.html')

# Generate API documentation
RailsFlowMap.export(graph, format: :openapi, output: 'docs/api.yaml')

Using Rake Tasks

# Generate all visualizations
rake flow_map:generate

# Specific format
rake flow_map:generate FORMAT=mermaid OUTPUT=docs/flow.md

# Analyze API endpoint
rake flow_map:endpoint ENDPOINT=/api/v1/users FORMAT=sequence

📊 Visualization Examples

🌊 Mermaid Architecture Diagram

graph TD
    User[User] --> Post[Post]
    User --> Comment[Comment]
    Post --> Comment
    UsersController --> User
    PostsController --> Post
    API[/api/v1/users] --> UsersController

⚡ Interactive D3.js Visualization

Features: Zoom, drag, filter by component type, search functionality

📋 OpenAPI Documentation

openapi: 3.0.0
info:
  title: Rails API Documentation
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: List all users
      responses:
        200:
          description: Successful response

🎯 Use Cases

👥 For Development Teams

📚 Documentation - Auto-generate always up-to-date architecture docs
🔍 Code Reviews - Visualize architectural changes in PRs
🎓 Onboarding - Help new team members understand the codebase
🏗️ Refactoring - Identify dependencies before making changes

🚀 For DevOps & CI/CD

📊 Monitoring - Track architecture complexity over time
🔄 Automation - Generate docs automatically on deployment
📈 Metrics - Collect code quality and dependency metrics
🚨 Alerts - Detect breaking architectural changes

📋 For API Teams

📖 API Docs - Auto-generate OpenAPI specifications
🔄 Flow Diagrams - Visualize request/response flows
🧪 Testing - Understand endpoint dependencies
📚 Client SDKs - Provide clear API structure documentation

🔧 Configuration

Basic Configuration

# config/initializers/rails_flow_map.rb
RailsFlowMap.configure do |config|
  config.output_directory = 'doc/flow_maps'
  config.exclude_paths = ['vendor/', 'tmp/']
  config.default_format = :mermaid
end

Advanced Configuration

RailsFlowMap.configure do |config|
  # Analysis options
  config.include_models = true
  config.include_controllers = true
  config.include_routes = true

  # Performance options
  config.streaming_mode = true
  config.memory_limit = 512.megabytes

  # Security options
  config.sanitize_output = true
  config.allow_system_paths = false
end

📚 Documentation

Quick References

📖 Usage Examples - Comprehensive usage guide
⚡ Quick Reference - Common commands and patterns
🔧 API Documentation - YARD documentation

Integration Guides

🔄 CI/CD Integration - GitHub Actions, GitLab CI
💻 VS Code Integration - Editor setup and tasks
🐳 Docker Integration - Containerized workflows

Examples

🚀 Basic Examples - Getting started code samples
🔬 Advanced Patterns - Complex use cases

🛠️ Supported Formats

Format	Description	Best For	Output
`mermaid`	GitHub-friendly diagrams	Documentation, README	`.md`
`plantuml`	Detailed UML diagrams	Technical documentation	`.puml`
`d3js`	Interactive visualizations	Exploration, presentations	`.html`
`openapi`	API specifications	API documentation	`.yaml`
`sequence`	Request flow diagrams	API analysis	`.md`
`erd`	Database schemas	Data modeling	`.md`
`metrics`	Code quality reports	Code reviews, monitoring	`.md`
`graphviz`	Network diagrams	Complex relationships	`.dot`

🔗 Integrations

GitHub Actions

name: Generate Architecture Docs
on: [push]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
      - run: bundle exec rake flow_map:generate_all

VS Code Tasks

{
  "label": "Generate Architecture Docs",
  "type": "shell",
  "command": "bundle exec rake flow_map:generate_all"
}

Pre-commit Hooks

#!/bin/bash
bundle exec rake flow_map:diff > ARCHITECTURE_CHANGES.md
git add ARCHITECTURE_CHANGES.md

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/railsflowmap/rails-flow-map.git
cd rails-flow-map
bundle install
rake spec

Running Tests

# Run all tests
bundle exec rspec

# Run specific test
bundle exec rspec spec/rails_flow_map/formatters/mermaid_formatter_spec.rb

# Run with coverage
COVERAGE=true bundle exec rspec

📄 License

Rails Flow Map is released under the MIT License.

🙏 Acknowledgments

Thanks to all contributors
Inspired by the Rails community's need for better architecture visualization
Built with ❤️ for the Rails ecosystem

🔗 Links

**⭐ Star us on GitHub if Rails Flow Map helps your team! ⭐** [⬆ Back to top](#rails-flow-map-)