Communitygithub.com

ihebEllouz/project-class-architect

Reverse-engineers a software repository into an accurate, interactive UML class diagram (one self-contained HTML file) - classes, interfaces, enums, attributes, methods, visibility, inheritance, associations, aggregation, composition, dependencies, multiplicities and database/ORM relationships, every element traced to its source file and line - with search, filters, a magnifying lens, in-diagram editing, change detection and SVG/PNG/JSON/HTML exports. Use when the user wants to visualize, document, understand or review a codebase's architecture, class model, domain or entity model (ERD), dependencies or dependency cycles, or asks for a UML class diagram of a project. Supports Java/Spring/JPA, Kotlin, TypeScript/JavaScript (Angular, NestJS, TypeORM), Python (Django, SQLAlchemy, dataclasses), C# (EF Core), Go (GORM), PHP (Doctrine, Laravel), SQL DDL and Prisma.

What is project-class-architect?

project-class-architect is a Claude Code agent skill that reverse-engineers a software repository into an accurate, interactive UML class diagram (one self-contained HTML file) - classes, interfaces, enums, attributes, methods, visibility, inheritance, associations, aggregation, composition, dependencies, multiplicities and database/ORM relationships, every element traced to its source file and line - with search, filters, a magnifying lens, in-diagram editing, change detection and SVG/PNG/JSON/HTML exports. Use when the user wants to visualize, document, understand or review a codebase's architecture, class model, domain or entity model (ERD), dependencies or dependency cycles, or asks for a UML class diagram of a project. Supports Java/Spring/JPA, Kotlin, TypeScript/JavaScript (Angular, NestJS, TypeORM), Python (Django, SQLAlchemy, dataclasses), C# (EF Core), Go (GORM), PHP (Doctrine, Laravel), SQL DDL and Prisma.

Works with✓Claude Code~Codex CLI~Cursor
Part ofDesign & UI
npx skills add https://github.com/ihebEllouz/project-class-architect/tree/HEAD
View original→Browse all skills

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentation

Project Class Architect

Turns a repository into an interactive UML class diagram that a developer can explore instead of reading hundreds of files. The analysis is evidence-based: every class, attribute, method and relationship in the diagram points to the file and line it came from. Nothing is invented; heuristic findings are labelled inferred.

All paths in this file are relative to the skill directory (the folder containing this SKILL.md).

Requirements

  • Node.js 18+ (node --version). The scripts have no dependencies: never run npm install for this skill.
  • Read access to the repository. The analysis never modifies source files; it only writes its output folder.
  • If Node.js is not available, use the fallback described at the end.

Workflow

1. Identify the repository

Use the absolute path of the project the user is talking about (usually the current workspace). Commands below run from the skill directory, so a relative path like . would point at the skill itself.

2. Generate the diagram

node scripts/class-architect.js generate "/absolute/path/to/repo"

Useful options (see the CLI reference for all of them):

NeedOption
Author in the footer--author "Name" --author-role "Software Engineer"
Diagram title--title "Billing Service"
Only part of a large repo--include "src/main/java/com/acme/billing/**" (repeatable)
Skip folders--exclude "legacy/**" (repeatable)
Restrict languages--languages java,sql
Analyse tests too--include-tests
Initial view / layout--view classes|er|overview|packages --layout grouped|layered|hierarchical|grid
Custom output folder--out "/path/to/output" (default <repo>/.class-architect)
Keep local paths out of the HTML--hide-root (disables "open in editor" links)

The command prints a JSON summary on stdout (progress goes to stderr). Exit codes: 0 success, 1 usage error, 2 no analysable source files, 3 model validation failed (nothing written), 4 internal error.

3. Check the result

Read the JSON summary (status, outputs, summary.counts, summary.insights, summary.edits, validation). Outputs written in the output folder:

  • diagram.html - the interactive diagram (open it in a browser; it works offline).
  • report.md / report.json - files scanned, classes, interfaces, enums, relationships, inferred relationships, unresolved references, excluded files with reasons, warnings, insights.
  • model.json - the UML model (single source of truth); overlay.json - user edits, when there are any.

If exit code is 2, adjust --include / --languages and say which folders were excluded and why (from the JSON details). If exit code is 3, report the validation errors; do not hand-edit the model to hide them.

For repositories with hundreds of classes, the diagram opens on the Overview (modules) and lets the user drill down into modules and packages; you can also generate focused diagrams with --include for one bounded context.

4. Present the diagram to the user

  • Give the path of diagram.html (and its file:// URL from outputs.diagramUrl). Do not try to launch a browser unless the user asks and your environment allows it.
  • Summarise only what the report says: numbers of classes / interfaces / enums / relationships, detected frameworks, dependency cycles, architecture findings, unresolved references and warnings. Quote class names exactly.
  • Mention that relationships marked inferred (naming conventions, Go structural typing) should be verified, and that derived table/column names are marked as derived.
  • Point out the main interactions: click a class or line to inspect it (with source file and line), search (/), filters, views (Overview, Packages, Classes, Database ER), the magnifying lens (L), edit mode (E), Insights, Export. Details: the interactive diagram guide.

5. Refresh after code changes

Run the same command again. It:

  • re-analyses only changed files (incremental cache),
  • keeps every user edit (from overlay.json and from edits the user saved into diagram.html with the Save button),
  • reports edits whose target disappeared from the code as orphaned (kept, never silently dropped) and edits that conflict with a source change,
  • highlights added / removed / modified classes compared with the previous run,
  • keeps a backup of the previous diagram (diagram.prev.html).

If the user downloaded a copy of the diagram elsewhere, pass it with --edits "/path/to/saved-diagram.html".

6. Optional: documentation sections

The diagram can show extra documentation below it (tables, flows, steps, enum grids, banner notes) using the original template's components. Only add facts you verified in the code, and cite the source file. Write a JSON file following the configuration guide and pass --notes notes.json.

Rules

  • Never modify, format or "fix" the analysed source code as part of this skill.
  • Never invent classes, members or relationships, and never present an inferred relationship as certain.
  • Never delete or overwrite overlay.json or a user-saved diagram.html: the CLI merges them for you.
  • The output folder .class-architect/ is generated; suggest adding it to .gitignore unless the user wants to commit the diagram.
  • Do not upload the diagram or the model anywhere: they may contain proprietary code structure.

Fallback when scripts cannot run

If Node.js 18+ is unavailable or command execution is not permitted:

  1. Read the relevant source files and write a model JSON by hand following the UML model reference. Include only elements you saw in the code, with source.file and source.line; set confidence: "inferred" for anything not explicit.
  2. Copy templates/viewer.html to the location where the user wants the diagram (for example class-diagram.html).
  3. In the copy, replace the text null inside <script type="application/json" id="pca-data">null</script> with {"model": <your model>, "overlay": null, "meta": {"title": "<project name>"}}, writing < as < inside the JSON.
  4. Alternatively, tell the user to open templates/viewer.html and drop the model.json onto the page.

The layout, interactions and exports then work in the browser exactly as for a generated diagram; only the automatic extraction, change detection and validation report are missing. Say clearly that the model was written by hand.

Other commands

node scripts/class-architect.js analyze "/abs/repo"                       # model + report, no HTML
node scripts/class-architect.js render --model model.json --out diagram.html
node scripts/class-architect.js validate --model model.json --html diagram.html
node scripts/class-architect.js diff --base old-model.json --head model.json
node scripts/class-architect.js edits --from saved-diagram.html --out overlay.json
node scripts/class-architect.js viewer --out viewer.html
node scripts/class-architect.js doctor

Reference files (read only when needed)

Related Skills

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community