GitDiagram

GitDiagram is a tool that converts public or private GitHub repositories into interactive architecture diagrams. Unlike simple folder visualizers, it uses AI to analyze the repository tree and README to generate a system-level graph.

Key Capabilities:

• Architecture-first diagrams: Generates a graph based on system logic rather than just folder structures.
• Interactive links: Components in the diagram link directly to their real files or directories on GitHub.
• Streaming generation: Provides real-time architecture explanations while the graph is being planned.
• Export options: Users can copy the Mermaid source or download the diagram as a PNG.
• Private repository support: Users can provide a GitHub personal access token (PAT) locally in the browser to diagram private repos.

If the Vercel production deployment becomes unavailable, GitDiagram can be recovered using Railway. The repository contains a Dockerfile and railway.json configured to package the existing Next.js application (using output: "standalone") for Railway.

Because the application is self-contained, recovery does not require a separate backend implementation, CORS configuration, or data migration. The application uses /api/healthz for deployment health checks and respects the platform-provided PORT.

To run GitDiagram locally, ensure you have bun installed. Follow these steps:

1. Clone the repository:

   git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
   cd gitdiagram

2. Install dependencies:

   bun install

3. Configure environment variables:

   cp .env.example .env

4. Start the development server:

   bun run dev

Access the application at http://localhost:3000.

Required Configuration: You must configure Cloudflare R2, Upstash, and an AI provider (OpenAI or OpenRouter via AI_PROVIDER) in your .env file. While optional, providing a GitHub PAT or GitHub App is recommended to increase GitHub API limits.

Once the incident is resolved and you wish to return to the primary Vercel deployment, follow these steps:

1. Verify Vercel Health: Ensure https://gitdiagram.com/api/healthz is responsive and a small production generation works.
2. Restore Routing: Restore gitdiagram.com to the intended Vercel deployment if any routing changes were made.
3. Cleanup Railway: Remove temporary Railway domains and delete the Railway service.
4. Final Audit: Confirm the Railway project has no active services and the DNS zone contains no Railway records.

Use the following commands to run the project's validation suite, which includes linting, type checking, and tests (covering Mermaid parser contracts, API routes, storage concurrency, and more):

bun run lint
bun run typecheck
bun run test
bun run build

Before submitting a pull request, run the following commands to ensure code quality and correctness:

bun run lint
bun run typecheck
bun run test
bun run build

The primary deployment target is Vercel. The project uses Bun as both the package manager and the server runtime for Route Handlers.

Key Deployment Details:

• The project uses runtime = "nodejs" declarations for route-level server runtimes.
• The project-level bunVersion setting ensures Vercel executes Functions with Bun.
• Ensure all variables from .env.example are added to your Vercel project settings before deploying.

Deployment Commands

vercel deploy
vercel deploy --prod

Once configured, you can start the application in development or production mode.

Development Mode

Run the following command to start the Next.js development server:

bun run dev

The application will be available at http://localhost:3000. Note that Next.js Route Handlers under /api/generate/* run within this same process.

Production Mode (Local Check)

To test the production build locally:

bun run build
bun run start

To diagram a private repository, select the Private Repos option in the application header. You must provide a fine-grained GitHub personal access token (PAT) that has read access to the target repository.

Security Note: The token is sent only with the relevant same-origin request and is never embedded in public diagram links. Private artifacts are stored in a separate, protected R2 storage namespace derived with a server-side secret.

The GenerationSessionAudit interface provides a complete audit trail of a diagram generation attempt. It tracks the lifecycle from idle through running to succeeded or failed.

Key fields for debugging or monitoring include:

• status: Current state (idle | running | succeeded | failed).
• graphAttempts: An array of GraphAttemptAudit objects, useful for seeing how many retries were required to produce a valid graph.
• validationError: Contains error details if the generated graph failed schema validation.
• stageUsages: Detailed usage metrics for different generation stages.
• timeline: A chronological list of GenerationTimelineEvent entries.