Picture by Writer | Canva
Navigating and understanding giant codebases might 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 way of quite a few information and documentation, which might 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 instrument helps in understanding advanced programs, and enhancing collaboration amongst growth groups. On this article, I’ll stroll you thru the step-by-step strategy 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 working pnpm set up, ensure 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 Surroundings Variables
Edit the .env file to incorporate your OpenAI / Anthropic /OpenRouter API key and, optionally, your GitHub private entry token.
Step 4: Begin Backend Providers
docker-compose up --build -d
The FastAPI server shall be accessible at localhost:8000. You will note the next message on the server facet.
{"message":"Hey 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: After I tried to run this command, I received 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 if you happen to see this, simply run:
After that, pnpm db:push labored advantageous 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
This can be a nice concept and a extremely helpful repository. I’ve personally felt the necessity for one thing like this in my very own tasks, so I respect the hassle and imaginative and prescient behind it.
That stated, 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 finally, I discover that there isn’t a dependable repair—it’s largely a limitation of the LLM. If there have been a approach to validate Mermaid.js code, that might assist, however as of now, I’m unsure how.
He additionally famous that the present immediate (in `prompts.py`, particularly the third one which generates Mermaid code) already tries to implement right syntax—however it’s not foolproof, and new syntax points nonetheless happen.
✅ A Resolution I Discovered On-line That Labored
Whereas digging by way of the GitHub Points, I got here throughout a workaround shared by one other person that truly 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. Though some parts would possibly nonetheless be lacking, it at the very least produced a partial diagram—sufficient to offer a high-level understanding of the codebase.
Kanwal Mehreen Kanwal is a machine studying engineer and a technical author with a profound ardour for knowledge 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 range 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 ladies in STEM fields.
