ERDGo

AI-powered Entity Relationship Diagram (ERD) generator and analyzer for any codebase.

ERDGo scans your project (Prisma, Laravel, SQL, models, services, routes), builds an interactive ERD, optionally enhances relationships with AI, and lets you edit, export, screenshot, and chat about the schema.

Table of contents

• Features
• Requirements
• Installation
• Quick start
• CLI reference
• Dashboard walkthrough
• Generate ERD with AI
• Interactive ERD editor
• AI project chat
• Exports
• AI provider setup
• Configuration
• HTTP API
• Project structure
• Development
• How it works
• Troubleshooting
• Publishing / GitHub
• License

Features

• Framework-aware scan — Prisma, Laravel, React/Vite, Nest-style layouts, SQL dumps, models, migrations
• Heuristic ERD — tables/entities, fields, PK/FK, formal ORM relations
• AI enhancement — soft/logical joins from app code (lookups, embeds, include trees)
• Interactive React Flow canvas — drag tables, connect fields, bend lines, reconnect ends
• Full-page ERD screenshot — PNG / JPEG / SVG, dark or light theme
• SQL + Markdown + DOC export — MySQL, PostgreSQL, SQL Server, Oracle, SQLite
• Use Case & Business Process diagrams — generated from the current ERD
• AI project chat — ask about login, CRUD, routes, and tables using scanned context
• Global CLI — erdgo start -r /path/to/project

Requirements

| Requirement | Version / notes | |-------------|-----------------| | Node.js | 18+ recommended (20+ ideal) | | npm | 9+ | | OS | Windows, macOS, Linux | | AI (optional) | Any OpenAI-compatible API (OpenAI, OpenRouter, Ollama, 9Router, custom gateway) |

Installation

Option A — Global install from this repository (local package)

git clone https://github.com/<your-org>/erdgo.git
cd erdgo
npm install
npm run build
npm i -g .

After that, the erdgo command is available system-wide.

Option B — Global install from npm (after publish)

npm i -g erdgo

Option C — Run without global install

git clone https://github.com/<your-org>/erdgo.git
cd erdgo
npm install
npm run build
node dist/cli.js start -r /path/to/your/project
# or during development:
npx tsx cli.ts start -r /path/to/your/project

Note: Until the package is published to the npm registry, use Option A or C. npm i -g erdgo only works after npm publish.

Quick start

# 1) Install (from repo)
npm install
npm run build
npm i -g .

# 2) Start against a project
erdgo start -r /path/to/your/app

# 3) Open the dashboard
#    http://localhost:3847

Optional port:

erdgo start -r /path/to/your/app -p 3848

Typical first session:

1. Open http://localhost:3847
2. Confirm Project root points at your app
3. Configure AI settings (optional but recommended)
4. Click Scan files + Generate ERD (or open /erd → Regenerate ERD)
5. Explore the interactive diagram at http://localhost:3847/erd

CLI reference

erdgo <command> [options]

| Command | Description | |---------|-------------| | erdgo start | Create project-docs/ structure and start the dashboard server | | erdgo ui | Same as start (dashboard only entry) | | erdgo --version | Print version | | erdgo --help | Show help |

Options

| Option | Description | Default | |--------|-------------|---------| | -r, --project <path> | Project root to scan | current working directory | | -p, --port <port> | Dashboard HTTP port | 3847 |

Examples

# Scan current folder
erdgo start

# Scan a specific app
erdgo start -r D:\laragon\www\HRGA-BTR

# Custom port
erdgo start -r ~/apps/my-api -p 3848

# Dashboard alias
erdgo ui -r ./my-project

Dashboard walkthrough

Home (/)

• Project root switcher
• AI provider / base URL / model / API key
• Status: framework detection, file counts, last ERD summary
• Generate ERD → opens full ERD view after generation
• Links to ERD, Use Case / Process, exports

ERD full view (/erd)

• Interactive React Flow canvas (tables + relationship lines)
• Regenerate ERD — rescan + heuristic + AI (if configured)
• Save edits — persist node positions and manual relationships
• Relayout tables — recompute layout so lines attach cleanly
• Fit view — zoom/pan to show all tables
• Screenshot — full diagram capture (not only the viewport)
• Export .sql / .md / .doc
• AI Chat — ask questions about the scanned project
• Generate diagrams — Use Case + Business Process from ERD

Diagrams (/diagrams)

• Mermaid Use Case and Business Process views derived from the ERD

Generate ERD with AI

From the UI

1. Configure AI on the dashboard (provider, base URL, model, API key)
2. Click Test AI (if available) to verify the connection
3. Open /erd and click Regenerate ERD
4. Wait for scan + AI analysis (can take 30s–several minutes on large projects)
5. Status line shows source mode, e.g. heuristic+ai · AI · Prisma

