[AI in open source] GitDiagram: AI helps you understand the architecture of any code base

Product positioning ?

"Convert any GitHub repository into an interactive system design/architecture diagram and visualize the project structure with one click."

GitDiagram is an open source tool that can automatically convert the GitHub repository structure into an interactive system architecture diagram to help developers quickly understand the project architecture. It not only displays the overall structure of the project, but also allows users to click on components to directly navigate to source files and related directories, greatly improving code understanding and team collaboration efficiency.

Its Github address is: 

https://github.com/ahmedkhaleel2004/gitdiagram

Key Features ✨

• Smart conversion: instantly convert any GitHub repository into a system design diagram.
• Interactive components: Click on the component in the diagram to jump directly to the source file and directory.
• Private repository support: Access private code repositories via GitHub token.
• Custom charts: Customize chart style and content through user instructions.
• URL shortcut: Just replace "hub" with "diagram" in the GitHub URL to view its architecture diagram.

Use cases ?

• Getting started with a new project: quickly understand the overall architecture of an unfamiliar code base.
• Team collaboration: Clearly present project structure to team members and facilitate communication.
• Documentation: Generate visual diagrams for technical documentation.
• Code review: Assist the code review process with an overall structure diagram.
• Teaching and training: Explain system architecture design concepts to newcomers.

How to use it?

The following uses the analysis of an open source project as an example to introduce how to use GitDiagram to visualize the project architecture.

