ark1332331/gitdiagram

Purpose and Entry Points

GitDiagram converts a GitHub repository into an interactive Mermaid architecture diagram, with source/directory links and Mermaid/PNG export. The primary runtime is a Next.js application: landing input at src/app/page.tsx, repository result route at src/app/[username]/[repo]/page.tsx, and streaming generation API at src/app/api/generate/stream/route.ts. A FastAPI backend remains as an optional legacy deployment path.

User and Diagram UI

The repository page’s client controller coordinates loading, generation state, rendering, and user interactions in src/app/[username]/[repo]/repo-page-client.tsx. Diagram display and clickable Mermaid rendering are centered on src/components/mermaid-diagram.tsx; export behavior is separated into src/features/diagram/export.ts and src/hooks/diagram/useDiagramExport.ts. GitHub URL parsing, including .git suffix normalization, belongs to src/features/diagram/github-url.ts.

Streaming Generation Boundary

The browser calls the generation endpoint through src/features/diagram/api.ts and consumes server-sent events via src/features/diagram/sse.ts / src/hooks/diagram/useDiagramStream.ts. src/app/api/generate/stream/route.ts is the key boundary: it validates request inputs, orchestrates repository retrieval and model generation, and streams incremental diagram/result events back to the UI. src/app/api/generate/cost/route.ts exposes generation cost estimation separately.

Server-Side Repository Analysis

The Next.js server generation domain is organized under src/server/generate/. src/server/generate/github.ts retrieves GitHub repository structure/content, using a user-provided PAT or configured token for private repositories and rate-limit relief. src/server/generate/prompts.ts defines the model instructions for turning repository material into architecture-oriented Mermaid. src/server/generate/format.ts normalizes generated output for the API/UI contract.

AI, Mermaid, and Cost Services

src/server/generate/openai.ts invokes an OpenAI-compatible Chat Completions provider, configured for providers such as DeepSeek through environment settings. Model selection/configuration is centralized in src/server/generate/model-config.ts; token/cost logic is in src/server/generate/pricing.ts. Generated Mermaid is validated or processed in src/server/generate/mermaid.ts before presentation, creating a boundary between untrusted LLM output and diagram rendering.

Persistence and Server Actions

Postgres persistence is accessed through Drizzle in src/server/db/index.ts with schema definitions in src/server/db/schema.ts. Repository/cache-oriented server actions live in src/app/_actions/repo.ts and src/app/_actions/cache.ts. Database failures are intentionally noncritical for page availability per the local-reproduction design; generation relies primarily on GitHub and the model provider.

Optional Legacy Backend and Infrastructure

The optional FastAPI implementation mirrors the generation pipeline: application entrypoint backend/app/main.py, generation router backend/app/routers/generate.py, and GitHub/OpenAI/Mermaid services under backend/app/services/. It can be selected with public runtime environment flags rather than the built-in Next.js API. Local infrastructure includes Dockerized PostgreSQL via docker-compose.yml or start-database.sh; the legacy backend has its own container definition at backend/Dockerfile. Deployment automation is represented by .github/workflows/deploy.yml.