From the API

curl -X POST http://localhost:3847/api/erd/generate \
  -H "Content-Type: application/json" \
  -d "{\"useAi\": true}"

Disable AI (heuristic only):

curl -X POST http://localhost:3847/api/erd/generate \
  -H "Content-Type: application/json" \
  -d "{\"useAi\": false}"

What AI does

1. Heuristic pass parses Prisma / SQL / models / migrations
2. AI pass reads prioritized source files and returns extra entities/relationships
3. Soft-relation inference merges logical joins (lookups, embeds, app-level FKs)
4. Result is laid out as React Flow nodes/edges and saved under:

<project-root>/project-docs/diagrams/erd.json

Interactive ERD editor

| Action | How | |--------|-----| | Move a table | Drag the card | | Add relationship | Drag a blue handle from table A to table B (or to a field) | | Arrow direction | Arrow always points to the drop table (A→B vs B→A) | | Bend a line | Select the line, drag the yellow midpoint | | Reconnect ends | Drag the purple edge updater handles | | Edit label / fields | Select line → Edit line (or press E) | | Delete relationship | Select line → Delete line (or Del) | | Expand fields | Click +N more fields on a tall table | | Persist changes | Click Save edits |

Unsaved changes show an Unsaved badge. Always save before regenerating if you want to keep manual edits (regenerate rebuilds from source).

AI project chat

Open AI Chat on the ERD page.

Example questions:

• How does login work in this project?
• Which tables are involved in registration?
• List auth-related routes/endpoints
• Explain the main CRUD pattern (controller/service/route)
• Which entities relate to travel / orders / …?

Chat uses:

• Latest ERD summary
• Ranked source excerpts (routes, controllers, services, schema)
• Your configured AI model

If AI text fails, ERDGo returns a structured fallback summary from the scan.

Exports

From /erd (after an ERD exists):

| Export | Description | |--------|-------------| | Export .sql | DDL for selected dialect | | Export .md | Markdown documentation | | Export .doc | Simple document export | | Screenshot | Full-canvas image (PNG/JPEG/SVG) |

SQL dialects: mysql, postgres, sqlserver, oracle, sqlite.

API examples:

# SQL
curl -L "http://localhost:3847/api/erd/export/sql?dialect=mysql" -o erd-mysql.sql

# Markdown / doc
curl -L "http://localhost:3847/api/erd/export/doc?format=md" -o erd.md

AI provider setup

Dashboard

1. Open /
2. Section AI settings
3. Choose a preset or custom
4. Set Base URL, Model, API Key
5. Save AI config
6. Test connection

User AI config (saved outside the package)

When you click Save config on the dashboard, ERDGo stores provider / baseURL / model / apiKey in your user profile, not inside the npm package:

| OS | Path | |----|------| | Windows | %USERPROFILE%\.erdgo\config.json | | macOS / Linux | ~/.erdgo/config.json |

Example user file:

{
  "ai": {
    "provider": "openai",
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "model": "gpt-4o",
    "enabled": true
  }
}

The package install only ships a non-secret config.json (browser defaults, ERD limits, preset catalog).
API keys, base URL, and model are never written into the install directory, so npm i -g does not redistribute your credentials.

Environment variables

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o
AI_PROVIDER=openai

Env vars override the user config file when set.

Built-in presets

| Provider | Typical base URL | Example model | |----------|------------------|---------------| | OpenAI | https://api.openai.com/v1 | gpt-4o | | OpenRouter | https://openrouter.ai/api/v1 | openai/gpt-4o | | Ollama | http://127.0.0.1:11434/v1 | llama3.2 | | 9Router / custom | your gateway /v1 | your model id |

Any OpenAI-compatible Chat Completions API works.

Configuration

ERD scan limits (package config.json — non-secret)

{
  "erd": {
    "maxFiles": 280,
    "maxFileBytes": 800000
  }
}

Output folders (created under the scanned project)

project-docs/
  diagrams/     # erd.json, diagram artifacts
  exports/      # SQL / doc exports
  cache/
  docs/
  reports/
  screenshots/

Important

• User AI secrets live in ~/.erdgo/config.json (or %USERPROFILE%\.erdgo\config.json).
• Package config.json has no apiKey / personal baseURL / model.
• Scanned project root (-r) never owns provider secrets.

HTTP API

Base URL: http://localhost:3847 (or your port)

| Method | Path | Description | |--------|------|-------------| | GET | /api/health | Health check | | GET | /api/status | Project + AI + last ERD summary | | GET | /api/project-root | Current project root | | PUT | /api/project-root | Switch project root { "path": "..." } | | GET | /api/config | Public config (AI key masked) | | PUT | /api/config/ai | Update AI settings | | POST | /api/ai/test | Test AI connection | | GET | /api/erd | Load latest ERD + React Flow graph | | POST | /api/erd/generate | Generate ERD { "useAi": true } | | PUT | /api/erd | Save manual edits (nodes/edges) | | GET | /api/erd/export/sql?dialect=mysql | Export SQL | | GET | /api/erd/export/doc | Export documentation | | POST | /api/chat | Project Q&A { "question": "..." } | | POST | /api/diagrams/generate | Generate use-case / process diagrams |

