canvas_erd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b593a4a8e3ebb6c820c3469cc0063acb4fdf129313e2ea2c68da33a15166be2
+  data.tar.gz: da8d50366c574f574289cf59046e98954fdf324ceff1f20d3ba2811349a5b35e
+SHA512:
+  metadata.gz: 8262355aa351a042ea353f9d1340aee15d30e839f29bcdea12c3d3d728070d176deb0cb845db2b43e7c1f0cb05cd8321a8480e00286e665379b1b368640c0f31
+  data.tar.gz: a4db10469eaf6ee4f1d95afbcc7f02f826c37f0234187d02d925c79d73f4c65f86c9fe5dbb8e08d6e46929189c6e53d5695f81f05e185d2a01c73349e88b1776

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-08-30
+
+- Generate a JSON-safe diagram schema from Rails ERD domain models.
+- Start a loopback-only editor using the Rails application's Rack server.
+- Arrange and select tables on a Fabric.js canvas, with editable notes, arrows, zoom, and pan controls.
+- Refresh columns and relationships while preserving diagram edits.
+- Save editable diagrams inside ordinary PNG files and reopen them from the CLI.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Heiligers, FASCINATION•works
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,86 @@
+# CanvasERD
+
+CanvasERD is a companion gem for editing diagrams generated from Rails ERD domain models in a local browser.
+
+The editor renders Rails models and relationships on an interactive Fabric.js canvas.
+New diagrams use ELK's layered graph layout to arrange tables from their Rails relationships.
+
+## Installation
+
+Add CanvasERD to the development group in the Rails application's `Gemfile`:
+
+```ruby
+group :development do
+  gem "canvas_erd", require: false
+end
+```
+
+Then run `bundle install`. CanvasERD requires Ruby 3.1 or newer, Active Record 7.0 or newer, and a Rack server available in the Rails bundle.
+
+## Usage
+
+From a Rails application root, run:
+
+```sh
+bundle exec canvas_erd
+```
+
+CanvasERD loads and eager-loads the Rails application, generates the schema, starts on a loopback-only address, and opens the editor in the default browser. Pass `--no-open` to print the URL without opening it.
+
+CanvasERD uses Rackup with a server handler already present in the Rails bundle, normally Puma. It does not install a separate web server.
+
+Diagrams are saved by the editor as `*.erd.png` files under `docs/erd/` in the Rails application. Use a different directory inside the application with `--diagrams-dir`, for example:
+
+```sh
+bundle exec canvas_erd --diagrams-dir db/diagrams
+```
+
+The editor's saved-diagram menu loads these files directly. You can also open a diagram when starting CanvasERD with `bundle exec canvas_erd path/to/domain.erd.png`.
+
+## Editor controls
+
+- Drag tables to reposition them.
+- Use the table sidebar to add or remove tables without losing their positions.
+- Use **Layout tables** to rearrange the tables currently on the canvas with ELK without moving notes or hidden tables.
+- Pinch over the canvas or use the toolbar buttons to zoom.
+- Use a two-finger trackpad gesture to pan. Space-drag remains available as a keyboard fallback, and **Fit diagram** resets the view.
+- Add editable notes with **Add note**. Select a note and press Delete to remove it.
+- Use **Refresh schema** after a database migration to update columns and relationships. Existing table positions, selections, notes, and the current view are preserved; new tables start unselected.
+- Edit the diagram name, then use **Save** (or <kbd>⌘S</kbd>/<kbd>Ctrl-S</kbd>) to write the complete diagram into the Rails application as a normal `*.erd.png` image with its editable schema, layout, notes, selection, and viewport embedded inside it. Select a saved diagram from the menu to reopen it, or use **New** to start an “Untitled ERD.”
+
+CanvasERD refreshes the model classes already loaded by the server. Restart CanvasERD after adding or renaming model classes or changing model code.
+Image optimization tools may remove the CanvasERD metadata required to edit a diagram again.
+
+The editor binds only to `127.0.0.1` and does not expose the Rails application over the network.
+
+## Domain adapter
+
+After loading the Rails application, generate a JSON-safe schema hash with:
+
+```ruby
+schema = CanvasERD::Diagram.create
+```
+
+The schema contains entities, attributes, relationships, and specializations with stable identifiers. Relationship cardinality ranges use `nil` as an unbounded maximum.
+
+## Development
+
+Run the tests:
+
+```sh
+bundle exec rake test
+```
+
+Build the gem:
+
+```sh
+bundle exec rake build
+```
+
+## License
+
+CanvasERD is available under the MIT License. Dependencies remain subject to their included licenses.
+
+[Fabric.js](https://fabricjs.com/) 7.4.0 is vendored under `lib/canvas_erd/web/vendor`. Its license is included in `licenses/FABRIC-JS-LICENSE.txt`.
+[elkjs](https://github.com/kieler/elkjs) 0.12.0 is vendored there as a browser API and Web Worker. Its [source is available from the elkjs project](https://github.com/kieler/elkjs/tree/0.12.0), and its license is included in `licenses/ELKJS-LICENSE.md`.
+Icons from [iconoir](https://iconoir.com/) directly embedded in the HTML, and it's license is included in `licenses/ICONOIR-LICENSE`.

data/exe/canvas_erd

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "canvas_erd"
+
+exit CanvasERD::CLI.start(ARGV)
+

data/lib/canvas_erd/application_loader.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CanvasERD
+  class ApplicationLoader
+    class Error < StandardError; end
+
+    attr_reader :root
+
+    def initialize(root = Dir.pwd)
+      @root = File.expand_path(root)
+    end
+
+    def load
+      environment_path = File.join(root, "config", "environment.rb")
+      unless File.file?(environment_path)
+        raise Error, "Rails application environment not found at #{environment_path}"
+      end
+
+      require environment_path
+      eager_load_rails_application
+      true
+    end
+
+    private
+
+    def eager_load_rails_application
+      return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+      Rails.application.eager_load!
+
+      config = Rails.application.config
+      return unless config.respond_to?(:eager_load_namespaces)
+
+      config.eager_load_namespaces.each(&:eager_load!)
+    end
+  end
+end

data/lib/canvas_erd/browser.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module CanvasERD
+  class Browser
+    def self.open(url)
+      new.open(url)
+    end
+
+    def initialize(host_os: RbConfig::CONFIG.fetch("host_os"), process_spawn: Process.method(:spawn))
+      @host_os = host_os
+      @process_spawn = process_spawn
+    end
+
+    def open(url)
+      command = command_for(url)
+      return false unless command
+
+      process_id = @process_spawn.call(*command, out: File::NULL, err: File::NULL)
+      Process.detach(process_id) if process_id.is_a?(Integer)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    private
+
+    def command_for(url)
+      case @host_os
+      when /darwin/
+        ["open", url]
+      when /linux|bsd/
+        ["xdg-open", url]
+      when /mswin|mingw|cygwin/
+        ["cmd", "/c", "start", "", url]
+      end
+    end
+  end
+end

data/lib/canvas_erd/cli.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module CanvasERD
+  class CLI
+    class Error < StandardError; end
+
+    Options = Struct.new(:action, :diagram_path, :diagrams_directory, :open_browser, keyword_init: true)
+
+    def self.start(arguments = ARGV, out: $stdout, err: $stderr)
+      new(out: out, err: err).start(arguments)
+    end
+
+    def initialize(out: $stdout, err: $stderr, root: Dir.pwd)
+      @out = out
+      @err = err
+      @root = root
+    end
+
+    def start(arguments)
+      options = parse(arguments)
+
+      case options.action
+      when :help
+        @out.puts parser
+        0
+      when :version
+        @out.puts "CanvasERD #{CanvasERD::VERSION}"
+        0
+      else
+        run(options)
+      end
+    rescue OptionParser::ParseError => error
+      @err.puts "Error: #{error.message}"
+      @err.puts parser
+      1
+    rescue Error, ApplicationLoader::Error, DiagramStore::Error, PngDocument::Error, Server::Error => error
+      @err.puts "Error: #{error.message}"
+      1
+    rescue StandardError => error
+      @err.puts "Failed: #{error.class}: #{error.message}"
+      1
+    end
+
+    def parse(arguments)
+      action = :run
+      diagrams_directory = DiagramStore::DEFAULT_DIRECTORY
+      open_browser = true
+      remaining = parser(
+        action_setter: ->(value) { action = value },
+        directory_setter: ->(value) { diagrams_directory = value },
+        open_setter: ->(value) { open_browser = value }
+      ).parse(arguments.dup)
+
+      raise OptionParser::ParseError, "expected at most one diagram path" if remaining.length > 1
+
+      Options.new(
+        action: action,
+        diagram_path: remaining.first,
+        diagrams_directory: diagrams_directory,
+        open_browser: open_browser
+      )
+    end
+
+    private
+
+    def run(options)
+      if options.diagram_path
+        @err.puts "Loading CanvasERD diagram from #{options.diagram_path}..."
+        document = PngDocument.load(File.expand_path(options.diagram_path, @root))
+      end
+
+      @err.puts "Loading Rails application from #{@root}..."
+      ApplicationLoader.new(@root).load
+
+      schema_provider = SchemaProvider.new
+      if document
+        schema = document.fetch("schema")
+        state = document.fetch("state")
+      else
+        @err.puts "Generating Rails ERD schema..."
+        schema = schema_provider.call
+      end
+      diagram_store = DiagramStore.new(root: @root, directory: options.diagrams_directory)
+      app = WebApplication.new(
+        schema: schema,
+        schema_provider: schema_provider,
+        state: state,
+        diagram_store: diagram_store
+      )
+      server = Server.new(app: app)
+
+      @out.puts "CanvasERD is running at #{server.url}"
+      unless !options.open_browser || Browser.open(server.url)
+        @err.puts "Could not open a browser. Visit #{server.url} manually."
+      end
+
+      server.start
+      0
+    end
+
+    def parser(action_setter: ->(_value) {}, directory_setter: ->(_value) {}, open_setter: ->(_value) {})
+      OptionParser.new do |options|
+        options.banner = "Usage: canvas_erd [options] [diagram.png]"
+
+        options.on("--no-open", "Do not open the editor in a browser") do
+          open_setter.call(false)
+        end
+
+        options.on("--diagrams-dir DIRECTORY", "Store diagrams here (default: docs/erd)") do |directory|
+          directory_setter.call(directory)
+        end
+
+        options.on("-v", "--version", "Print the CanvasERD version") do
+          action_setter.call(:version)
+        end
+
+        options.on("-h", "--help", "Show this help") do
+          action_setter.call(:help)
+        end
+      end
+    end
+  end
+end

data/lib/canvas_erd/diagram.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "rails_erd/diagram"
+
+module CanvasERD
+  class Diagram < RailsERD::Diagram
+    setup do
+      @entity_ids = {}
+      @schema = {
+        "name" => domain.name,
+        "entities" => [],
+        "relationships" => [],
+        "specializations" => []
+      }
+    end
+
+    each_entity do |entity, attributes|
+      @entity_ids[entity.name.to_s] = true
+      @schema["entities"] << entity_data(entity, attributes)
+    end
+
+    each_specialization do |specialization|
+      next unless included_entity?(specialization.generalized) && included_entity?(specialization.specialized)
+
+      @schema["specializations"] << specialization_data(specialization)
+    end
+
+    each_relationship do |relationship|
+      next unless included_entity?(relationship.source) && included_entity?(relationship.destination)
+
+      @schema["relationships"] << relationship_data(relationship)
+    end
+
+    save do
+      @schema["entities"].sort_by! { |entity| entity.fetch("id") }
+      @schema["relationships"].sort_by! { |relationship| relationship.fetch("id") }
+      @schema["specializations"].sort_by! { |specialization| specialization.fetch("id") }
+      @schema
+    end
+
+    private
+
+    def entity_data(entity, attributes)
+      {
+        "id" => entity.name.to_s,
+        "name" => entity.name.to_s,
+        "label" => entity_label(entity),
+        "table_name" => entity.model&.table_name,
+        "namespace" => entity.namespace,
+        "virtual" => entity.virtual?,
+        "generalized" => entity.generalized?,
+        "specialized" => entity.specialized?,
+        "attributes" => attributes.map { |attribute| attribute_data(entity, attribute) }
+      }
+    end
+
+    def entity_label(entity)
+      if options[:table_names] && entity.model
+        entity.model.table_name
+      else
+        entity.name.to_s
+      end
+    end
+
+    def attribute_data(entity, attribute)
+      {
+        "id" => "#{entity.name}.#{attribute.name}",
+        "name" => attribute.name.to_s,
+        "type" => attribute.type.to_s,
+        "type_description" => attribute.type_description,
+        "primary_key" => attribute.primary_key?,
+        "foreign_key" => attribute.foreign_key?,
+        "mandatory" => attribute.mandatory?,
+        "unique" => attribute.unique?,
+        "timestamp" => attribute.timestamp?,
+        "inheritance" => attribute.inheritance?
+      }
+    end
+
+    def relationship_data(relationship)
+      source_id = relationship.source.name.to_s
+      destination_id = relationship.destination.name.to_s
+
+      {
+        "id" => endpoint_id("relationship", source_id, destination_id),
+        "source_id" => source_id,
+        "destination_id" => destination_id,
+        "cardinality" => cardinality_data(relationship.cardinality),
+        "indirect" => relationship.indirect?,
+        "mutual" => relationship.mutual?,
+        "recursive" => relationship.recursive?
+      }
+    end
+
+    def cardinality_data(cardinality)
+      {
+        "name" => cardinality.name.to_s,
+        "source" => range_data(cardinality.source_range),
+        "destination" => range_data(cardinality.destination_range)
+      }
+    end
+
+    def range_data(range)
+      {
+        "minimum" => range.begin,
+        "maximum" => range.end.finite? ? range.end : nil
+      }
+    end
+
+    def specialization_data(specialization)
+      generalized_id = specialization.generalized.name.to_s
+      specialized_id = specialization.specialized.name.to_s
+
+      {
+        "id" => endpoint_id("specialization", generalized_id, specialized_id),
+        "generalized_id" => generalized_id,
+        "specialized_id" => specialized_id,
+        "type" => specialization.inheritance? ? "inheritance" : "polymorphic"
+      }
+    end
+
+    def included_entity?(entity)
+      entity && @entity_ids.key?(entity.name.to_s)
+    end
+
+    def endpoint_id(kind, first_id, second_id)
+      "#{kind}:#{[first_id, second_id].sort.join('|')}"
+    end
+  end
+end

data/lib/canvas_erd/diagram_store.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "stringio"
+
+module CanvasERD
+  class DiagramStore
+    class Error < StandardError; end
+    class NotFound < Error; end
+
+    DEFAULT_DIRECTORY = "docs/erd"
+    FILENAME_PATTERN = /\A[^\x00\/\\]+\.erd\.png\z/i
+
+    attr_reader :directory
+
+    def initialize(root:, directory: DEFAULT_DIRECTORY)
+      @root = File.expand_path(root)
+      @directory = File.expand_path(directory, @root)
+      return if @directory.start_with?("#{@root}#{File::SEPARATOR}")
+
+      raise Error, "Diagram directory must be inside the Rails application"
+    end
+
+    def relative_directory
+      directory.delete_prefix("#{@root}#{File::SEPARATOR}")
+    end
+
+    def names
+      return [] unless Dir.exist?(directory)
+
+      Dir.children(directory).select { |name| valid_filename?(name) && File.file?(path_for(name)) }.sort
+    end
+
+    def read(name)
+      bytes = File.binread(path_for(name))
+      PngDocument.read(StringIO.new(bytes))
+      bytes
+    rescue Errno::ENOENT
+      raise NotFound, "Diagram not found: #{name}"
+    rescue SystemCallError => error
+      raise Error, "Could not read diagram #{name}: #{error.message}"
+    rescue PngDocument::Error => error
+      raise Error, error.message
+    end
+
+    def write(name, bytes)
+      path = path_for(name)
+      PngDocument.read(StringIO.new(bytes))
+      FileUtils.mkdir_p(directory)
+      File.binwrite(path, bytes)
+      name
+    rescue SystemCallError => error
+      raise Error, "Could not save diagram #{name}: #{error.message}"
+    rescue PngDocument::Error => error
+      raise Error, error.message
+    end
+
+    private
+
+    def path_for(name)
+      raise Error, "Diagram filename must end in .erd.png" unless valid_filename?(name)
+
+      File.join(directory, name)
+    end
+
+    def valid_filename?(name)
+      name.is_a?(String) && FILENAME_PATTERN.match?(name)
+    end
+  end
+end

data/lib/canvas_erd/png_document.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require "zlib"
+
+module CanvasERD
+  class PngDocument
+    class Error < StandardError; end
+
+    SIGNATURE = "\x89PNG\r\n\x1a\n".b
+    KEYWORD = "CanvasERD"
+    ITXT_PREFIX = "#{KEYWORD}\0\0\0\0\0".b
+    MAX_CHUNK_SIZE = 64 * 1024 * 1024
+
+    def self.load(path)
+      File.open(path, "rb") { |file| read(file) }
+    rescue SystemCallError => error
+      raise Error, "Could not read diagram #{path}: #{error.message}"
+    end
+
+    def self.read(input)
+      raise Error, "Not a PNG file" unless input.read(SIGNATURE.bytesize) == SIGNATURE
+
+      document_json = nil
+      found_end = false
+
+      until found_end
+        length_bytes = input.read(4)
+        raise Error, "PNG ended before its IEND chunk" unless length_bytes&.bytesize == 4
+
+        length = length_bytes.unpack1("N")
+        raise Error, "PNG chunk is too large" if length > MAX_CHUNK_SIZE
+
+        type = read_exact(input, 4)
+        data = read_exact(input, length)
+        checksum = read_exact(input, 4).unpack1("N")
+        raise Error, "PNG chunk checksum is invalid" unless Zlib.crc32(type + data) == checksum
+
+        if type == "iTXt" && data.start_with?(ITXT_PREFIX)
+          document_json = data.delete_prefix(ITXT_PREFIX).force_encoding(Encoding::UTF_8)
+        end
+        found_end = type == "IEND"
+      end
+
+      raise Error, "PNG does not contain an editable CanvasERD diagram" unless document_json
+
+      validate(JSON.parse(document_json))
+    rescue JSON::ParserError => error
+      raise Error, "CanvasERD diagram metadata is invalid: #{error.message}"
+    end
+
+    def self.read_exact(input, length)
+      value = input.read(length)
+      raise Error, "PNG chunk is truncated" unless value&.bytesize == length
+
+      value
+    end
+    private_class_method :read_exact
+
+    def self.validate(document)
+      schema = document["schema"] if document.is_a?(Hash)
+      state = document["state"] if document.is_a?(Hash)
+      valid = document.is_a?(Hash) &&
+        document["format"] == "canvas_erd" &&
+        document["version"] == 1 &&
+        schema.is_a?(Hash) &&
+        schema["entities"].is_a?(Array) &&
+        schema["relationships"].is_a?(Array) &&
+        schema["specializations"].is_a?(Array) &&
+        state.is_a?(Hash) &&
+        state["includedEntityIds"].is_a?(Array) &&
+        state["positions"].is_a?(Hash) &&
+        state["notes"].is_a?(Array)
+      raise Error, "CanvasERD diagram format is not supported" unless valid
+
+      document
+    end
+    private_class_method :validate
+  end
+end

data/lib/canvas_erd/schema_provider.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CanvasERD
+  class SchemaProvider
+    def initialize(models: -> { ActiveRecord::Base.descendants }, diagram: -> { CanvasERD::Diagram.create })
+      @models = models
+      @diagram = diagram
+    end
+
+    def call
+      @models.call.each(&:reset_column_information)
+      @diagram.call
+    end
+  end
+end