# tidewave-ai/tidewave_rails architecture

> Architecture diagram of the GitHub repository tidewave-ai/tidewave_rails, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tidewave-ai/tidewave_rails
- Repository: https://github.com/tidewave-ai/tidewave_rails

## Overview

##### Project type and purpose
- Tidewave is an open-source Ruby gem that plugs into a Rails application via a Railtie.
- It implements the Model Context Protocol (MCP) to let an AI assistant (your LLM in the editor) inspect and manipulate the running web app (logs, DB, code, gem sources, etc.) at development time.

##### File structure
- Top-level directories:
- bin/ (developer tooling scripts, e.g. rubocop)
- config/ (database.yml and Railtie configuration hooks)
- lib/tidewave/ (the core library: configuration, file_tracker, railtie, tool_resolver)
- lib/tidewave/tools/ (one class per “tool”: execute_sql_query, grep_project_files, etc.)
- spec/ (unit tests for each component and tool)
- Key files:
- lib/tidewave/railtie.rb registers routes (MCP endpoint) and initializers
- lib/tidewave/tool_resolver.rb dynamically picks the right tool class for each MCP request
- lib/tidewave/file_tracker.rb tracks file changes in the host app
- configuration.rb for user-customizable options (allowed_ips, origins)

##### README for additional insights
- Describes how Tidewave is mounted at `/tidewave/mcp` on the Rails server
- Emphasizes development-only use on a threaded server (Puma)
- References FastMCP as the underlying protocol for JSON-over-HTTP messaging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        LLM(("LLM in Editor")):::external
        Plugin["Editor Plugin / MCP Client"]:::external
    end

    LLM -->|"HTTP JSON"| Plugin

    %% Rails App with Tidewave
    subgraph "Rails Application (Puma)"
        subgraph "Tidewave (Railtie Plugin)"
            Entry["Core Library Entry Point"]:::runtime
            Version["Version Definition"]:::runtime
            Configuration["Configuration Object"]:::runtime
            Railtie["Tidewave Railtie/Engine"]:::runtime
            ToolResolver["Tool Resolver"]:::runtime
            FileTracker["File Tracker"]:::runtime

            subgraph "Tools"
                Base["Base Tool Class"]:::runtime
                ESQL["execute_sql_query"]:::runtime
                Grep["grep_project_files"]:::runtime
                Glob["glob_project_files"]:::runtime
                ListF["list_project_files"]:::runtime
                ReadF["read_project_file"]:::runtime
                WriteF["write_project_file"]:::runtime
                EditF["edit_project_file"]:::runtime
                PkgSearch["package_search"]:::runtime
                ProjectEval["project_eval"]:::runtime
                ShellEval["shell_eval"]:::runtime
                LogsTool["get_logs"]:::runtime
                Models["get_models"]:::runtime
                SrcLoc["get_source_location"]:::runtime
            end
        end

        subgraph "Host Application Subsystems"
            DB[(Database)]:::subsystem
            Logs[(Logs Storage)]:::subsystem
            FS[(Source Files)]:::subsystem
            Gems[(Gem Code)]:::subsystem
        end
    end

    %% Data Flow
    Plugin -->|"POST /tidewave/mcp"| Railtie
    Railtie -->|"validate config"| Configuration
    Railtie -->|"dispatch request"| ToolResolver
    ToolResolver --> Base
    ToolResolver --> ESQL
    ToolResolver --> Grep
    ToolResolver --> Glob
    ToolResolver --> ListF
    ToolResolver --> ReadF
    ToolResolver --> WriteF
    ToolResolver --> EditF
    ToolResolver --> PkgSearch
    ToolResolver --> ProjectEval
    ToolResolver --> ShellEval
    ToolResolver --> LogsTool
    ToolResolver --> Models
    ToolResolver --> SrcLoc
    Base --> FileTracker
    ESQL -->|"SQL query"| DB
    Models -->|"ActiveRecord"| DB
    Grep -->|"grep"| FS
    Glob -->|"glob"| FS
    ListF -->|"list"| FS
    ReadF -->|"read"| FS
    WriteF -->|"write"| FS
    EditF -->|"edit"| FS
    ProjectEval -->|"Ruby eval"| FS
    ShellEval -->|"shell"| FS
    LogsTool -->|"read logs"| Logs
    SrcLoc -->|"inspect"| Gems
    ToolResolver --> Railtie
    Railtie -->|"HTTP JSON response"| Plugin
    Plugin -->|"deliver"| LLM

    %% Click Events
    click Entry "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave.rb"
    click Version "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/version.rb"
    click Configuration "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/configuration.rb"
    click Railtie "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/railtie.rb"
    click ToolResolver "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tool_resolver.rb"
    click FileTracker "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/file_tracker.rb"
    click Base "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/base.rb"
    click ESQL "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/execute_sql_query.rb"
    click Grep "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/grep_project_files.rb"
    click Glob "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/glob_project_files.rb"
    click ListF "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/list_project_files.rb"
    click ReadF "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/read_project_file.rb"
    click WriteF "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/write_project_file.rb"
    click EditF "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/edit_project_file.rb"
    click PkgSearch "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/package_search.rb"
    click ProjectEval "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/project_eval.rb"
    click ShellEval "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/shell_eval.rb"
    click LogsTool "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/get_logs.rb"
    click Models "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/get_models.rb"
    click SrcLoc "https://github.com/tidewave-ai/tidewave_rails/blob/main/lib/tidewave/tools/get_source_location.rb"

    %% Styles
    classDef external fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef runtime fill:#E5FFE5,stroke:#339933,color:#003300
    classDef subsystem fill:#FFE5CC,stroke:#FF9933,color:#663300
```