Step 1: Visit the GitDiagram website (https://gitdiagram.com/) and enter the address of the GitHub repository you want to analyze.

Step 2: Wait for AI to analyze the warehouse structure. This process may take a few seconds to a few minutes depending on the size of the warehouse. If there is a cache, it will return in seconds; if not, you have to wait. Take the recently popular MCP TypeScript SDK as an example:

https://github.com/modelcontextprotocol/typescript-sdk

Step 3: View the generated architecture diagram to see the overall structure of the system and the relationship between the components.

Each component is interactive. Click it to jump to the corresponding source code file or directory, so you can have a deeper understanding of the specific implementation:

Step 4: The generated chart is Mermaid.js code, which can be copied directly; or exported as a PNG image.

How does AI understand code architecture?

The core behind GitDiagram is the powerful LLM. How does it analyze and understand complex code bases? This process is divided into three key steps:

1. Warehouse data extraction : The system first obtains the warehouse's file tree structure, README content, and other key metadata from the GitHub API. These raw data become the input source for AI.

2. Multi-stage intelligent analysis : GitDiagram uses a carefully designed three-stage prompt engineering processing pipeline:

• Finally, the system sends the explanation and component mapping information to the AI ​​model.
• Use SYSTEM_THIRD_PROMPT to instruct the AI ​​to generate standard compliant Mermaid.js chart code
• The generated chart contains rich interactive events, allowing users to click on any component to jump directly to the corresponding file or directory on GitHub
• The system automatically handles these click events, intelligently determines whether the path is a file or a directory, and constructs the correct GitHub URL

• Stage 3: Generate Mermaid chart  ?

• The system passes the explanation generated in the first stage back to the AI ​​model
• Instruct the AI ​​to accurately map each identified component to an actual file or directory path via SYSTEM_SECOND_PROMPT
• This mapping process is a key step in creating interactive diagrams, as it links the visual components to the actual code files.
• AI analyzes the directory structure to determine which files best represent the functionality of a specific component

• Phase 2: Component Mapping  ?

• The system first uses the GitHub API to obtain the complete file tree and README content of the code repository
• Intelligent filtering algorithm automatically removes irrelevant files (such as node_modules, image resources, etc.)
• The LLM (now using OpenAI o3-mini, originally using Claude-3.5-Sonnet) model analyzes this streamlined data and generates a detailed explanation of the codebase structure
• This step uses SYSTEM_FIRST_PROMPT in prompts.py to guide AI to identify key components and system architecture from the file structure

• Phase 1: Analyze the code base structure  ?

The entire generation process uses streaming processing to return progress updates, and users can see the generation process of the chart from scratch in real time, which is also a major feature of GitDiagram. The system also implements an intelligent caching mechanism to avoid repeated generation of charts for the same code base, greatly improving efficiency. For particularly large code bases, GitDiagram also provides an API key option, allowing users to use their own OpenAI keys for processing, breaking through the default restrictions.

1. Dynamic rendering and interaction : The front end uses Mermaid.js to convert the generated chart code into visual graphics and add interactivity so that users can click on any component to gain in-depth understanding.

It is worth mentioning that GitDiagram initially used Claude 3.5 Sonnet for code understanding, and has now switched to OpenAI's o3-mini model, which performs well in processing large code bases. AI can not only recognize file structures, but also understand dependencies between codes, and even infer design patterns and architectural decisions.

Technology stack and implementation ?

GitDiagram adopts a modern full-stack architecture design:

• Front-end : Built on Next.js 15, TypeScript, Tailwind CSS, and ShadCN UI components, using the App Router pattern to organize code and improving performance through Server Components and Server Actions.

• Backend : Use FastAPI (Python) to handle warehouse data extraction and AI processing workflows, including complex prompt engineering and API call management.

• Database : Use PostgreSQL with Drizzle ORM for type-safe database operations, and use Neon Database to provide serverless PostgreSQL services.

• AI integration : Call large language models through APIs to analyze code bases and generate architecture diagrams, using complex prompt engineering to extract accurate information.

• Deployment : The front-end is deployed on Vercel, and the back-end runs on EC2 instances, using GitHub Actions to implement the CI/CD process.

AI-assisted development practice ?

By looking at the project code, we found that the development process of GitDiagram relied heavily on the AI ​​programming tool Cursor, which is an excellent practice example of "vibe coding"..cursor/rulesThe directory contains the contextual rules set by the author for the AI ​​assistant to help AI better understand and participate in project development.

The author issummary.mdcThe document contains a carefully written project overview that provides a comprehensive background for Cursor’s AI assistant:

• Project Overview : Clearly describes the core functions and value of GitDiagram
• Key features : Lists the main functional points of the system
• Technology stack : details all the technologies used in the front-end and back-end
• Architecture design : divided into four modules: front-end, back-end, database and AI integration
• Project structure : specifies the purpose of each directory
• Development Setup : Provides a guide to setting up the environment

This approach greatly improves the AI ​​assistant's ability to understand the project, allowing it to provide more accurate and valuable code suggestions. By letting AI understand the entire project's architecture and technology selection, developers can get code generation and problem solutions that are more in line with the project context.

Interestingly, GitDiagram itself is an AI tool that helps developers understand the code base, and its development process also makes full use of the power of AI. This "AI-assisted development of AI tools" model demonstrates a new paradigm for modern software development and also verifies the author's deep understanding and flexible application of AI technology.

For developers who want to try AI-assisted programming, the development method of GitDiagram provides a template worth referring to: creating a detailed project overview document, clarifying the technology stack and architectural design, and using a standardized code structure, all of which can help AI better understand the project context and provide more accurate assistance.

Local deployment ?

If you want to run GitDiagram in your own environment, you can follow these steps:

# Clone the repositorygit  clone  https://github.com/ahmedkhaleel2004/gitdiagram.gitcd  gitdiagram
# Install dependenciespnpm install
# Configure environment variablescp  .env.example . env# Edit the .env file and add the necessary API key
# Start the backenddocker-compose up --build -d
# Start the local databasechmod  +x start-database.sh./start-database.sh
# Initialize the database structurepnpm db:push
# Start the front-end development serverpnpm-dev

After completing the above steps, you can visitlocalhost:3000Use GitDiagram. If you need to view and manipulate the database, you can runpnpm db:studio.

Summary thoughts?

GitDiagram makes codebase visualization easier than ever before. It uses the power of AI to automatically analyze and understand code structure, providing developers with a powerful tool. However, there are some areas that need improvement:

• Processing of very large warehouses can take a long time, and optimizing the speed of analysis is a challenge.
• The resulting graphs can sometimes be too complex and require smarter simplification algorithms.
• There is still room for improvement in understanding the features of specific programming languages, such as better identification of design patterns in different frameworks.

With the continuous development of AI technology, GitDiagram may make greater breakthroughs in code understanding in the future, allowing developers to understand complex system architectures more easily and improve development efficiency.

Do you often have trouble understanding the code structure of a new project? Why not try GitDiagram and let AI help you easily decipher the mysteries of the code base!