Project structure

erdgo/
├── cli.ts                 # CLI entry (compiled to dist/cli.js)
├── index.ts               # Core entry
├── config.json            # Non-secret defaults only (presets / ERD limits)
├── package.json           # name: @akabaru21/erdgo, bin: erdgo
├── public/                # Static HTML sources
│   ├── index.html         # Dashboard
│   ├── erd.html           # Full ERD editor
│   └── diagrams.html      # Use case / process
├── src/
│   ├── server.ts          # Express dashboard + API
│   ├── erd-generator.ts   # Scan, heuristic, AI enhance, layout
│   ├── schema-scanner.ts  # File collection
│   ├── framework-detector.ts
│   ├── ai-client.ts       # OpenAI-compatible client
│   ├── project-chat.ts    # AI chat over project context
│   ├── erd-export.ts      # SQL / docs export
│   ├── process-diagrams.ts
│   └── pages/             # Generated HTML string modules
└── dist/                  # Build output (npm package runtime)

Source of truth is TypeScript. Runtime for the published CLI is dist/.

Development

# install deps
npm install

# run TypeScript directly
npm start
# or
npx tsx cli.ts start -r /path/to/project

# typecheck
npm run typecheck

# production build
npm run build
node dist/cli.js start -r /path/to/project

Editing the UI

1. Edit public/index.html or public/erd.html
2. Regenerate page modules (example):

node -e "const fs=require('fs');const html=fs.readFileSync('public/erd.html','utf8');fs.writeFileSync('src/pages/erd.ts','/** Auto-generated */\nexport function renderErdPage(): string {\n  return '+JSON.stringify(html)+';\n}\n');"

3. Rebuild / restart the server

How it works

┌─────────────────┐
│  Project root   │  (-r path)
└────────┬────────┘
         │
         v
┌─────────────────┐
│ Framework detect│  Prisma / Laravel / React / ...
└────────┬────────┘
         │
         v
┌─────────────────┐
│ Schema scanner  │  scoped roots, max files/bytes
└────────┬────────┘
         │
         v
┌─────────────────┐
│ Heuristic parse │  Prisma models, SQL DDL, FK patterns
└────────┬────────┘
         │
         v
┌─────────────────┐
│ AI enhance      │  logical joins from app code (optional)
└────────┬────────┘
         │
         v
┌─────────────────┐
│ React Flow layout│  nodes + relation edges
└────────┬────────┘
         │
         v
  project-docs/diagrams/erd.json
  Dashboard /erd interactive UI

Troubleshooting

| Problem | What to try | |---------|-------------| | erdgo not found | Run npm i -g . from the repo after npm run build, or use node dist/cli.js | | Port already in use | erdgo start -p 3848 or stop the process on 3847 | | Empty ERD | Ensure the project has Prisma/SQL/models; check /api/status → framework + warnings | | AI not used | Check enabled, API key, base URL; POST /api/ai/test; look at aiError in generate response | | Generate is slow | Large monorepos: lower erd.maxFiles, or run with "useAi": false first | | Manual lines disappear | Click Save edits before regenerate; regenerate rebuilds from source | | Screenshot only viewport | Use the built-in Screenshot button (full bounds capture), not browser print |

Publishing / GitHub

Suggested repository setup

git init
git add .
git commit -m "Initial commit: ERDGo AI ERD generator"
git branch -M main
git remote add origin https://github.com/<your-org>/erdgo.git
git push -u origin main

.gitignore recommendations

node_modules/
dist/
.env
*.log
project-docs/
.DS_Store

If you publish the npm package, do ship dist/ (via npm run build + files in package.json). For the GitHub source repo you may either commit dist/ or build in CI before publish.

npm publish checklist

1. Update version in package.json
2. Ensure bin.erdgo → dist/cli.js
3. npm run build
4. npm publish --access public (scoped packages need access flag)
5. Users install with:

npm i -g erdgo
erdgo start -r /path/to/project

Security

• Never commit real API keys
• Prefer env vars (OPENAI_API_KEY) in CI
• Keep AI secrets only in ~/.erdgo/config.json (never in the package install or public forks)

License

MIT (or your chosen license). Add a LICENSE file before publishing.

Support

• Open an issue on GitHub for bugs and feature requests
• Include: Node version, OS, framework of the scanned project, and /api/status summary (redact API keys)

ERDGo — scan · analyze · diagram · export.