Full Stack UML Diagram Generator

@dawidkrasinski/uml-diagram-generator is a full-stack package that analyzes TypeScript/JavaScript code and generates interactive UML diagrams.

Two parts in one package:

• Backend (lib/): AST parser, code analysis, UML graph generation
• Frontend (template/): Next.js UI for interactive diagram viewing

🚀 What does this project do

The package performs the entire pipeline from raw code to visual diagram:

1. File Collection: Recursively searches directories and collects .ts, .js, .tsx, .jsx, .mjs, .cjs files, excluding node_modules, .git, dist, .next.
2. Parsing and Analysis: Parses AST using Babel and extracts classes, functions, global variables, inheritance, methods, properties.
3. Graph Generation: Converts metadata to UML structure (nodes + relations).
4. Visualization: Displays interactive diagram in the browser with filtering and navigation features.

🧱 Project Architecture

uml-diagram-generator/
├── lib/                           # Backend — parser and generator
│   ├── files/FileCollector.ts     # File collection from filesystem
│   ├── parser/ParserFacade.ts     # AST parser + entity extractors
│   ├── parser/extractors/         # ClassExtractor, FunctionExtractor, etc.
│   ├── graph/GraphGenerator.ts    # Conversion to UML graph
│   └── pipeline/CodeAnalyzerService.ts # Orchestration of entire analysis
├── template/                      # Frontend — Next.js UI
│   ├── app/page.tsx               # Main screen (graph + sidebar)
│   ├── app/api/route.ts           # GET /api endpoint (runs analyzer)
│   ├── components/graph/          # Interactive graph rendering
│   └── components/FileTreeSidebar # File tree and entity filtering
├── tests/                         # Unit tests (lib)
├── index.ts                       # API entry point
└── README.md                      # This file

✅ Features

Backend (lib/)

• ✓ Recursive source file collection
• ✓ Extension filtering (.ts, .js, .tsx, .jsx, .mjs, .cjs)
• ✓ AST parsing with Babel
• ✓ Class extraction (with access modifiers: private/protected/public)
• ✓ Function extraction, global variables, React components
• ✓ Inheritance and relation definitions (extends, implements)
• ✓ UML Graph structure (nodes + relations)

Frontend (template/)

• ✓ Interactive UML graph (XY Flow + ELK Layout)
• ✓ Sidebar with file tree for filtering
• ✓ Entity activation and auto-fit view
• ✓ VS Code integration (code -g for opening files)
• ✓ Responsive UI (Tailwind CSS)

⚙️ Installation and Running

For Users (Installation as a Package)

In any project:

npm install --save-dev @dawidkrasinski/uml-diagram-generator

The package will automatically add a script to the host's package.json:

{
  "scripts": {
    "generate:uml": "uml ."
  }
}

Then run:

npm run generate:uml

This will open the full UI (Next.js frontend) analyzing the current directory.

If you only want machine-readable output or the UI cannot start in your environment, use the CLI fallback:

uml . --json

For Developers (Working with Repository)

git clone <repo>
cd uml-diagram-generator
npm install

Running the entire pipeline (backend + frontend):

npm start

Builds the library and runs the Next.js UI on http://localhost:3000

Running separately:

Frontend (Next.js dev server):

npm --prefix ./template run dev

Backend (build lib):

npm run build

CLI (JSON output without UI):

node dist/index.js /path/to/project --json

Programmatic API

import { main } from "@dawidkrasinski/uml-diagram-generator";

const graph = main("/path/to/project");
console.log(JSON.stringify(graph, null, 2));

Frontend API

GET /api

Runs the analyzer and returns the graph:

{
  "graph": {
    "nodes": [...],
    "relations": [...]
  }
}

Optional configuration via environment variable:

UML_TARGET_PATH=/custom/path npm --prefix ./template run dev

Bundled frontend stack:

• [email protected]
• [email protected]
• [email protected]

POST /api/open-file

Opens a file in VS Code (only files from the project):

curl -X POST http://localhost:3000/api/open-file \
  -H "Content-Type: application/json" \
  -d '{"pathParts":["src","app","page.tsx"]}'

🧭 Data Model

The /api endpoint returns UMLGraph:

{
  "nodes": [
    {
      "id": "1",
      "name": "UserService",
      "type": "class",
      "attributes": ["user", "db"],
      "methods": ["getUser", "saveUser"],
      "path": ["src", "services", "UserService.ts"]
    },
    {
      "id": "2",
      "name": "PrismaClient",
      "type": "class",
      "attributes": [],
      "methods": [],
      "path": ["node_modules", "@prisma", "client"]
    }
  ],
  "relations": [
    {
      "id": "rel-1",
      "from": "1",
      "to": "2",
      "type": "dependency"
    }
  ]
}

Node Types:

• class — TypeScript/JavaScript class
• function — top-level function
• api-endpoint — API endpoint in Next.js
• variable — global variable
• component — React component

🧪 Tests

Run unit tests (lib):

npm test

Watch mode:

npm test -- --watch

Coverage:

npm test -- --coverage

🏗️ Structure for Developers

Backend Extensions

Add new file extensions in lib/files/FileCollector.ts:

const SUPPORTED_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];

Add extraction logic in lib/parser/extractors/:

// New file: ClassExtractorCustom.ts
export function extractCustomEntities(node: t.ClassDeclaration): Entity {
  // ...
}

Frontend Extensions

Add new components in template/components/:

// New UML node
export function UMLCustomElement({ node }: Props) {
  return <div>{node.name}</div>;
}

Integrate with lib/Generator.ts for type coordination.

📌 Important Notes

• Parser skips files that fail to parse — logs warnings to stderr
• Inheritance relations are created only between classes in the same parsed set
• Frontend filters the view based on the file tree — graph shows only active entities
• The /api/open-file endpoint validates paths — only files in the project directory

🛠️ Troubleshooting

| Problem | Solution | | ----------------------------------- | ---------------------------------------------------------------------------------------- | | code: command not found | Install VS Code CLI (Cmd+Shift+P → "install code command") | | Frontend shows empty graph | Check UML_TARGET_PATH — does it point to the code folder? | | UI start fails after package update | Delete .uml-diagram-generator-runtime/ in the target project and run the command again | | Build fails | Delete dist/ and try npm run build again | | Files are not being parsed | Parser logs warnings — check console output |

📚 More Information

• Frontend: template/README.md
• Backend API: lib/Generator.ts
• Parser: lib/parser/ParserFacade.ts
• Tests: tests/

❤️ License

Open source. Use and modify freely.