entscape

README

entscape

Interactive Ent schema visualization using Cytoscape.js.

Features

• Parse Ent schema files and export as JSON
• Interactive entity-relationship diagram with Cytoscape.js
• Click entities to open source code (GitHub/GitLab)
• Link to documentation (pkg.go.dev or self-hosted)
• Deploy to GitHub Pages as static HTML
• NPM module for embedding in existing sites

Installation

go install github.com/grokify/entscape/cmd/entscape@latest

Quick Start

# Generate JSON from Ent schema
entscape generate --schema ./ent/schema --output schema.json

# Generate static HTML
entscape generate --schema ./ent/schema --html --output docs/index.html

# With source links
entscape generate --schema ./ent/schema \
  --repo https://github.com/org/repo \
  --branch main \
  --html --output docs/index.html

NPM Module

npm install @grokify/entscape

import { render } from '@grokify/entscape';

const schema = await fetch('schema.json').then(r => r.json());
render(document.getElementById('diagram'), schema, {
  layout: 'dagre',
  theme: 'light'
});

JSON Schema

entscape uses a documented JSON format for schema data:

{
  "version": "1",
  "package": {
    "name": "github.com/org/repo/ent",
    "source": "https://github.com/org/repo",
    "branch": "main"
  },
  "entities": [
    {
      "name": "User",
      "path": "schema/user.go",
      "fields": [
        {"name": "id", "type": "int", "attrs": ["primary"]},
        {"name": "email", "type": "string", "attrs": ["unique", "required"]}
      ],
      "edges": [
        {"name": "posts", "target": "Post", "relation": "O2M", "inverse": "author"}
      ]
    }
  ]
}

See schema/entscape.schema.json for the full JSON Schema.

GitHub Pages

1. Generate HTML to docs/ folder:

   entscape generate --schema ./ent/schema --html --output docs/index.html
   

2. Enable GitHub Pages in repository settings (source: docs/ folder)

3. Optionally, add GitHub Action for auto-regeneration:

   name: Update Schema Diagram
   on:
     push:
       paths:
         - 'ent/schema/**'
   jobs:
     generate:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-go@v5
           with:
             go-version: '1.22'
         - run: go install github.com/grokify/entscape/cmd/entscape@latest
         - run: entscape generate --schema ./ent/schema --html --output docs/index.html
         - uses: stefanzweifel/git-auto-commit-action@v5
           with:
             commit_message: "docs: update schema diagram"
   

Relation Types

Code	Meaning	Example
O2O	One-to-One	User - Profile
O2M	One-to-Many	User - Posts
M2O	Many-to-One	Post - Author
M2M	Many-to-Many	User - Groups

License

MIT