Picture by Creator | Canva
Navigating and understanding giant codebases will be difficult, particularly for brand new builders becoming a member of a undertaking or when revisiting older repositories. Conventional strategies of understanding code buildings contain studying by means of quite a few information and documentation, which will be time-consuming and error-prone. GitDiagram provides an answer by changing GitHub repositories into interactive diagrams, offering a visible illustration of the codebase’s structure. This software helps in understanding advanced programs, and enhancing collaboration amongst growth groups. On this article, I’ll stroll you thru the step-by-step means of utilizing GitDiagram regionally. So, with none additional wait, let’s get began.
Step-by-Step Information to Utilizing GitDiagram Regionally
Step 1: Clone the GitDiagram repository
git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
cd gitdiagram
Step 2: Set up Dependencies
This fetches and installs dependencies into node_modules.
Earlier than operating pnpm set up, be sure you have Node.js and pnpm put in globally.
- To put in Node.js, obtain it from nodejs.org
- To put in pnpm, run the next command:
Step 3: Set Up Atmosphere Variables
Edit the .env file to incorporate your OpenAI / Anthropic /OpenRouter API key and, optionally, your GitHub private entry token.
Step 4: Begin Backend Companies
docker-compose up --build -d
The FastAPI server will probably be accessible at localhost:8000. You will notice the next message on the server facet.
{"message":"Howdy from GitDiagram API!"}
Step 5: Initialize the Database
Run the next instructions to arrange the database:
chmod +x start-database.sh
./start-database.sh
pnpm db:push
When prompted to generate a random password, enter sure. The Postgres database will begin in a container at localhost:5432.
Observe: Once I tried to run this command, I obtained this error:
sh: drizzle-kit: command not discovered
ELIFECYCLE Command failed.
WARN Native bundle.json exists, however node_modules lacking, did you imply to put in?
Seems I hadn’t put in drizzle-kit. So should you see this, simply run:
After that, pnpm db:push labored positive and gave me this output:
No config path supplied, utilizing default 'drizzle.config.ts'
Studying config file '/Customers/kanwal/Desktop/gitdiagram/drizzle.config.ts'
Utilizing 'postgres' driver for database querying
[✓] Pulling schema from database...
[✓] Modifications utilized
Step 6: Run the Frontend
Now you can entry the web site at localhost:3000 and edit the speed limits outlined in backend/app/routers/generate.py within the generate operate decorator. Let’s attempt to visualize the github repo of the fastapi library.
Frontend Interface:
Output:
Concluding Ideas
It is a nice thought and a very helpful repository. I’ve personally felt the necessity for one thing like this in my very own initiatives, so I recognize the hassle and imaginative and prescient behind it.
That mentioned, providing an unbiased opinion—there’s undoubtedly room for enchancment.
One recurring difficulty I bumped into was:
Syntax error in textual content mermaid model 11.4.
In response to the undertaking proprietor ahmedkhaleel2004, this error often means the LLM generated invalid Mermaid.js syntax.
I’ve tried addressing this difficulty in quite a few methods, however in the end, I discover that there isn’t a dependable repair—it’s principally a limitation of the LLM. If there have been a technique to validate Mermaid.js code, that might assist, however as of now, I’m undecided how.
He additionally famous that the present immediate (in `prompts.py`, particularly the third one which generates Mermaid code) already tries to implement appropriate syntax—but it surely’s not foolproof, and new syntax points nonetheless happen.
✅ A Resolution I Discovered On-line That Labored
Whereas digging by means of the GitHub Points, I got here throughout a workaround shared by one other person that really labored for me:
Add this to the customise diagram immediate:Ignore the syntax difficulty from Mermaid model 11.4.1 and regenerate the rest of the diagram.
Utilizing that line helped bypass the error. Regardless that some elements may nonetheless be lacking, it no less than produced a partial diagram—sufficient to provide a high-level understanding of the codebase.
Kanwal Mehreen Kanwal is a machine studying engineer and a technical author with a profound ardour for information science and the intersection of AI with drugs. She co-authored the e book “Maximizing Productiveness with ChatGPT”. As a Google Era Scholar 2022 for APAC, she champions variety and tutorial excellence. She’s additionally acknowledged as a Teradata Variety in Tech Scholar, Mitacs Globalink Analysis Scholar, and Harvard WeCode Scholar. Kanwal is an ardent advocate for change, having based FEMCodes to empower girls in STEM fields.
