[ { "path": ".github/FUNDING.yml", "content": "# These are supported funding model platforms\n\ngithub: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]\npatreon: # Replace with a single Patreon username\nopen_collective: # Replace with a single Open Collective username\nko_fi: ahmedkhaleel2004\ntidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel\ncommunity_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry\nliberapay: # Replace with a single Liberapay username\nissuehunt: # Replace with a single IssueHunt username\nlfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry\npolar: # Replace with a single Polar username\nbuy_me_a_coffee: # Replace with a single Buy Me a Coffee username\nthanks_dev: # Replace with a single thanks.dev username\ncustom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n pull_request:\n push:\n branches:\n - main\n\njobs:\n frontend:\n runs-on: ubuntu-latest\n env:\n POSTGRES_URL: postgresql://postgres:password@localhost:5432/gitdiagram\n steps:\n - uses: actions/checkout@v4\n - name: Setup pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 10.30.0\n - name: Setup Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: \".nvmrc\"\n cache: \"pnpm\"\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n - name: Lint\n run: pnpm lint\n - name: Typecheck\n run: pnpm typecheck\n - name: Frontend tests\n run: pnpm test\n - name: Build\n run: pnpm build\n\n backend:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Setup Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n - name: Install uv\n run: pip install uv==0.5.24\n - name: Sync backend dependencies\n run: cd backend && uv sync --frozen --no-install-project\n - name: Import sanity\n run: cd backend && uv run python -m compileall app\n - name: Backend tests\n run: cd backend && uv run pytest -q\n" }, { "path": ".github/workflows/deploy.yml", "content": "name: Deploy to EC2\n\non:\n # Disabled for automatic deploys after migrating to Next.js/Vercel backend.\n # Kept as legacy workflow for historical reference / manual fallback use.\n workflow_dispatch:\n inputs:\n confirm_legacy_ec2_deploy:\n description: \"Type true to run legacy EC2 deploy\"\n required: false\n default: \"false\"\n\njobs:\n deploy:\n if: ${{ github.event.inputs.confirm_legacy_ec2_deploy == 'true' }}\n runs-on: ubuntu-latest\n\n # Add concurrency to prevent multiple deployments running at once\n concurrency:\n group: production\n cancel-in-progress: true\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Deploy to EC2\n uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5\n with:\n host: ${{ secrets.EC2_HOST }}\n username: ubuntu\n key: ${{ secrets.EC2_SSH_KEY }}\n script: |\n cd ~/gitdiagram\n git fetch origin main\n git checkout main\n git pull --ff-only origin main\n sudo chmod +x ./backend/nginx/setup_nginx.sh\n sudo ./backend/nginx/setup_nginx.sh\n chmod +x ./backend/deploy.sh\n ./backend/deploy.sh\n" }, { "path": ".gitignore", "content": "# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.\n\n# dependencies\n/node_modules\n/.pnp\n.pnp.js\n\n# testing\n/coverage\n\n# database\n/prisma/db.sqlite\n/prisma/db.sqlite-journal\ndb.sqlite\n\n# next.js\n/.next/\n/out/\nnext-env.d.ts\n\n# production\n/build\n\n# misc\n.DS_Store\n*.pem\n\n# debug\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n.pnpm-debug.log*\n\n# local env files\n# do not commit any .env files to git, except for the .env.example file. https://create.t3.gg/en/usage/env-variables#using-environment-variables\n.env\n.env*.local\n.env-e\n\n# vercel\n.vercel\n\n# typescript\n*.tsbuildinfo\n\n# idea files\n.idea\n\n__pycache__/\nvenv\nbackend/.venv\n.venv\n\n# vscode\n.vscode/\n" }, { "path": ".nvmrc", "content": "22\n" }, { "path": "CLAUDE.md", "content": "# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nGitDiagram converts GitHub repositories into interactive Mermaid diagrams using a 3-stage LLM pipeline. It's a full-stack app with a Next.js frontend (Vercel) and FastAPI backend (Railway).\n\n## Commands\n\n### Frontend (pnpm, Node 22)\n```bash\npnpm install # Install dependencies\npnpm dev # Start Next.js dev server (Turbo)\npnpm build # Production build\npnpm lint # ESLint\npnpm check # Type-check + lint\npnpm test # Vitest (frontend unit tests)\npnpm format:write # Prettier formatting\n```\n\n### Backend (Python 3.12, uv)\n```bash\ncd backend\nuv sync --no-install-project # Install pinned deps into .venv\nuv run pytest -q # Run all backend tests\nuv run pytest tests/path/test_file.py::test_name # Run single test\nuv run python -m compileall app # Compile check\n```\n\n### Database\n```bash\npnpm db:push # Push schema changes to Postgres\npnpm db:generate # Generate Drizzle migration files\npnpm db:studio # Open Drizzle Studio\n```\n\n### Local Development\n```bash\n# Start local Postgres\n./start-database.sh\n\n# Start FastAPI backend (Docker, recommended for production parity)\ndocker-compose up --build -d\ndocker-compose logs -f api\n\n# OR start FastAPI backend directly\npnpm dev:backend # runs uvicorn via uv\n```\n\nTo route the Next.js frontend to a local FastAPI backend, set in `.env`:\n```\nNEXT_PUBLIC_USE_LEGACY_BACKEND=true\nNEXT_PUBLIC_API_DEV_URL=http://localhost:8000\n```\n\n## Architecture\n\n### Dual-Backend Design\nThe app supports two generation backends controlled by `NEXT_PUBLIC_USE_LEGACY_BACKEND`:\n- **FastAPI** (`backend/`) on Railway — primary production path\n- **Next.js Route Handlers** (`src/app/api/generate/`) — legacy fallback\n\nBoth expose the same SSE streaming API. The frontend (`src/features/diagram/api.ts`) routes to one or the other transparently.\n\n### 3-Stage LLM Pipeline\nDiagram generation uses three sequential OpenAI streaming calls:\n1. **Explanation** — understands the repo structure\n2. **Component Mapping** — maps components to file paths (XML tags extracted)\n3. **Mermaid Diagram** — generates Mermaid syntax with click events\n\nAfter stage 3, Mermaid syntax is validated (via `backend/scripts/validate_mermaid.mjs` or `src/server/generate/mermaid.ts`) and auto-fixed for up to 3 attempts if invalid. Prompts live in `backend/app/prompts.py` and `src/server/generate/prompts.ts`.\n\n### Streaming State Machine\nSSE events flow through states: `idle → started → explanation_* → mapping_* → diagram_* → diagram_fix_* → complete`\n\nFrontend: `src/hooks/diagram/useDiagramStream.ts` manages state.\nBackend: `backend/app/routers/generate.py` emits events.\n\n### GitHub Authentication Priority\n1. User-supplied PAT (from localStorage)\n2. `GITHUB_PAT` env var\n3. GitHub App (CLIENT_ID + PRIVATE_KEY + INSTALLATION_ID)\n\n### Caching\nGenerated diagrams are cached in PostgreSQL (`gitdiagram_diagram_cache` table, schema at `src/server/db/schema.ts`) keyed by `(username, repo)`. Server action: `src/app/_actions/cache.ts`.\n\n### Path Aliases\nTypeScript uses `~/*` → `./src/*`.\n\n## Key File Locations\n\n| Concern | Frontend | Backend |\n|---|---|---|\n| Prompts | `src/server/generate/prompts.ts` | `backend/app/prompts.py` |\n| GitHub client | `src/server/generate/github.ts` | `backend/app/services/github_service.py` |\n| OpenAI streaming | `src/server/generate/openai.ts` | `backend/app/services/openai_service.py` |\n| Mermaid validation | `src/server/generate/mermaid.ts` | `backend/app/services/mermaid_service.py` |\n| Stream endpoint | `src/app/api/generate/stream/` | `backend/app/routers/generate.py` |\n| DB schema | `src/server/db/schema.ts` | — |\n| Frontend API client | `src/features/diagram/api.ts` | — |\n| Main diagram hook | `src/hooks/useDiagram.ts` | — |\n\n## Environment Variables\n\nMinimum required (see `.env.example` for full list):\n- `POSTGRES_URL` — Neon serverless Postgres\n- `OPENAI_API_KEY` — used for all generation stages\n- `GITHUB_PAT` — optional but avoids GitHub rate limits\n- `OPENAI_MODEL` — single model for all three pipeline stages\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2024 Ahmed Khaleel\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "[![Image](./docs/readme_img.png \"GitDiagram Front Page\")](https://gitdiagram.com/)\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n[![Kofi](https://img.shields.io/badge/Kofi-F16061.svg?logo=ko-fi&logoColor=white)](https://ko-fi.com/ahmedkhaleel2004)\n\n# GitDiagram\n\nTurn any GitHub repository into an interactive diagram for visualization in seconds.\n\nYou can also replace `hub` with `diagram` in any Github URL to access its diagram.\n\n## 🚀 Features\n\n- 👀 **Instant Visualization**: Convert any GitHub repository structure into a system design / architecture diagram\n- 🎨 **Interactivity**: Click on components to navigate directly to source files and relevant directories\n- ⚡ **Fast Generation**: Powered by OpenAI GPT-5.4 mini (configurable) for quick and accurate diagrams\n- 🖼️ **Export Options**: Copy Mermaid code or download the generated diagram as PNG\n- 🌐 **API Access**: Public API available for integration (WIP)\n\n## ⚙️ Tech Stack\n\n- **Frontend**: Next.js, TypeScript, Tailwind CSS, ShadCN\n- **Backend**: FastAPI (Railway), with Next.js Route Handlers available as a fallback path\n- **Database**: PostgreSQL (with Drizzle ORM)\n- **AI**: OpenAI GPT-5.4 mini (via `OPENAI_MODEL`)\n- **Deployment**: Vercel (frontend) + Railway (backend)\n- **CI/CD**: GitHub Actions\n- **Analytics**: PostHog, Api-Analytics\n\n## 🔄 Backend Architecture Update\n\nGitDiagram now runs its primary generation backend on FastAPI (deployed on Railway).\n\nFrontend calls are routed to the external backend by setting:\n- `NEXT_PUBLIC_USE_LEGACY_BACKEND=true`\n- `NEXT_PUBLIC_API_DEV_URL=https://`\n\nThe variable name contains \"LEGACY\" for backward compatibility, but it now points to the primary external backend in production.\n\n## 🤔 About\n\nI created this because I wanted to contribute to open-source projects but quickly realized their codebases are too massive for me to dig through manually, so this helps me get started - but it's definitely got many more use cases!\n\nGiven any public (or private!) GitHub repository it generates diagrams in Mermaid.js with OpenAI's GPT-5.4 mini! (Previously Claude 3.5 Sonnet)\n\nI extract information from the file tree and README for details and interactivity (you can click components to be taken to relevant files and directories).\n\nMost of what you might call the \"processing\" of this app is done with prompt engineering and a 3-step streaming pipeline in the FastAPI backend under `/backend`.\n\n## 🔒 How to diagram private repositories\n\nYou can simply click on \"Private Repos\" in the header and follow the instructions by providing a GitHub personal access token with the `repo` scope.\n\nYou can also self-host this app locally (backend separated as well!) with the steps below.\n\n## 🛠️ Self-hosting / Local Development\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/ahmedkhaleel2004/gitdiagram.git\ncd gitdiagram\n```\n\n2. Install dependencies\n\n```bash\npnpm i\n```\n\n3. Set up environment variables (create .env)\n\n```bash\ncp .env.example .env\n```\n\nThen edit the `.env` file with your OpenAI API key and optional GitHub personal access token.\n\n4. Start local database\n\n```bash\nchmod +x start-database.sh\n./start-database.sh\n```\n\nWhen prompted to generate a random password, input yes.\nThe Postgres database will start in a container at `localhost:5432`\n\n5. Initialize the database schema\n\n```bash\npnpm db:push\n```\n\nYou can view and interact with the database using `pnpm db:studio`\n\n6. Run frontend\n\n```bash\npnpm dev\n```\n\nYou can now access the website at `localhost:3000`.\n\nRun FastAPI backend (recommended if you want parity with production):\n\n```bash\ndocker-compose up --build -d\ndocker-compose logs -f api\n```\n\nTo route frontend calls to the external backend, set:\n- `NEXT_PUBLIC_USE_LEGACY_BACKEND=true`\n- `NEXT_PUBLIC_API_DEV_URL=http://localhost:8000`\n\nFor a full machine setup guide (Node/Python/uv versions + verification), see `docs/dev-setup.md`.\n\nQuick validation:\n\n```bash\npnpm check\npnpm test\npnpm build\n```\n\nRailway backend docs: `docs/railway-backend.md`.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Acknowledgements\n\nShoutout to [Romain Courtois](https://github.com/cyclotruc)'s [Gitingest](https://gitingest.com/) for inspiration and styling\n\n## 🤔 Future Steps\n\n- Implement font-awesome icons in diagram\n- Implement an embedded feature like star-history.com but for diagrams. The diagram could also be updated progressively as commits are made.\n" }, { "path": "backend/.python-version", "content": "3.12\n" }, { "path": "backend/Dockerfile", "content": "FROM node:22.12.0-slim AS node-runtime\nFROM python:3.12-slim\n\nWORKDIR /app\nENV ENVIRONMENT=production\nENV PORT=8000\n\nCOPY --from=node-runtime /usr/local/bin/node /usr/local/bin/node\nCOPY --from=node-runtime /usr/local/lib/node_modules /usr/local/lib/node_modules\nRUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \\\n ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx\n\n# Install uv inside the image\nCOPY --from=ghcr.io/astral-sh/uv:0.5.24 /uv /uvx /bin/\n\n# Copy dependency manifests first for better layer caching\nCOPY pyproject.toml uv.lock ./\nCOPY package.json ./\nCOPY package-lock.json ./\n\n# Install pinned runtime dependencies from uv lockfile\nRUN uv sync --frozen --no-dev --no-install-project\nRUN npm ci --omit=dev\n\n# Copy application code\nCOPY . .\nRUN chmod +x /app/entrypoint.sh && \\\n sed -i 's/\\r$//' /app/entrypoint.sh && \\\n ls -la /app/entrypoint.sh\n\nEXPOSE 8000\n\nCMD [\"/bin/bash\", \"/app/entrypoint.sh\"]\n" }, { "path": "backend/app/__init__.py", "content": "" }, { "path": "backend/app/core/errors.py", "content": "from __future__ import annotations\n\n\ndef api_error(code: str, message: str, **extra):\n payload = {\n \"ok\": False,\n \"error\": message,\n \"error_code\": code,\n }\n payload.update(extra)\n return payload\n\n\ndef api_success(**data):\n payload = {\"ok\": True}\n payload.update(data)\n return payload\n" }, { "path": "backend/app/core/observability.py", "content": "from __future__ import annotations\n\nimport json\nimport logging\nimport time\n\n\nlogger = logging.getLogger(\"gitdiagram.api\")\nif not logger.handlers:\n logging.basicConfig(level=logging.INFO, format=\"%(asctime)s %(levelname)s %(message)s\")\n\n\ndef log_event(event: str, **fields):\n logger.info(\n json.dumps(\n {\n \"event\": event,\n **fields,\n },\n default=str,\n )\n )\n\n\nclass Timer:\n def __init__(self):\n self.start = time.perf_counter()\n\n def elapsed_ms(self) -> int:\n return int((time.perf_counter() - self.start) * 1000)\n" }, { "path": "backend/app/main.py", "content": "import os\n\nfrom api_analytics.fastapi import Analytics\nfrom fastapi import FastAPI\nfrom fastapi.middleware.cors import CORSMiddleware\n\nfrom app.core.errors import api_success\nfrom app.core.observability import log_event\nfrom app.routers import generate\n\napp = FastAPI()\n\ncors_origins = os.getenv(\"CORS_ORIGINS\")\nif cors_origins:\n origins = [origin.strip() for origin in cors_origins.split(\",\") if origin.strip()]\nelse:\n origins = [\n \"http://localhost:3000\",\n \"https://gitdiagram.com\",\n \"https://www.gitdiagram.com\",\n ]\n\napp.add_middleware(\n CORSMiddleware,\n allow_origins=origins,\n allow_credentials=True,\n allow_methods=[\"GET\", \"POST\", \"OPTIONS\"],\n allow_headers=[\"*\"],\n)\n\napi_analytics_key = os.getenv(\"API_ANALYTICS_KEY\")\nif api_analytics_key:\n app.add_middleware(Analytics, api_key=api_analytics_key)\n\napp.include_router(generate.router)\n\n\n@app.get(\"/\")\nasync def root():\n return api_success(message=\"Hello from GitDiagram API!\")\n\n\n@app.get(\"/healthz\")\nasync def healthz():\n log_event(\"healthz.ok\")\n return api_success(status=\"ok\")\n" }, { "path": "backend/app/prompts.py", "content": "# This is our processing. This is where GitDiagram makes the magic happen\n# There is a lot of DETAIL we need to extract from the repository to produce detailed and accurate diagrams\n# I will immediately put out there that I'm trying to reduce costs. Theoretically, I could, for like 5x better accuracy, include most file content as well which would make for perfect diagrams, but thats too many tokens for my wallet, and would probably greatly increase generation time. (maybe a paid feature?)\n\n# THE PROCESS:\n\n# imagine it like this:\n# def prompt1(file_tree, readme) -> explanation of diagram\n# def prompt2(explanation, file_tree) -> maps relevant directories and files to parts of diagram for interactivity\n# def prompt3(explanation, map) -> Mermaid.js code\n\n# Note: Originally prompt1 and prompt2 were combined - but I tested it, and turns out mapping relevant dirs and files in one prompt along with generating detailed and accurate diagrams was difficult for Claude 3.5 Sonnet. It lost detail in the explanation and dedicated more \"effort\" to the mappings, so this is now its own prompt.\n\n# This is my first take at prompt engineering so if you have any ideas on optimizations please make an issue on the GitHub!\n\nSYSTEM_FIRST_PROMPT = \"\"\"\nYou are tasked with explaining to a principal software engineer how to draw the best and most accurate system design diagram / architecture of a given project. This explanation should be tailored to the specific project's purpose and structure. To accomplish this, you will be provided with two key pieces of information:\n\n1. The complete and entire file tree of the project including all directory and file names, which will be enclosed in tags in the users message.\n\n2. The README file of the project, which will be enclosed in tags in the users message.\n\nAnalyze these components carefully, as they will provide crucial information about the project's structure and purpose. Follow these steps to create an explanation for the principal software engineer:\n\n1. Identify the project type and purpose:\n - Examine the file structure and README to determine if the project is a full-stack application, an open-source tool, a compiler, or another type of software imaginable.\n - Look for key indicators in the README, such as project description, features, or use cases.\n\n2. Analyze the file structure:\n - Pay attention to top-level directories and their names (e.g., \"frontend\", \"backend\", \"src\", \"lib\", \"tests\").\n - Identify patterns in the directory structure that might indicate architectural choices (e.g., MVC pattern, microservices).\n - Note any configuration files, build scripts, or deployment-related files.\n\n3. Examine the README for additional insights:\n - Look for sections describing the architecture, dependencies, or technical stack.\n - Check for any diagrams or explanations of the system's components.\n\n4. Based on your analysis, explain how to create a system design diagram that accurately represents the project's architecture. Include the following points:\n\n a. Identify the main components of the system (e.g., frontend, backend, database, building, external services).\n b. Determine the relationships and interactions between these components.\n c. Highlight any important architectural patterns or design principles used in the project.\n d. Include relevant technologies, frameworks, or libraries that play a significant role in the system's architecture.\n\n5. Provide guidelines for tailoring the diagram to the specific project type:\n - For a full-stack application, emphasize the separation between frontend and backend, database interactions, and any API layers.\n - For an open-source tool, focus on the core functionality, extensibility points, and how it integrates with other systems.\n - For a compiler or language-related project, highlight the different stages of compilation or interpretation, and any intermediate representations.\n\n6. Instruct the principal software engineer to include the following elements in the diagram:\n - Clear labels for each component\n - Directional arrows to show data flow or dependencies\n - Color coding or shapes to distinguish between different types of components\n\n7. NOTE: Emphasize the importance of being very detailed and capturing the essential architectural elements. Don't overthink it too much, simply separating the project into as many components as possible is best.\n\nPresent your explanation and instructions within tags, ensuring that you tailor your advice to the specific project based on the provided file tree and README content.\n\"\"\"\n\n# - A legend explaining any symbols or abbreviations used\n# ^ removed since it was making the diagrams very long\n\n# just adding some clear separation between the prompts\n# ************************************************************\n# ************************************************************\n\nSYSTEM_SECOND_PROMPT = \"\"\"\nYou are tasked with mapping key components of a system design to their corresponding files and directories in a project's file structure. You will be provided with a detailed explanation of the system design/architecture and a file tree of the project.\n\nFirst, carefully read the system design explanation which will be enclosed in tags in the users message.\n\nThen, examine the file tree of the project which will be enclosed in tags in the users message.\n\nYour task is to analyze the system design explanation and identify key components, modules, or services mentioned. Then, try your best to map these components to what you believe could be their corresponding directories and files in the provided file tree.\n\nGuidelines:\n1. Focus on major components described in the system design.\n2. Look for directories and files that clearly correspond to these components.\n3. Include both directories and specific files when relevant.\n4. If a component doesn't have a clear corresponding file or directory, simply dont include it in the map.\n\nNow, provide your final answer in the following format:\n\n\n1. [Component Name]: [File/Directory Path]\n2. [Component Name]: [File/Directory Path]\n[Continue for all identified components]\n\n\nRemember to be as specific as possible in your mappings, only use what is given to you from the file tree, and to strictly follow the components mentioned in the explanation. \n\"\"\"\n\n# ❌ BELOW IS A REMOVED SECTION FROM THE ABOVE PROMPT USED FOR CLAUDE 3.5 SONNET\n# Before providing your final answer, use the to think through your process:\n# 1. List the key components identified in the system design.\n# 2. For each component, brainstorm potential corresponding directories or files.\n# 3. Verify your mappings by double-checking the file tree.\n\n# \n# [Your thought process here]\n# \n\n# just adding some clear separation between the prompts\n# ************************************************************\n# ************************************************************\n\nSYSTEM_THIRD_PROMPT = \"\"\"\nYou are a principal software engineer tasked with creating a system design diagram using Mermaid.js based on a detailed explanation. Your goal is to accurately represent the architecture and design of the project as described in the explanation.\n\nThe detailed explanation of the design will be enclosed in tags in the users message.\n\nAlso, sourced from the explanation, as a bonus, a few of the identified components have been mapped to their paths in the project file tree, whether it is a directory or file which will be enclosed in tags in the users message.\n\nTo create the Mermaid.js diagram:\n\n1. Carefully read and analyze the provided design explanation.\n2. Identify the main components, services, and their relationships within the system.\n3. Determine the appropriate Mermaid.js diagram type to use (e.g., flowchart, sequence diagram, class diagram, architecture, etc.) based on the nature of the system described.\n4. Create the Mermaid.js code to represent the design, ensuring that:\n a. All major components are included\n b. Relationships between components are clearly shown\n c. The diagram accurately reflects the architecture described in the explanation\n d. The layout is logical and easy to understand\n\nGuidelines for diagram components and relationships:\n- Use appropriate shapes for different types of components (e.g., rectangles for services, cylinders for databases, etc.)\n- Use clear and concise labels for each component\n- Show the direction of data flow or dependencies using arrows\n- Group related components together if applicable\n- Include any important notes or annotations mentioned in the explanation\n- Just follow the explanation. It will have everything you need.\n\nIMPORTANT!!: Please orient and draw the diagram as vertically as possible. You must avoid long horizontal lists of nodes and sections!\n\nYou must include click events for components of the diagram that have been specified in the provided :\n- Do not try to include the full url. This will be processed by another program afterwards. All you need to do is include the path.\n- For example:\n - This is a correct click event: `click Example \"app/example.js\"`\n - This is an incorrect click event: `click Example \"https://github.com/username/repo/blob/main/app/example.js\"`\n- Do this for as many components as specified in the component mapping, include directories and files.\n - If you believe the component contains files and is a directory, include the directory path.\n - If you believe the component references a specific file, include the file path.\n- Make sure to include the full path to the directory or file exactly as specified in the component mapping.\n- It is very important that you do this for as many files as possible. The more the better.\n\n- IMPORTANT: THESE PATHS ARE FOR CLICK EVENTS ONLY, these paths should not be included in the diagram's node's names. Only for the click events. Paths should not be seen by the user.\n\nYour output should be valid Mermaid.js code that can be rendered into a diagram.\n\nDo not include an init declaration such as `%%{init: {'key':'etc'}}%%`. This is handled externally. Just return the diagram code.\n\nYour response must strictly be just the Mermaid.js code, without any additional text or explanations.\nNo code fence or markdown ticks needed, simply return the Mermaid.js code.\n\nEnsure that your diagram adheres strictly to the given explanation, without adding or omitting any significant components or relationships. \n\nFor general direction, the provided example below is how you should structure your code:\n\n```mermaid\nflowchart TD \n %% or graph TD, your choice\n\n %% Global entities\n A(\"Entity A\"):::external\n %% more...\n\n %% Subgraphs and modules\n subgraph \"Layer A\"\n A1(\"Module A\"):::example\n %% more modules...\n %% inner subgraphs if needed...\n end\n\n %% more subgraphs, modules, etc...\n\n %% Connections\n A -->|\"relationship\"| B\n %% and a lot more...\n\n %% Click Events\n click A1 \"example/example.js\"\n %% and a lot more...\n\n %% Styles\n classDef frontend %%...\n %% and a lot more...\n```\n\nEXTREMELY Important notes on syntax!!! (PAY ATTENTION TO THIS):\n- Make sure to add colour to the diagram!!! This is extremely critical.\n- In Mermaid.js syntax, we cannot include special characters for nodes without being inside quotes! For example: `EX[/api/process (Backend)]:::api` and `API -->|calls Process()| Backend` are two examples of syntax errors. They should be `EX[\"/api/process (Backend)\"]:::api` and `API -->|\"calls Process()\"| Backend` respectively. Notice the quotes. This is extremely important. Make sure to include quotes for any string that contains special characters.\n- In Mermaid.js syntax, you cannot apply a class style directly within a subgraph declaration. For example: `subgraph \"Frontend Layer\":::frontend` is a syntax error. However, you can apply them to nodes within the subgraph. For example: `Example[\"Example Node\"]:::frontend` is valid, and `class Example1,Example2 frontend` is valid.\n- In Mermaid.js syntax, there cannot be spaces in the relationship label names. For example: `A -->| \"example relationship\" | B` is a syntax error. It should be `A -->|\"example relationship\"| B` \n- In Mermaid.js syntax, you cannot give subgraphs an alias like nodes. For example: `subgraph A \"Layer A\"` is a syntax error. It should be `subgraph \"Layer A\"` \n\"\"\"\n# ^^^ note: ive generated a few diagrams now and claude still writes incorrect mermaid code sometimes. in the future, refer to those generated diagrams and add important instructions to the prompt above to avoid those mistakes. examples are best.\n\n# e. A legend is included\n# ^ removed since it was making the diagrams very long\n\nSYSTEM_FIX_MERMAID_PROMPT = \"\"\"\nYou are a Mermaid syntax repair specialist.\n\nYou will receive:\n- ...\n- ...\n- ...\n- ...\n\nTask:\n- Fix Mermaid syntax errors while preserving the original diagram meaning.\n- Keep all click events that map to repository paths.\n- Keep diagram mostly vertical.\n- Return Mermaid code only.\n\nRules:\n- No markdown code fences.\n- No extra commentary.\n- Ensure final output is syntactically valid Mermaid.\n\"\"\"\n" }, { "path": "backend/app/routers/generate.py", "content": "from __future__ import annotations\n\nimport asyncio\nimport json\nimport re\nfrom typing import Any\n\nfrom fastapi import APIRouter, Request\nfrom fastapi.responses import JSONResponse, StreamingResponse\nfrom pydantic import BaseModel, Field, ValidationError\n\nfrom app.core.observability import Timer, log_event\nfrom app.prompts import (\n SYSTEM_FIRST_PROMPT,\n SYSTEM_FIX_MERMAID_PROMPT,\n SYSTEM_SECOND_PROMPT,\n SYSTEM_THIRD_PROMPT,\n)\nfrom app.services.github_service import GitHubService\nfrom app.services.mermaid_service import format_validation_feedback, validate_mermaid_syntax\nfrom app.services.model_config import get_model\nfrom app.services.openai_service import OpenAIService\nfrom app.services.pricing import estimate_text_token_cost_usd\n\nrouter = APIRouter(prefix=\"/generate\", tags=[\"OpenAI\"])\n\nopenai_service = OpenAIService()\n\nMAX_MERMAID_FIX_ATTEMPTS = 3\nMULTI_STAGE_INPUT_MULTIPLIER = 2\nINPUT_OVERHEAD_TOKENS = 3000\nESTIMATED_OUTPUT_TOKENS = 8000\n\n\nclass GenerateRequest(BaseModel):\n username: str = Field(min_length=1)\n repo: str = Field(min_length=1)\n api_key: str | None = Field(default=None, min_length=1)\n github_pat: str | None = Field(default=None, min_length=1)\n\n\ndef _sse_message(payload: dict[str, Any]) -> str:\n return f\"data: {json.dumps(payload)}\\n\\n\"\n\n\ndef _strip_mermaid_code_fences(text: str) -> str:\n return text.replace(\"```mermaid\", \"\").replace(\"```\", \"\").strip()\n\n\ndef _extract_component_mapping(response: str) -> str:\n start_tag = \"\"\n end_tag = \"\"\n start_index = response.find(start_tag)\n end_index = response.find(end_tag)\n if start_index == -1 or end_index == -1:\n return response\n return response[start_index:end_index]\n\n\ndef process_click_events(diagram: str, username: str, repo: str, branch: str) -> str:\n click_pattern = r'click ([^\\s\"]+)\\s+\"([^\"]+)\"'\n\n def replace_path(match: re.Match[str]) -> str:\n node_id = match.group(1)\n trimmed_path = match.group(2).strip().strip(\"\\\"'\")\n is_file = \".\" in trimmed_path and not trimmed_path.endswith(\"/\")\n path_type = \"blob\" if is_file else \"tree\"\n full_url = f\"https://github.com/{username}/{repo}/{path_type}/{branch}/{trimmed_path}\"\n return f'click {node_id} \"{full_url}\"'\n\n return re.sub(click_pattern, replace_path, diagram)\n\n\ndef _parse_request_payload(payload: Any) -> tuple[GenerateRequest | None, str | None]:\n try:\n parsed = GenerateRequest.model_validate(payload)\n return parsed, None\n except ValidationError:\n return None, \"Invalid request payload.\"\n\n\ndef _get_github_data(username: str, repo: str, github_pat: str | None):\n github_service = GitHubService(pat=github_pat)\n return github_service.get_github_data(username, repo)\n\n\nasync def _estimate_repo_input_tokens(\n model: str,\n file_tree: str,\n readme: str,\n api_key: str | None = None,\n) -> int:\n try:\n return await openai_service.count_input_tokens(\n model=model,\n system_prompt=SYSTEM_FIRST_PROMPT,\n data={\n \"file_tree\": file_tree,\n \"readme\": readme,\n },\n api_key=api_key,\n reasoning_effort=\"medium\",\n )\n except Exception:\n return openai_service.estimate_tokens(f\"{file_tree}\\n{readme}\")\n\n\n@router.post(\"/cost\")\nasync def get_generation_cost(request: Request):\n timer = Timer()\n try:\n payload = await request.json()\n parsed, error = _parse_request_payload(payload)\n if not parsed:\n return JSONResponse(\n {\n \"ok\": False,\n \"error\": error,\n \"error_code\": \"VALIDATION_ERROR\",\n }\n )\n\n github_data = _get_github_data(parsed.username, parsed.repo, parsed.github_pat)\n model = get_model()\n base_input_tokens = await _estimate_repo_input_tokens(\n model=model,\n file_tree=github_data.file_tree,\n readme=github_data.readme,\n api_key=parsed.api_key,\n )\n estimated_input_tokens = (\n base_input_tokens * MULTI_STAGE_INPUT_MULTIPLIER + INPUT_OVERHEAD_TOKENS\n )\n estimated_output_tokens = ESTIMATED_OUTPUT_TOKENS\n cost_usd, pricing_model, pricing = estimate_text_token_cost_usd(\n model=model,\n input_tokens=estimated_input_tokens,\n output_tokens=estimated_output_tokens,\n )\n\n response_payload = {\n \"ok\": True,\n \"cost\": f\"${cost_usd:.2f} USD\",\n \"model\": model,\n \"pricing_model\": pricing_model,\n \"estimated_input_tokens\": estimated_input_tokens,\n \"estimated_output_tokens\": estimated_output_tokens,\n \"pricing\": {\n \"input_per_million_usd\": pricing.input_per_million_usd,\n \"output_per_million_usd\": pricing.output_per_million_usd,\n },\n }\n log_event(\n \"generate.cost.success\",\n username=parsed.username,\n repo=parsed.repo,\n elapsed_ms=timer.elapsed_ms(),\n model=model,\n )\n return JSONResponse(response_payload)\n except Exception as exc:\n log_event(\n \"generate.cost.failed\",\n elapsed_ms=timer.elapsed_ms(),\n error=str(exc),\n )\n return JSONResponse(\n {\n \"ok\": False,\n \"error\": str(exc) if isinstance(exc, Exception) else \"Failed to estimate generation cost.\",\n \"error_code\": \"COST_ESTIMATION_FAILED\",\n }\n )\n\n\n@router.post(\"/stream\")\nasync def generate_stream(request: Request):\n try:\n payload = await request.json()\n except Exception:\n return JSONResponse(\n {\n \"ok\": False,\n \"error\": \"Invalid request payload.\",\n \"error_code\": \"VALIDATION_ERROR\",\n },\n status_code=400,\n )\n\n parsed, error = _parse_request_payload(payload)\n if not parsed:\n return JSONResponse(\n {\n \"ok\": False,\n \"error\": error,\n \"error_code\": \"VALIDATION_ERROR\",\n },\n status_code=400,\n )\n\n async def event_generator():\n timer = Timer()\n\n def send(payload: dict[str, Any]) -> str:\n return _sse_message(payload)\n\n try:\n github_data = _get_github_data(parsed.username, parsed.repo, parsed.github_pat)\n model = get_model()\n token_count = await _estimate_repo_input_tokens(\n model=model,\n file_tree=github_data.file_tree,\n readme=github_data.readme,\n api_key=parsed.api_key,\n )\n\n yield send(\n {\n \"status\": \"started\",\n \"message\": \"Starting generation process...\",\n }\n )\n\n if token_count > 50000 and token_count < 195000 and not parsed.api_key:\n yield send(\n {\n \"status\": \"error\",\n \"error\": \"File tree and README combined exceeds token limit (50,000). This repository is too large for free generation. Provide your own OpenAI API key to continue.\",\n \"error_code\": \"API_KEY_REQUIRED\",\n }\n )\n return\n\n if token_count > 195000:\n yield send(\n {\n \"status\": \"error\",\n \"error\": \"Repository is too large (>195k tokens) for analysis. Try a smaller repo.\",\n \"error_code\": \"TOKEN_LIMIT_EXCEEDED\",\n }\n )\n return\n\n yield send(\n {\n \"status\": \"explanation_sent\",\n \"message\": f\"Sending explanation request to {model}...\",\n }\n )\n await asyncio.sleep(0.08)\n yield send(\n {\n \"status\": \"explanation\",\n \"message\": \"Analyzing repository structure...\",\n }\n )\n\n explanation = \"\"\n async for chunk in openai_service.stream_completion(\n model=model,\n system_prompt=SYSTEM_FIRST_PROMPT,\n data={\n \"file_tree\": github_data.file_tree,\n \"readme\": github_data.readme,\n },\n api_key=parsed.api_key,\n reasoning_effort=\"medium\",\n ):\n explanation += chunk\n yield send({\"status\": \"explanation_chunk\", \"chunk\": chunk})\n\n yield send(\n {\n \"status\": \"mapping_sent\",\n \"message\": f\"Sending component mapping request to {model}...\",\n }\n )\n await asyncio.sleep(0.08)\n yield send(\n {\n \"status\": \"mapping\",\n \"message\": \"Creating component mapping...\",\n }\n )\n\n full_mapping_response = \"\"\n async for chunk in openai_service.stream_completion(\n model=model,\n system_prompt=SYSTEM_SECOND_PROMPT,\n data={\n \"explanation\": explanation,\n \"file_tree\": github_data.file_tree,\n },\n api_key=parsed.api_key,\n reasoning_effort=\"low\",\n ):\n full_mapping_response += chunk\n yield send({\"status\": \"mapping_chunk\", \"chunk\": chunk})\n\n component_mapping = _extract_component_mapping(full_mapping_response)\n\n yield send(\n {\n \"status\": \"diagram_sent\",\n \"message\": f\"Sending diagram generation request to {model}...\",\n }\n )\n await asyncio.sleep(0.08)\n yield send(\n {\n \"status\": \"diagram\",\n \"message\": \"Generating diagram...\",\n }\n )\n\n mermaid_code = \"\"\n async for chunk in openai_service.stream_completion(\n model=model,\n system_prompt=SYSTEM_THIRD_PROMPT,\n data={\n \"explanation\": explanation,\n \"component_mapping\": component_mapping,\n },\n api_key=parsed.api_key,\n reasoning_effort=\"low\",\n ):\n mermaid_code += chunk\n yield send({\"status\": \"diagram_chunk\", \"chunk\": chunk})\n\n candidate_diagram = _strip_mermaid_code_fences(mermaid_code)\n validation_result = await asyncio.to_thread(\n validate_mermaid_syntax,\n candidate_diagram,\n )\n had_fix_loop = not validation_result.valid\n\n if not validation_result.valid:\n parser_feedback = format_validation_feedback(validation_result)\n yield send(\n {\n \"status\": \"diagram_fixing\",\n \"message\": \"Diagram generated. Mermaid syntax validation failed, starting auto-fix loop...\",\n \"parser_error\": parser_feedback,\n }\n )\n\n attempt = 1\n while (not validation_result.valid) and attempt <= MAX_MERMAID_FIX_ATTEMPTS:\n parser_feedback = format_validation_feedback(validation_result)\n yield send(\n {\n \"status\": \"diagram_fix_attempt\",\n \"message\": f\"Fixing Mermaid syntax (attempt {attempt}/{MAX_MERMAID_FIX_ATTEMPTS})...\",\n \"fix_attempt\": attempt,\n \"fix_max_attempts\": MAX_MERMAID_FIX_ATTEMPTS,\n \"parser_error\": parser_feedback,\n }\n )\n\n repaired_diagram = \"\"\n async for chunk in openai_service.stream_completion(\n model=model,\n system_prompt=SYSTEM_FIX_MERMAID_PROMPT,\n data={\n \"mermaid_code\": candidate_diagram,\n \"parser_error\": parser_feedback,\n \"explanation\": explanation,\n \"component_mapping\": component_mapping,\n },\n api_key=parsed.api_key,\n reasoning_effort=\"low\",\n ):\n repaired_diagram += chunk\n yield send(\n {\n \"status\": \"diagram_fix_chunk\",\n \"chunk\": chunk,\n \"fix_attempt\": attempt,\n \"fix_max_attempts\": MAX_MERMAID_FIX_ATTEMPTS,\n }\n )\n\n candidate_diagram = _strip_mermaid_code_fences(repaired_diagram)\n yield send(\n {\n \"status\": \"diagram_fix_validating\",\n \"message\": f\"Validating Mermaid syntax after attempt {attempt}/{MAX_MERMAID_FIX_ATTEMPTS}...\",\n \"fix_attempt\": attempt,\n \"fix_max_attempts\": MAX_MERMAID_FIX_ATTEMPTS,\n }\n )\n validation_result = await asyncio.to_thread(\n validate_mermaid_syntax,\n candidate_diagram,\n )\n attempt += 1\n\n if not validation_result.valid:\n yield send(\n {\n \"status\": \"error\",\n \"error\": \"Generated Mermaid remained syntactically invalid after auto-fix attempts. Please retry generation.\",\n \"error_code\": \"MERMAID_SYNTAX_UNRESOLVED\",\n \"parser_error\": format_validation_feedback(validation_result),\n }\n )\n return\n\n processed_diagram = process_click_events(\n candidate_diagram,\n parsed.username,\n parsed.repo,\n github_data.default_branch,\n )\n\n if had_fix_loop:\n yield send(\n {\n \"status\": \"diagram_fixing\",\n \"message\": \"Mermaid syntax validated. Finalizing diagram output...\",\n }\n )\n\n yield send(\n {\n \"status\": \"complete\",\n \"diagram\": processed_diagram,\n \"explanation\": explanation,\n \"mapping\": component_mapping,\n }\n )\n log_event(\n \"generate.stream.success\",\n username=parsed.username,\n repo=parsed.repo,\n elapsed_ms=timer.elapsed_ms(),\n model=model,\n )\n except Exception as exc:\n yield send(\n {\n \"status\": \"error\",\n \"error\": str(exc) if isinstance(exc, Exception) else \"Streaming generation failed.\",\n \"error_code\": \"STREAM_FAILED\",\n }\n )\n log_event(\n \"generate.stream.failed\",\n username=parsed.username,\n repo=parsed.repo,\n elapsed_ms=timer.elapsed_ms(),\n error=str(exc),\n )\n\n return StreamingResponse(\n event_generator(),\n media_type=\"text/event-stream\",\n headers={\n \"Content-Type\": \"text/event-stream; charset=utf-8\",\n \"Cache-Control\": \"no-cache, no-transform\",\n \"Connection\": \"keep-alive\",\n \"X-Accel-Buffering\": \"no\",\n },\n )\n" }, { "path": "backend/app/services/github_service.py", "content": "from __future__ import annotations\n\nimport base64\nimport os\nfrom datetime import UTC, datetime, timedelta\nfrom dataclasses import dataclass\n\nimport jwt\nimport requests\n\nEXCLUDED_PATTERNS = [\n \"node_modules/\",\n \"vendor/\",\n \"venv/\",\n \".min.\",\n \".pyc\",\n \".pyo\",\n \".pyd\",\n \".so\",\n \".dll\",\n \".class\",\n \".jpg\",\n \".jpeg\",\n \".png\",\n \".gif\",\n \".ico\",\n \".svg\",\n \".ttf\",\n \".woff\",\n \".webp\",\n \"__pycache__/\",\n \".cache/\",\n \".tmp/\",\n \"yarn.lock\",\n \"poetry.lock\",\n \"*.log\",\n \".vscode/\",\n \".idea/\",\n]\n\n\n@dataclass(frozen=True)\nclass GithubData:\n default_branch: str\n file_tree: str\n readme: str\n\n\ndef _should_include_file(path: str) -> bool:\n lower_path = path.lower()\n return not any(pattern in lower_path for pattern in EXCLUDED_PATTERNS)\n\n\ndef _fetch_json(url: str, headers: dict[str, str], not_found_message: str) -> dict:\n response = requests.get(url, headers=headers, timeout=30)\n if response.status_code == 404:\n raise ValueError(not_found_message)\n if not response.ok:\n raise ValueError(f\"GitHub request failed ({response.status_code}): {response.text}\")\n return response.json()\n\n\nclass GitHubService:\n def __init__(self, pat: str | None = None):\n # Request-provided PAT (or env PAT) has top priority.\n self.github_token = (pat or os.getenv(\"GITHUB_PAT\") or \"\").strip() or None\n\n # GitHub App credentials are used when PAT is unavailable.\n self.client_id = (os.getenv(\"GITHUB_CLIENT_ID\") or \"\").strip() or None\n self.private_key = (os.getenv(\"GITHUB_PRIVATE_KEY\") or \"\").strip() or None\n self.installation_id = (os.getenv(\"GITHUB_INSTALLATION_ID\") or \"\").strip() or None\n\n self.access_token: str | None = None\n self.token_expires_at: datetime | None = None\n\n def _normalize_private_key(self) -> str:\n if not self.private_key:\n raise ValueError(\"Missing GITHUB_PRIVATE_KEY.\")\n # Supports both literal newlines and escaped \\\\n forms.\n return self.private_key.replace(\"\\\\n\", \"\\n\")\n\n def _can_use_app_auth(self) -> bool:\n return bool(self.client_id and self.private_key and self.installation_id)\n\n def _generate_jwt(self) -> str:\n if not self.client_id:\n raise ValueError(\"Missing GITHUB_CLIENT_ID.\")\n now = int(datetime.now(UTC).timestamp())\n payload = {\n \"iat\": now,\n \"exp\": now + (10 * 60),\n \"iss\": self.client_id,\n }\n return jwt.encode(payload, self._normalize_private_key(), algorithm=\"RS256\")\n\n def _get_installation_token(self) -> str:\n if self.access_token and self.token_expires_at and self.token_expires_at > datetime.now(UTC):\n return self.access_token\n\n if not self.installation_id:\n raise ValueError(\"Missing GITHUB_INSTALLATION_ID.\")\n\n jwt_token = self._generate_jwt()\n response = requests.post(\n f\"https://api.github.com/app/installations/{self.installation_id}/access_tokens\",\n headers={\n \"Authorization\": f\"Bearer {jwt_token}\",\n \"Accept\": \"application/vnd.github+json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\",\n },\n timeout=30,\n )\n if not response.ok:\n raise ValueError(\n f\"GitHub app token request failed ({response.status_code}): {response.text}\"\n )\n\n payload = response.json()\n token = payload.get(\"token\")\n if not isinstance(token, str) or not token:\n raise ValueError(\"GitHub app token response missing token.\")\n\n expires_at_raw = payload.get(\"expires_at\")\n if isinstance(expires_at_raw, str):\n try:\n expires_at = datetime.fromisoformat(expires_at_raw.replace(\"Z\", \"+00:00\"))\n except ValueError:\n expires_at = datetime.now(UTC) + timedelta(minutes=50)\n else:\n expires_at = datetime.now(UTC) + timedelta(minutes=50)\n\n self.access_token = token\n self.token_expires_at = expires_at\n return token\n\n def _get_headers(self) -> dict[str, str]:\n if self.github_token:\n return {\n \"Authorization\": f\"token {self.github_token}\",\n \"Accept\": \"application/vnd.github+json\",\n }\n\n if self._can_use_app_auth():\n token = self._get_installation_token()\n return {\n \"Authorization\": f\"Bearer {token}\",\n \"Accept\": \"application/vnd.github+json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\",\n }\n\n return {\"Accept\": \"application/vnd.github+json\"}\n\n def get_default_branch(self, username: str, repo: str) -> str:\n data = _fetch_json(\n f\"https://api.github.com/repos/{username}/{repo}\",\n self._get_headers(),\n \"Repository not found.\",\n )\n return data.get(\"default_branch\") or \"main\"\n\n def get_github_file_paths_as_list(self, username: str, repo: str, branch: str) -> str:\n data = _fetch_json(\n f\"https://api.github.com/repos/{username}/{repo}/git/trees/{branch}?recursive=1\",\n self._get_headers(),\n \"Could not fetch repository file tree.\",\n )\n paths = [\n item.get(\"path\")\n for item in (data.get(\"tree\") or [])\n if isinstance(item.get(\"path\"), str) and _should_include_file(item[\"path\"])\n ]\n if not paths:\n raise ValueError(\n \"Could not fetch repository file tree. Repository might be empty or inaccessible.\"\n )\n return \"\\n\".join(paths)\n\n def get_github_readme(self, username: str, repo: str) -> str:\n data = _fetch_json(\n f\"https://api.github.com/repos/{username}/{repo}/readme\",\n self._get_headers(),\n \"No README found for the specified repository.\",\n )\n content = data.get(\"content\")\n if not isinstance(content, str) or not content:\n raise ValueError(\"No README found for the specified repository.\")\n\n encoding = data.get(\"encoding\")\n if encoding == \"base64\":\n return base64.b64decode(content).decode(\"utf-8\")\n return content\n\n def get_github_data(self, username: str, repo: str) -> GithubData:\n default_branch = self.get_default_branch(username, repo)\n file_tree = self.get_github_file_paths_as_list(username, repo, default_branch)\n readme = self.get_github_readme(username, repo)\n return GithubData(\n default_branch=default_branch,\n file_tree=file_tree,\n readme=readme,\n )\n" }, { "path": "backend/app/services/mermaid_service.py", "content": "from __future__ import annotations\n\nimport json\nimport subprocess\nfrom dataclasses import dataclass\n\n\n@dataclass(frozen=True)\nclass MermaidValidationResult:\n valid: bool\n message: str | None = None\n line: int | None = None\n token: str | None = None\n expected: list[str] | None = None\n\n\ndef normalize_parser_message(message: str | None) -> str:\n if not message:\n return \"Mermaid syntax is invalid and could not be parsed.\"\n\n if \"sanitize is not a function\" in message or \"__TURBOPACK__imported__module\" in message:\n return \"Mermaid parser runtime failed in server context (sanitizer issue).\"\n\n return message\n\n\ndef validate_mermaid_syntax(diagram: str) -> MermaidValidationResult:\n try:\n proc = subprocess.run(\n [\"node\", \"scripts/validate_mermaid.mjs\"],\n input=diagram,\n text=True,\n capture_output=True,\n check=False,\n )\n except Exception as exc:\n return MermaidValidationResult(\n valid=False,\n message=normalize_parser_message(str(exc)),\n )\n\n if proc.returncode != 0:\n message = proc.stderr.strip() or proc.stdout.strip() or \"Mermaid validation failed.\"\n return MermaidValidationResult(valid=False, message=normalize_parser_message(message))\n\n try:\n payload = json.loads(proc.stdout)\n except json.JSONDecodeError:\n return MermaidValidationResult(\n valid=False,\n message=normalize_parser_message(\"Mermaid validator returned invalid JSON.\"),\n )\n\n valid = bool(payload.get(\"valid\"))\n message = payload.get(\"message\")\n normalized_message = (\n normalize_parser_message(message)\n if not valid\n else (message if isinstance(message, str) else None)\n )\n\n return MermaidValidationResult(\n valid=valid,\n message=normalized_message,\n line=payload.get(\"line\"),\n token=payload.get(\"token\"),\n expected=payload.get(\"expected\"),\n )\n\n\ndef format_validation_feedback(result: MermaidValidationResult) -> str:\n if result.valid:\n return \"No syntax errors found.\"\n\n details = [f\"message: {result.message or 'unknown parse error'}\"]\n if isinstance(result.line, int):\n details.append(f\"line: {result.line}\")\n if result.token:\n details.append(f\"token: {result.token}\")\n if result.expected:\n details.append(f\"expected: {', '.join(result.expected)}\")\n\n return \"\\n\".join(details)\n" }, { "path": "backend/app/services/model_config.py", "content": "from __future__ import annotations\n\nimport os\n\nDEFAULT_MODEL = \"gpt-5.4-mini\"\n\n\ndef get_model() -> str:\n model = os.getenv(\"OPENAI_MODEL\", \"\").strip()\n return model or DEFAULT_MODEL\n" }, { "path": "backend/app/services/openai_service.py", "content": "from __future__ import annotations\n\nfrom typing import AsyncGenerator, Literal\nimport math\nimport os\n\nfrom dotenv import load_dotenv\nfrom openai import AsyncOpenAI\n\nfrom app.utils.format_message import format_user_message\n\nload_dotenv()\n\nReasoningEffort = Literal[\"low\", \"medium\", \"high\"]\n\n\nclass OpenAIService:\n def __init__(self):\n self.default_api_key = os.getenv(\"OPENAI_API_KEY\")\n\n def _resolve_api_key(self, override_api_key: str | None = None) -> str:\n api_key = (override_api_key or self.default_api_key or \"\").strip()\n if not api_key:\n raise ValueError(\n \"Missing OpenAI API key. Set OPENAI_API_KEY or provide api_key in request.\"\n )\n return api_key\n\n @staticmethod\n def estimate_tokens(text: str) -> int:\n # Mirrors Next.js fallback heuristic.\n return math.ceil(len(text) / 4)\n\n @staticmethod\n def _build_input(system_prompt: str, user_prompt: str) -> list[dict]:\n return [\n {\"role\": \"system\", \"content\": system_prompt},\n {\"role\": \"user\", \"content\": user_prompt},\n ]\n\n @staticmethod\n def _create_client(api_key: str) -> AsyncOpenAI:\n # Keep explicit config local to this service.\n return AsyncOpenAI(\n api_key=api_key,\n max_retries=2,\n timeout=600,\n )\n\n async def stream_completion(\n self,\n *,\n model: str,\n system_prompt: str,\n data: dict[str, str | None],\n api_key: str | None = None,\n reasoning_effort: ReasoningEffort | None = None,\n max_output_tokens: int | None = None,\n ) -> AsyncGenerator[str, None]:\n user_prompt = format_user_message(data)\n resolved_api_key = self._resolve_api_key(api_key)\n payload: dict = {\n \"model\": model,\n \"stream\": True,\n \"input\": self._build_input(system_prompt, user_prompt),\n }\n if reasoning_effort:\n payload[\"reasoning\"] = {\"effort\": reasoning_effort}\n if max_output_tokens:\n payload[\"max_output_tokens\"] = max_output_tokens\n\n client = self._create_client(resolved_api_key)\n stream = await client.responses.create(**payload)\n try:\n async for event in stream:\n if event.type == \"response.output_text.delta\":\n delta = getattr(event, \"delta\", None)\n if isinstance(delta, str) and delta:\n yield delta\n continue\n\n if event.type == \"error\":\n message = getattr(event, \"message\", None) or \"OpenAI stream failed.\"\n raise ValueError(str(message))\n finally:\n await stream.close()\n await client.close()\n\n async def count_input_tokens(\n self,\n *,\n model: str,\n system_prompt: str,\n data: dict[str, str | None],\n api_key: str | None = None,\n reasoning_effort: ReasoningEffort | None = None,\n ) -> int:\n user_prompt = format_user_message(data)\n resolved_api_key = self._resolve_api_key(api_key)\n payload: dict = {\n \"model\": model,\n \"input\": self._build_input(system_prompt, user_prompt),\n }\n if reasoning_effort:\n payload[\"reasoning\"] = {\"effort\": reasoning_effort}\n\n client = self._create_client(resolved_api_key)\n try:\n response = await client.responses.input_tokens.count(**payload)\n input_tokens = getattr(response, \"input_tokens\", None)\n if not isinstance(input_tokens, int):\n raise ValueError(\"OpenAI input token count returned invalid payload.\")\n return input_tokens\n finally:\n await client.close()\n" }, { "path": "backend/app/services/pricing.py", "content": "from __future__ import annotations\n\nfrom dataclasses import dataclass\n\nDEFAULT_PRICING_MODEL = \"gpt-5.4-mini\"\n\n\n@dataclass(frozen=True)\nclass ModelPricing:\n input_per_million_usd: float\n output_per_million_usd: float\n\n\nMODEL_PRICING: dict[str, ModelPricing] = {\n \"gpt-5.4\": ModelPricing(input_per_million_usd=2.5, output_per_million_usd=15.0),\n \"gpt-5.4-pro\": ModelPricing(input_per_million_usd=30.0, output_per_million_usd=180.0),\n \"gpt-5.4-mini\": ModelPricing(input_per_million_usd=0.75, output_per_million_usd=4.5),\n \"gpt-5.4-nano\": ModelPricing(input_per_million_usd=0.2, output_per_million_usd=1.25),\n \"gpt-5.2\": ModelPricing(input_per_million_usd=1.75, output_per_million_usd=14.0),\n \"gpt-5.2-chat-latest\": ModelPricing(\n input_per_million_usd=1.75,\n output_per_million_usd=14.0,\n ),\n \"gpt-5.2-codex\": ModelPricing(input_per_million_usd=1.75, output_per_million_usd=14.0),\n \"gpt-5.2-pro\": ModelPricing(input_per_million_usd=21.0, output_per_million_usd=168.0),\n \"gpt-5.1\": ModelPricing(input_per_million_usd=1.25, output_per_million_usd=10.0),\n \"gpt-5\": ModelPricing(input_per_million_usd=1.25, output_per_million_usd=10.0),\n \"gpt-5-mini\": ModelPricing(input_per_million_usd=0.25, output_per_million_usd=2.0),\n \"gpt-5-nano\": ModelPricing(input_per_million_usd=0.05, output_per_million_usd=0.4),\n \"o4-mini\": ModelPricing(input_per_million_usd=1.1, output_per_million_usd=4.4),\n}\n\nDEFAULT_PRICING = MODEL_PRICING[DEFAULT_PRICING_MODEL]\n\n\ndef _strip_date_snapshot_suffix(model: str) -> str:\n import re\n\n return re.sub(r\"-\\d{4}-\\d{2}-\\d{2}$\", \"\", model, flags=re.IGNORECASE)\n\n\ndef resolve_pricing_model(model: str) -> str:\n normalized = model.strip().lower()\n if normalized in MODEL_PRICING:\n return normalized\n\n without_date = _strip_date_snapshot_suffix(normalized)\n if without_date in MODEL_PRICING:\n return without_date\n\n if without_date.startswith(\"gpt-5.4-pro\"):\n return \"gpt-5.4-pro\"\n if without_date.startswith(\"gpt-5.4-mini\"):\n return \"gpt-5.4-mini\"\n if without_date.startswith(\"gpt-5.4-nano\"):\n return \"gpt-5.4-nano\"\n if without_date.startswith(\"gpt-5.4\"):\n return \"gpt-5.4\"\n if without_date.startswith(\"gpt-5.2-pro\"):\n return \"gpt-5.2-pro\"\n if without_date.startswith(\"gpt-5.2-codex\"):\n return \"gpt-5.2-codex\"\n if without_date.startswith(\"gpt-5.2-chat\"):\n return \"gpt-5.2-chat-latest\"\n if without_date.startswith(\"gpt-5.2\"):\n return \"gpt-5.2\"\n if without_date.startswith(\"gpt-5.1\"):\n return \"gpt-5.1\"\n if without_date.startswith(\"gpt-5-mini\"):\n return \"gpt-5-mini\"\n if without_date.startswith(\"gpt-5-nano\"):\n return \"gpt-5-nano\"\n if without_date.startswith(\"gpt-5\"):\n return \"gpt-5\"\n if without_date.startswith(\"o4-mini\"):\n return \"o4-mini\"\n\n return DEFAULT_PRICING_MODEL\n\n\ndef estimate_text_token_cost_usd(\n model: str,\n input_tokens: int,\n output_tokens: int,\n) -> tuple[float, str, ModelPricing]:\n pricing_model = resolve_pricing_model(model)\n pricing = MODEL_PRICING.get(pricing_model, DEFAULT_PRICING)\n input_cost = (max(input_tokens, 0) / 1_000_000) * pricing.input_per_million_usd\n output_cost = (max(output_tokens, 0) / 1_000_000) * pricing.output_per_million_usd\n return (input_cost + output_cost, pricing_model, pricing)\n" }, { "path": "backend/app/utils/format_message.py", "content": "def format_user_message(data: dict[str, str | None]) -> str:\n parts: list[str] = []\n for key, value in data.items():\n if isinstance(value, str):\n parts.append(f\"<{key}>\\n{value}\\n\")\n return \"\\n\".join(parts)\n" }, { "path": "backend/deploy.sh", "content": "#!/bin/bash\n\n# Exit on any error\nset -e\n\n# Navigate to project directory\ncd ~/gitdiagram\n\n# Pull latest changes\ngit pull --ff-only origin main\n\n# Build and restart containers with production environment\ndocker-compose down\nENVIRONMENT=production docker-compose up --build -d\n\n# Remove unused images\ndocker image prune -f\n\n# Show logs only if --logs flag is passed\nif [ \"$1\" == \"--logs\" ]; then\n docker-compose logs -f\nelse\n echo \"Deployment complete! Run 'docker-compose logs -f' to view logs\"\nfi\n" }, { "path": "backend/entrypoint.sh", "content": "#!/bin/bash\n\nset -euo pipefail\n\nENVIRONMENT=\"${ENVIRONMENT:-production}\"\nHOST=\"${HOST:-0.0.0.0}\"\nPORT=\"${PORT:-8000}\"\nWEB_CONCURRENCY=\"${WEB_CONCURRENCY:-2}\"\n\necho \"Current ENVIRONMENT: ${ENVIRONMENT}\"\necho \"Binding to ${HOST}:${PORT}\"\n\nif [ \"${ENVIRONMENT}\" = \"development\" ]; then\n echo \"Starting in development mode with hot reload...\"\n exec uv run --no-dev uvicorn app.main:app --host \"${HOST}\" --port \"${PORT}\" --reload\nfi\n\necho \"Starting in production mode...\"\nexec uv run --no-dev uvicorn app.main:app \\\n --host \"${HOST}\" \\\n --port \"${PORT}\" \\\n --timeout-keep-alive 300 \\\n --workers \"${WEB_CONCURRENCY}\" \\\n --loop uvloop \\\n --http httptools\n" }, { "path": "backend/nginx/api.conf", "content": "server {\n server_name api.gitdiagram.com;\n\n # Block requests with no valid Host header\n if ($host !~ ^(api.gitdiagram.com)$) {\n return 444;\n }\n\n # Strictly allow only GET, POST, and OPTIONS requests for the specified paths (defined in my fastapi app)\n location ~ ^/(generate(/cost|/stream)?|healthz|)?$ {\n if ($request_method !~ ^(GET|POST|OPTIONS)$) {\n return 444;\n }\n\n proxy_pass http://127.0.0.1:8000;\n include proxy_params;\n proxy_redirect off;\n\n # Disable buffering for SSE\n proxy_buffering off;\n proxy_cache off;\n \n # Required headers for SSE\n proxy_set_header Connection '';\n proxy_http_version 1.1;\n }\n\n # Return 444 for everything else (no response, just close connection)\n location / {\n return 444;\n # keep access log on\n }\n\n # Add timeout settings\n proxy_connect_timeout 300;\n proxy_send_timeout 300;\n proxy_read_timeout 300;\n send_timeout 300;\n\n listen 443 ssl; # managed by Certbot\n ssl_certificate /etc/letsencrypt/live/api.gitdiagram.com/fullchain.pem; # managed by Certbot\n ssl_certificate_key /etc/letsencrypt/live/api.gitdiagram.com/privkey.pem; # managed by Certbot\n include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot\n ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot\n\n}\nserver {\n if ($host = api.gitdiagram.com) {\n return 301 https://$host$request_uri;\n } # managed by Certbot\n\n\n listen 80;\n server_name api.gitdiagram.com;\n return 404; # managed by Certbot\n}\n" }, { "path": "backend/nginx/setup_nginx.sh", "content": "#!/bin/bash\n\n# Exit on any error\nset -e\n\n# Check if running as root\nif [ \"$EUID\" -ne 0 ]; then \n echo \"Please run as root or with sudo\"\n exit 1\nfi\n\n# Copy Nginx configuration\necho \"Copying Nginx configuration...\"\ncp \"$(dirname \"$0\")/api.conf\" /etc/nginx/sites-available/api\nln -sf /etc/nginx/sites-available/api /etc/nginx/sites-enabled/\n\n# Test Nginx configuration\necho \"Testing Nginx configuration...\"\nnginx -t\n\n# Reload Nginx\necho \"Reloading Nginx...\"\nsystemctl reload nginx\n\necho \"Nginx configuration updated successfully!\" " }, { "path": "backend/package.json", "content": "{\n \"name\": \"gitdiagram-backend-mermaid-validator\",\n \"private\": true,\n \"type\": \"module\",\n \"dependencies\": {\n \"dompurify\": \"3.3.1\",\n \"jsdom\": \"28.1.0\",\n \"mermaid\": \"11.12.3\"\n }\n}\n" }, { "path": "backend/pyproject.toml", "content": "[project]\nname = \"gitdiagram-backend\"\nversion = \"0.1.0\"\ndescription = \"FastAPI backend for GitDiagram\"\nrequires-python = \">=3.12,<3.13\"\ndependencies = [\n \"aiohttp==3.13.3\",\n \"api-analytics==1.2.7\",\n \"fastapi==0.128.8\",\n \"openai==2.21.0\",\n \"PyJWT[crypto]==2.11.0\",\n \"python-dotenv==1.2.1\",\n \"requests==2.32.5\",\n \"tiktoken==0.12.0\",\n \"uvicorn[standard]==0.40.0\",\n]\n\n[dependency-groups]\ndev = [\n \"httpx==0.28.1\",\n \"pytest==8.3.4\",\n]\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.uv]\npackage = false\n" }, { "path": "backend/scripts/validate_mermaid.mjs", "content": "import { createRequire } from \"node:module\";\nimport { stdin, stdout, stderr } from \"node:process\";\n\nimport DOMPurify from \"dompurify\";\n\nconst require = createRequire(import.meta.url);\nlet mermaidInstance = null;\nlet initialized = false;\nlet domPurifyPatched = false;\n\nfunction ensureDomPurifyPatched() {\n if (domPurifyPatched) return;\n\n try {\n const domPurify = DOMPurify;\n if (typeof domPurify === \"function\" && typeof domPurify.sanitize !== \"function\") {\n const { JSDOM } = require(\"jsdom\");\n const domWindow = new JSDOM(\"\").window;\n const domPurifyInstance = domPurify(domWindow);\n Object.assign(domPurify, domPurifyInstance);\n }\n } catch {\n // Best effort patch.\n } finally {\n domPurifyPatched = true;\n }\n}\n\nasync function getMermaid() {\n if (mermaidInstance) return mermaidInstance;\n ensureDomPurifyPatched();\n const mermaidModule = await import(\"mermaid\");\n mermaidInstance = mermaidModule.default;\n return mermaidInstance;\n}\n\nasync function ensureMermaidInitialized() {\n const mermaid = await getMermaid();\n if (initialized) return mermaid;\n mermaid.initialize({\n startOnLoad: false,\n securityLevel: \"loose\",\n });\n initialized = true;\n return mermaid;\n}\n\nasync function readStdin() {\n let data = \"\";\n for await (const chunk of stdin) {\n data += chunk;\n }\n return data;\n}\n\nfunction normalizeError(error) {\n return {\n valid: false,\n message: error?.message || \"Mermaid syntax is invalid and could not be parsed.\",\n line: error?.hash?.line,\n token: error?.hash?.token,\n expected: error?.hash?.expected,\n };\n}\n\nasync function main() {\n try {\n const diagram = (await readStdin()).toString();\n const mermaid = await ensureMermaidInitialized();\n await mermaid.parse(diagram);\n stdout.write(JSON.stringify({ valid: true }));\n } catch (error) {\n stdout.write(JSON.stringify(normalizeError(error)));\n }\n}\n\nmain().catch((error) => {\n stderr.write(String(error?.message || error));\n process.exit(1);\n});\n" }, { "path": "backend/tests/conftest.py", "content": "from pathlib import Path\nimport sys\n\nBACKEND_ROOT = Path(__file__).resolve().parents[1]\nif str(BACKEND_ROOT) not in sys.path:\n sys.path.insert(0, str(BACKEND_ROOT))\n" }, { "path": "backend/tests/test_generate_router.py", "content": "import json\nfrom types import SimpleNamespace\n\nfrom fastapi.testclient import TestClient\n\nfrom app.main import app\nfrom app.routers import generate\nfrom app.services.mermaid_service import MermaidValidationResult\n\nclient = TestClient(app)\n\n\ndef test_healthz_ok():\n response = client.get(\"/healthz\")\n assert response.status_code == 200\n assert response.json() == {\"ok\": True, \"status\": \"ok\"}\n\n\ndef test_generate_cost_success(monkeypatch):\n monkeypatch.setattr(\n generate,\n \"_get_github_data\",\n lambda username, repo, github_pat=None: SimpleNamespace(\n default_branch=\"main\",\n file_tree=\"src/main.py\",\n readme=\"# readme\",\n ),\n )\n monkeypatch.setattr(generate, \"get_model\", lambda: \"gpt-5.4-mini\")\n\n async def fake_count_input_tokens(*, model, system_prompt, data, api_key=None, reasoning_effort=None):\n return 100\n\n monkeypatch.setattr(generate.openai_service, \"count_input_tokens\", fake_count_input_tokens)\n\n response = client.post(\n \"/generate/cost\",\n json={\"username\": \"acme\", \"repo\": \"demo\"},\n )\n\n assert response.status_code == 200\n data = response.json()\n assert data[\"ok\"] is True\n assert data[\"cost\"].endswith(\"USD\")\n assert data[\"model\"] == \"gpt-5.4-mini\"\n assert data[\"pricing_model\"] == \"gpt-5.4-mini\"\n assert \"estimated_input_tokens\" in data\n assert \"estimated_output_tokens\" in data\n\n\ndef test_generate_cost_error(monkeypatch):\n def fail_github_data(username, repo, github_pat=None):\n raise ValueError(\"repo not found\")\n\n monkeypatch.setattr(generate, \"_get_github_data\", fail_github_data)\n\n response = client.post(\n \"/generate/cost\",\n json={\"username\": \"acme\", \"repo\": \"missing\"},\n )\n\n assert response.status_code == 200\n data = response.json()\n assert data[\"ok\"] is False\n assert data[\"error_code\"] == \"COST_ESTIMATION_FAILED\"\n\n\ndef test_generate_stream_event_order_with_fix_loop(monkeypatch):\n monkeypatch.setattr(\n generate,\n \"_get_github_data\",\n lambda username, repo, github_pat=None: SimpleNamespace(\n default_branch=\"main\",\n file_tree=\"src/main.py\",\n readme=\"# readme\",\n ),\n )\n monkeypatch.setattr(generate, \"get_model\", lambda: \"gpt-5.4-mini\")\n\n async def fake_estimate_repo_input_tokens(model, file_tree, readme, api_key=None):\n return 1000\n\n async def fake_stream_completion(*, model, system_prompt, data, api_key=None, reasoning_effort=None, max_output_tokens=None):\n if \"explaining to a principal\" in system_prompt:\n yield \"Repo explanation\"\n return\n if \"mapping key components\" in system_prompt:\n yield \"\"\n yield \"1. API: src/main.py\"\n yield \"\"\n return\n if \"syntax repair specialist\" in system_prompt:\n yield 'flowchart TD\\nA[\"API\"] --> B[\"Worker\"]\\nclick A \"src/main.py\"'\n return\n yield 'flowchart TD\\nA[\"API\"] --> B[\"Worker\"]\\nclick A \"src/main.py\"'\n\n validation_results = iter(\n [\n MermaidValidationResult(valid=False, message=\"bad syntax\"),\n MermaidValidationResult(valid=True),\n ]\n )\n\n monkeypatch.setattr(generate, \"_estimate_repo_input_tokens\", fake_estimate_repo_input_tokens)\n monkeypatch.setattr(generate.openai_service, \"stream_completion\", fake_stream_completion)\n monkeypatch.setattr(generate, \"validate_mermaid_syntax\", lambda diagram: next(validation_results))\n\n response = client.post(\n \"/generate/stream\",\n json={\"username\": \"acme\", \"repo\": \"demo\"},\n )\n\n assert response.status_code == 200\n events = []\n payloads = []\n for block in response.text.split(\"\\n\\n\"):\n if not block.startswith(\"data: \"):\n continue\n payload = json.loads(block[6:])\n payloads.append(payload)\n if \"status\" in payload:\n events.append(payload[\"status\"])\n\n assert \"started\" in events\n assert \"explanation_sent\" in events\n assert \"mapping_sent\" in events\n assert \"diagram_sent\" in events\n assert \"diagram_fixing\" in events\n assert \"diagram_fix_attempt\" in events\n assert \"diagram_fix_validating\" in events\n assert events[-1] == \"complete\"\n complete_payload = payloads[-1]\n assert complete_payload[\"status\"] == \"complete\"\n assert \"https://github.com/acme/demo/blob/main/src/main.py\" in complete_payload[\"diagram\"]\n\n\ndef test_modify_route_removed():\n response = client.post(\"/modify\", json={})\n assert response.status_code == 404\n" }, { "path": "backend/tests/test_generate_utils.py", "content": "from app.routers.generate import process_click_events\n\n\ndef test_process_click_events_builds_blob_and_tree_links():\n diagram = 'flowchart TD\\nclick Api \"src/api.ts\"\\nclick Core \"src/core\"'\n output = process_click_events(diagram, \"u\", \"r\", \"main\")\n\n assert 'click Api \"https://github.com/u/r/blob/main/src/api.ts\"' in output\n assert 'click Core \"https://github.com/u/r/tree/main/src/core\"' in output\n" }, { "path": "backend/tests/test_pricing.py", "content": "from app.services.pricing import estimate_text_token_cost_usd, resolve_pricing_model\n\n\ndef test_resolve_pricing_model_keeps_gpt_5_4_mini_on_its_own_tier():\n assert resolve_pricing_model(\"gpt-5.4-mini\") == \"gpt-5.4-mini\"\n assert resolve_pricing_model(\"gpt-5.4-mini-2026-03-17\") == \"gpt-5.4-mini\"\n\n\ndef test_estimate_text_token_cost_uses_gpt_5_4_mini_pricing():\n cost_usd, pricing_model, pricing = estimate_text_token_cost_usd(\n model=\"gpt-5.4-mini\",\n input_tokens=1_000_000,\n output_tokens=1_000_000,\n )\n\n assert pricing_model == \"gpt-5.4-mini\"\n assert pricing.input_per_million_usd == 0.75\n assert pricing.output_per_million_usd == 4.5\n assert cost_usd == 5.25\n" }, { "path": "components.json", "content": "{\n \"$schema\": \"https://ui.shadcn.com/schema.json\",\n \"style\": \"default\",\n \"rsc\": true,\n \"tsx\": true,\n \"tailwind\": {\n \"config\": \"tailwind.config.ts\",\n \"css\": \"src/styles/globals.css\",\n \"baseColor\": \"neutral\",\n \"cssVariables\": true,\n \"prefix\": \"\"\n },\n \"aliases\": {\n \"components\": \"~/components\",\n \"utils\": \"~/lib/utils\",\n \"ui\": \"~/components/ui\",\n \"lib\": \"~/lib\",\n \"hooks\": \"~/hooks\"\n },\n \"iconLibrary\": \"lucide\"\n}" }, { "path": "docker-compose.yml", "content": "services:\n api:\n build: \n context: ./backend\n dockerfile: Dockerfile\n ports:\n - \"8000:8000\"\n volumes:\n - ./backend:/app\n env_file:\n - .env\n environment:\n - ENVIRONMENT=${ENVIRONMENT:-development} # Default to development if not set\n restart: unless-stopped\n" }, { "path": "docs/dev-setup.md", "content": "# Local Development Setup\n\nThis project runs generation primarily through the FastAPI backend in `backend/` (Railway in production).\n\nNext.js Route Handlers under `/api/generate/*` remain available as an optional fallback path.\n\n## 1) Install tool versions\n\nRecommended versions:\n- Node.js: `22.x` (see `.nvmrc`)\n- pnpm: `9.13.0`\n- Python: `3.12.x` (required for FastAPI backend work)\n- uv: `0.5.24+` (required for FastAPI backend work)\n- Docker: latest stable\n\nInstall/check:\n\n```bash\nnode -v\npnpm -v\npython3 --version\nuv --version\ndocker --version\n```\n\nExpected:\n- Node starts with `v22`\n- pnpm prints `9.13.0` (or compatible in the same series)\n- Python starts with `3.12`\n\n## 2) Install frontend dependencies\n\n```bash\npnpm install\n```\n\n## 3) Sync backend dependencies with uv\n\n```bash\ncd backend\nuv sync --no-install-project\ncd ..\n```\n\nThis creates `backend/.venv` and installs pinned Python dependencies from `backend/uv.lock`.\n\n## 4) Configure environment variables\n\n```bash\ncp .env.example .env\n```\n\nThen set at least:\n- `POSTGRES_URL`\n- `OPENAI_API_KEY`\n\nOptional:\n- `OPENAI_MODEL` (single model used for all generation stages, defaults to `gpt-5.4-mini`)\n- `GITHUB_PAT`\n- `NEXT_PUBLIC_POSTHOG_KEY`\n- `NEXT_PUBLIC_USE_LEGACY_BACKEND=true` and `NEXT_PUBLIC_API_DEV_URL` (to route frontend calls to an external backend such as Railway/local FastAPI)\n\n## 5) Start local services\n\nStart local Postgres (if using local DB URL):\n\n```bash\nchmod +x start-database.sh\n./start-database.sh\n```\n\nPush schema:\n\n```bash\npnpm db:push\n```\n\nStart frontend:\n\n```bash\npnpm dev\n```\n\nStart FastAPI backend (recommended for production parity):\n\n```bash\ndocker-compose up --build -d\ndocker-compose logs -f api\n```\n\nor\n\n```bash\npnpm dev:backend\n```\n\nIf the FastAPI backend is running locally at `http://localhost:8000`, set:\n- `NEXT_PUBLIC_USE_LEGACY_BACKEND=true`\n- `NEXT_PUBLIC_API_DEV_URL=http://localhost:8000`\n\n## 6) Verification commands\n\nRun all baseline checks:\n\n```bash\npnpm check\npnpm test\npnpm build\n```\n\nFastAPI backend checks:\n\n```bash\ncd backend\nuv run pytest -q\nuv run python -m compileall app\ncd ..\n```\n\nIf all pass, your local environment is ready.\n" }, { "path": "docs/railway-backend.md", "content": "# Railway Backend Deploy Guide\n\nThis guide deploys the production FastAPI backend from this monorepo.\n\n## 1) Prerequisites\n\n- Railway account + project access\n- Railway CLI installed\n- Logged in locally:\n\n```bash\nrailway login\n```\n\n## 2) Create/link the Railway service\n\nYou can use dashboard or CLI. CLI flow:\n\n```bash\ncd /path/to/gitdiagram\nrailway init -n gitdiagram\nrailway add --service gitdiagram-api\nrailway link --service gitdiagram-api\n```\n\n## 3) Set backend environment variables\n\nRequired:\n- `OPENAI_API_KEY`\n\nRecommended:\n- `OPENAI_MODEL=gpt-5.4-mini`\n- `ENVIRONMENT=production`\n- `WEB_CONCURRENCY=2`\n- `CORS_ORIGINS=https://gitdiagram.com,https://www.gitdiagram.com,https://`\n\nOptional:\n- `GITHUB_PAT` (higher GitHub API rate limits for repository fetches)\n- `GITHUB_CLIENT_ID`\n- `GITHUB_PRIVATE_KEY`\n- `GITHUB_INSTALLATION_ID`\n- `API_ANALYTICS_KEY`\n\nSet variables via CLI:\n\n```bash\nrailway variables --service gitdiagram-api --set \"OPENAI_API_KEY=...\"\nrailway variables --service gitdiagram-api --set \"OPENAI_MODEL=gpt-5.4-mini\"\nrailway variables --service gitdiagram-api --set \"ENVIRONMENT=production\"\nrailway variables --service gitdiagram-api --set \"WEB_CONCURRENCY=2\"\nrailway variables --service gitdiagram-api --set \"CORS_ORIGINS=https://gitdiagram.com,https://www.gitdiagram.com,https://\"\n```\n\nDo not set `PORT` manually unless needed. Railway injects it automatically.\n\n## 4) Deploy backend from `backend/`\n\n```bash\ncd /path/to/gitdiagram\nrailway up --service gitdiagram-api --path-as-root backend\n```\n\n## 5) Create a public Railway domain\n\n```bash\nrailway domain --service gitdiagram-api\n```\n\nCopy the generated URL, for example:\n`https://gitdiagram-api-production-xxxx.up.railway.app`\n\n## 6) Point Vercel frontend to Railway backend\n\nIn your Vercel project environment variables, set:\n\n- `NEXT_PUBLIC_USE_LEGACY_BACKEND=true`\n- `NEXT_PUBLIC_API_DEV_URL=https://`\n\nThen redeploy Vercel.\n\nNote: the variable name includes \"LEGACY\" for backward compatibility, but this is now the primary external backend path.\n\n## 7) Verify\n\n1. Health endpoint:\n - `GET https:///healthz`\n - expected JSON: `{\"ok\": true, \"status\": \"ok\"}`\n2. Open your frontend and generate a diagram.\n3. Check Railway logs:\n\n```bash\nrailway logs --service gitdiagram-api\n```\n" }, { "path": "drizzle.config.ts", "content": "import { type Config } from \"drizzle-kit\";\n\nimport { env } from \"~/env\";\n\nexport default {\n schema: \"./src/server/db/schema.ts\",\n dialect: \"postgresql\",\n dbCredentials: {\n url: env.POSTGRES_URL,\n },\n tablesFilter: [\"gitdiagram_*\"],\n} satisfies Config;\n" }, { "path": "eslint.config.mjs", "content": "import nextCoreVitals from \"eslint-config-next/core-web-vitals\";\nimport nextTypescript from \"eslint-config-next/typescript\";\nimport drizzle from \"eslint-plugin-drizzle\";\nimport tseslint from \"@typescript-eslint/eslint-plugin\";\n\nconst config = [\n ...nextCoreVitals,\n ...nextTypescript,\n {\n ignores: [\n \".next/**\",\n \"node_modules/**\",\n \"backend/**\",\n \"dist/**\",\n \"coverage/**\",\n \"next-env.d.ts\",\n ],\n },\n {\n files: [\"**/*.{ts,tsx}\"],\n plugins: {\n drizzle,\n \"@typescript-eslint\": tseslint,\n },\n rules: {\n \"@typescript-eslint/array-type\": \"off\",\n \"@typescript-eslint/consistent-type-definitions\": \"off\",\n \"@typescript-eslint/consistent-type-imports\": [\n \"warn\",\n {\n prefer: \"type-imports\",\n fixStyle: \"inline-type-imports\",\n },\n ],\n \"@typescript-eslint/no-require-imports\": \"off\",\n \"@typescript-eslint/no-unused-vars\": [\n \"warn\",\n {\n argsIgnorePattern: \"^_\",\n },\n ],\n \"@typescript-eslint/require-await\": \"off\",\n \"react-hooks/set-state-in-effect\": \"off\",\n \"drizzle/enforce-delete-with-where\": [\n \"error\",\n {\n drizzleObjectName: [\"db\", \"ctx.db\"],\n },\n ],\n \"drizzle/enforce-update-with-where\": [\n \"error\",\n {\n drizzleObjectName: [\"db\", \"ctx.db\"],\n },\n ],\n },\n },\n];\n\nexport default config;\n" }, { "path": "next.config.js", "content": "/**\n * Run `build` or `dev` with `SKIP_ENV_VALIDATION` to skip env validation. This is especially useful\n * for Docker builds.\n */\nimport \"./src/env.js\";\n\n/** @type {import(\"next\").NextConfig} */\nconst config = {\n reactStrictMode: false,\n async rewrites() {\n return [\n {\n source: \"/phx9a/static/:path*\",\n destination: \"https://us-assets.i.posthog.com/static/:path*\",\n },\n {\n source: \"/phx9a/:path*\",\n destination: \"https://us.i.posthog.com/:path*\",\n },\n ];\n },\n // This is required to support PostHog trailing slash API requests\n skipTrailingSlashRedirect: true,\n};\n\nexport default config;\n" }, { "path": "package.json", "content": "{\n \"name\": \"gitdiagram\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"type\": \"module\",\n \"scripts\": {\n \"build\": \"next build\",\n \"check\": \"pnpm lint && tsc --noEmit\",\n \"db:generate\": \"drizzle-kit generate\",\n \"db:migrate\": \"drizzle-kit migrate\",\n \"db:push\": \"drizzle-kit push\",\n \"db:studio\": \"drizzle-kit studio\",\n \"dev\": \"next dev --turbo\",\n \"dev:backend\": \"cd backend && ENVIRONMENT=development uv run --no-dev uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload\",\n \"lint\": \"eslint . --ext .js,.jsx,.ts,.tsx\",\n \"lint:fix\": \"eslint . --ext .js,.jsx,.ts,.tsx --fix\",\n \"preview\": \"next build && next start\",\n \"start\": \"next start\",\n \"start:backend\": \"cd backend && ENVIRONMENT=production uv run --no-dev uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}\",\n \"test\": \"vitest run\",\n \"test:backend\": \"cd backend && uv run pytest -q\",\n \"test:watch\": \"vitest\",\n \"typecheck\": \"tsc --noEmit\",\n \"format:write\": \"prettier --write \\\"**/*.{ts,tsx,js,jsx,mdx}\\\" --cache\",\n \"format:check\": \"prettier --check \\\"**/*.{ts,tsx,js,jsx,mdx}\\\" --cache\"\n },\n \"dependencies\": {\n \"@mermaid-js/layout-elk\": \"^0.2.1\",\n \"@neondatabase/serverless\": \"^1.0.2\",\n \"@radix-ui/react-dialog\": \"^1.1.15\",\n \"@radix-ui/react-progress\": \"^1.1.8\",\n \"@radix-ui/react-slot\": \"^1.2.4\",\n \"@radix-ui/react-switch\": \"^1.2.6\",\n \"@radix-ui/react-tooltip\": \"^1.2.8\",\n \"@t3-oss/env-nextjs\": \"^0.13.10\",\n \"class-variance-authority\": \"^0.7.1\",\n \"clsx\": \"^2.1.1\",\n \"dompurify\": \"^3.3.1\",\n \"dotenv\": \"^17.3.1\",\n \"drizzle-orm\": \"^0.45.1\",\n \"geist\": \"^1.7.0\",\n \"ldrs\": \"^1.1.9\",\n \"lucide-react\": \"^0.574.0\",\n \"mermaid\": \"^11.12.3\",\n \"next\": \"^16.1.6\",\n \"next-themes\": \"^0.4.6\",\n \"openai\": \"^6.22.0\",\n \"postgres\": \"^3.4.8\",\n \"posthog-js\": \"^1.351.3\",\n \"react\": \"^19.2.4\",\n \"react-dom\": \"^19.2.4\",\n \"react-icons\": \"^5.5.0\",\n \"sonner\": \"^2.0.7\",\n \"svg-pan-zoom\": \"^3.6.2\",\n \"tailwind-merge\": \"^3.5.0\",\n \"tailwindcss-animate\": \"^1.0.7\",\n \"zod\": \"^4.3.6\"\n },\n \"devDependencies\": {\n \"@tailwindcss/postcss\": \"4.2.0\",\n \"@testing-library/jest-dom\": \"6.9.1\",\n \"@testing-library/react\": \"16.3.2\",\n \"@types/eslint\": \"^9.6.1\",\n \"@types/node\": \"^25.3.0\",\n \"@types/react\": \"^19.2.14\",\n \"@types/react-dom\": \"^19.2.3\",\n \"@typescript-eslint/eslint-plugin\": \"^8.56.0\",\n \"@typescript-eslint/parser\": \"^8.56.0\",\n \"drizzle-kit\": \"^0.31.9\",\n \"eslint\": \"^9.39.2\",\n \"eslint-config-next\": \"^16.1.6\",\n \"eslint-plugin-drizzle\": \"^0.2.3\",\n \"jsdom\": \"26.1.0\",\n \"postcss\": \"^8.5.6\",\n \"prettier\": \"^3.8.1\",\n \"prettier-plugin-tailwindcss\": \"^0.7.2\",\n \"tailwind-scrollbar\": \"^4.0.2\",\n \"tailwindcss\": \"^4.2.0\",\n \"typescript\": \"^5.9.3\",\n \"vitest\": \"4.0.18\"\n },\n \"ct3aMetadata\": {\n \"initVersion\": \"7.38.1\"\n },\n \"engines\": {\n \"node\": \">=22 <24\",\n \"pnpm\": \">=9 <11\"\n },\n \"packageManager\": \"pnpm@10.30.0\"\n}\n" }, { "path": "postcss.config.js", "content": "const config = {\n plugins: {\n \"@tailwindcss/postcss\": {},\n },\n};\n\nexport default config;\n" }, { "path": "prettier.config.js", "content": "/** @type {import('prettier').Config & import('prettier-plugin-tailwindcss').PluginOptions} */\nconst config = {\n plugins: [\"prettier-plugin-tailwindcss\"],\n};\n\nexport default config;\n" }, { "path": "src/app/[username]/[repo]/page.tsx", "content": "import type { Metadata } from \"next\";\nimport RepoPageClient from \"./repo-page-client\";\n\ntype RepoPageProps = {\n params: Promise<{ username: string; repo: string }>;\n};\n\nexport async function generateMetadata({\n params,\n}: RepoPageProps): Promise {\n const { username, repo } = await params;\n return {\n title: `${username}/${repo} Diagram | GitDiagram`,\n description: `Interactive architecture diagram for ${username}/${repo}.`,\n };\n}\n\nexport default async function Repo({ params }: RepoPageProps) {\n const { username, repo } = await params;\n return ;\n}\n" }, { "path": "src/app/[username]/[repo]/repo-page-client.tsx", "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport MainCard from \"~/components/main-card\";\nimport Loading from \"~/components/loading\";\nimport MermaidChart from \"~/components/mermaid-diagram\";\nimport { useDiagram } from \"~/hooks/useDiagram\";\nimport { ApiKeyDialog } from \"~/components/api-key-dialog\";\nimport { ApiKeyButton } from \"~/components/api-key-button\";\nimport { useStarReminder } from \"~/hooks/useStarReminder\";\n\ntype RepoPageClientProps = {\n username: string;\n repo: string;\n};\n\nexport default function RepoPageClient({ username, repo }: RepoPageClientProps) {\n const [zoomingEnabled, setZoomingEnabled] = useState(false);\n\n useStarReminder();\n\n const normalizedUsername = username.toLowerCase();\n const normalizedRepo = repo.toLowerCase();\n\n const {\n diagram,\n error,\n loading,\n lastGenerated,\n cost,\n showApiKeyDialog,\n handleCopy,\n handleApiKeySubmit,\n handleCloseApiKeyDialog,\n handleOpenApiKeyDialog,\n handleExportImage,\n handleRegenerate,\n state,\n } = useDiagram(normalizedUsername, normalizedRepo);\n\n return (\n
\n
\n setZoomingEnabled((prev) => !prev)}\n loading={loading}\n />\n
\n
\n {loading ? (\n \n ) : error || state.error ? (\n
\n

\n {error || state.error}\n

\n {state.parserError && (\n 
\n                {state.parserError}\n
\n )}\n {(error?.includes(\"API key\") ||\n state.error?.includes(\"API key\")) && (\n
\n \n
\n )}\n
\n ) : (\n
\n \n
\n )}\n
\n\n \n
\n );\n}\n" }, { "path": "src/app/_actions/cache.ts", "content": "\"use server\";\n\nimport { db } from \"~/server/db\";\nimport { eq, and } from \"drizzle-orm\";\nimport { diagramCache } from \"~/server/db/schema\";\nimport { sql } from \"drizzle-orm\";\n\nexport async function getCachedDiagram(username: string, repo: string) {\n try {\n const cached = await db\n .select()\n .from(diagramCache)\n .where(\n and(eq(diagramCache.username, username), eq(diagramCache.repo, repo)),\n )\n .limit(1);\n\n return cached[0]?.diagram ?? null;\n } catch (error) {\n console.error(\"Error fetching cached diagram:\", error);\n return null;\n }\n}\n\nexport async function getCachedExplanation(username: string, repo: string) {\n try {\n const cached = await db\n .select()\n .from(diagramCache)\n .where(\n and(eq(diagramCache.username, username), eq(diagramCache.repo, repo)),\n )\n .limit(1);\n\n return cached[0]?.explanation ?? null;\n } catch (error) {\n console.error(\"Error fetching cached explanation:\", error);\n return null;\n }\n}\n\nexport async function cacheDiagramAndExplanation(\n username: string,\n repo: string,\n diagram: string,\n explanation: string,\n usedOwnKey = false,\n) {\n try {\n await db\n .insert(diagramCache)\n .values({\n username,\n repo,\n diagram,\n explanation,\n usedOwnKey,\n })\n .onConflictDoUpdate({\n target: [diagramCache.username, diagramCache.repo],\n set: {\n diagram,\n explanation,\n usedOwnKey,\n updatedAt: new Date(),\n },\n });\n } catch (error) {\n console.error(\"Error caching diagram:\", error);\n }\n}\n\nexport async function getDiagramStats() {\n try {\n const stats = await db\n .select({\n totalDiagrams: sql`COUNT(*)`,\n ownKeyUsers: sql`COUNT(CASE WHEN ${diagramCache.usedOwnKey} = true THEN 1 END)`,\n freeUsers: sql`COUNT(CASE WHEN ${diagramCache.usedOwnKey} = false THEN 1 END)`,\n })\n .from(diagramCache);\n\n return stats[0];\n } catch (error) {\n console.error(\"Error getting diagram stats:\", error);\n return null;\n }\n}\n" }, { "path": "src/app/_actions/repo.ts", "content": "\"use server\";\n\nimport { db } from \"~/server/db\";\nimport { eq, and } from \"drizzle-orm\";\nimport { diagramCache } from \"~/server/db/schema\";\n\nexport async function getLastGeneratedDate(username: string, repo: string) {\n const result = await db\n .select()\n .from(diagramCache)\n .where(\n and(eq(diagramCache.username, username), eq(diagramCache.repo, repo)),\n );\n\n return result[0]?.updatedAt;\n}\n" }, { "path": "src/app/api/generate/cost/route.ts", "content": "import { NextResponse } from \"next/server\";\n\nimport { toTaggedMessage } from \"~/server/generate/format\";\nimport { getGithubData } from \"~/server/generate/github\";\nimport { getModel } from \"~/server/generate/model-config\";\nimport { countInputTokens, estimateTokens } from \"~/server/generate/openai\";\nimport { SYSTEM_FIRST_PROMPT } from \"~/server/generate/prompts\";\nimport { estimateTextTokenCostUsd } from \"~/server/generate/pricing\";\nimport { generateRequestSchema } from \"~/server/generate/types\";\n\nexport const runtime = \"nodejs\";\nexport const dynamic = \"force-dynamic\";\nexport const maxDuration = 300;\nconst MULTI_STAGE_INPUT_MULTIPLIER = 2;\nconst INPUT_OVERHEAD_TOKENS = 3000;\nconst ESTIMATED_OUTPUT_TOKENS = 8000;\n\nasync function estimateRepoInputTokens(\n model: string,\n fileTree: string,\n readme: string,\n apiKey?: string,\n) {\n try {\n return await countInputTokens({\n model,\n systemPrompt: SYSTEM_FIRST_PROMPT,\n userPrompt: toTaggedMessage({\n file_tree: fileTree,\n readme,\n }),\n apiKey,\n reasoningEffort: \"medium\",\n });\n } catch {\n return estimateTokens(`${fileTree}\\n${readme}`);\n }\n}\n\nexport async function POST(request: Request) {\n try {\n const parsed = generateRequestSchema.safeParse(await request.json());\n if (!parsed.success) {\n return NextResponse.json({\n ok: false,\n error: \"Invalid request payload.\",\n error_code: \"VALIDATION_ERROR\",\n });\n }\n\n const {\n username,\n repo,\n api_key: apiKey,\n github_pat: githubPat,\n } = parsed.data;\n const githubData = await getGithubData(username, repo, githubPat);\n const model = getModel();\n\n const baseInputTokens = await estimateRepoInputTokens(\n model,\n githubData.fileTree,\n githubData.readme,\n apiKey,\n );\n const estimatedInputTokens =\n baseInputTokens * MULTI_STAGE_INPUT_MULTIPLIER + INPUT_OVERHEAD_TOKENS;\n const estimatedOutputTokens = ESTIMATED_OUTPUT_TOKENS;\n\n const { costUsd, pricingModel, pricing } = estimateTextTokenCostUsd(\n model,\n estimatedInputTokens,\n estimatedOutputTokens,\n );\n\n return NextResponse.json({\n ok: true,\n cost: `$${costUsd.toFixed(2)} USD`,\n model,\n pricing_model: pricingModel,\n estimated_input_tokens: estimatedInputTokens,\n estimated_output_tokens: estimatedOutputTokens,\n pricing: {\n input_per_million_usd: pricing.inputPerMillionUsd,\n output_per_million_usd: pricing.outputPerMillionUsd,\n },\n });\n } catch (error) {\n return NextResponse.json({\n ok: false,\n error:\n error instanceof Error\n ? error.message\n : \"Failed to estimate generation cost.\",\n error_code: \"COST_ESTIMATION_FAILED\",\n });\n }\n}\n" }, { "path": "src/app/api/generate/stream/route.ts", "content": "import { getModel } from \"~/server/generate/model-config\";\nimport {\n extractComponentMapping,\n processClickEvents,\n stripMermaidCodeFences,\n toTaggedMessage,\n} from \"~/server/generate/format\";\nimport { getGithubData } from \"~/server/generate/github\";\nimport {\n formatValidationFeedback,\n validateMermaidSyntax,\n} from \"~/server/generate/mermaid\";\nimport {\n countInputTokens,\n estimateTokens,\n streamCompletion,\n} from \"~/server/generate/openai\";\nimport {\n SYSTEM_FIRST_PROMPT,\n SYSTEM_FIX_MERMAID_PROMPT,\n SYSTEM_SECOND_PROMPT,\n SYSTEM_THIRD_PROMPT,\n} from \"~/server/generate/prompts\";\nimport { generateRequestSchema, sseMessage } from \"~/server/generate/types\";\n\nexport const runtime = \"nodejs\";\nexport const dynamic = \"force-dynamic\";\nexport const maxDuration = 300;\nconst MAX_MERMAID_FIX_ATTEMPTS = 3;\n\nfunction sleep(ms: number) {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nasync function estimateRepoTokenCount(\n model: string,\n fileTree: string,\n readme: string,\n apiKey?: string,\n) {\n try {\n return await countInputTokens({\n model,\n systemPrompt: SYSTEM_FIRST_PROMPT,\n userPrompt: toTaggedMessage({\n file_tree: fileTree,\n readme,\n }),\n apiKey,\n reasoningEffort: \"medium\",\n });\n } catch {\n return estimateTokens(`${fileTree}\\n${readme}`);\n }\n}\n\nexport async function POST(request: Request) {\n const parsed = generateRequestSchema.safeParse(await request.json());\n\n if (!parsed.success) {\n return new Response(\n JSON.stringify({\n ok: false,\n error: \"Invalid request payload.\",\n error_code: \"VALIDATION_ERROR\",\n }),\n { status: 400, headers: { \"Content-Type\": \"application/json\" } },\n );\n }\n\n const { username, repo, api_key: apiKey, github_pat: githubPat } = parsed.data;\n\n const encoder = new TextEncoder();\n\n const stream = new ReadableStream({\n start(controller) {\n const send = (payload: Record) => {\n controller.enqueue(encoder.encode(sseMessage(payload)));\n };\n\n const run = async () => {\n try {\n const githubData = await getGithubData(username, repo, githubPat);\n const model = getModel();\n const tokenCount = await estimateRepoTokenCount(\n model,\n githubData.fileTree,\n githubData.readme,\n apiKey,\n );\n\n send({\n status: \"started\",\n message: \"Starting generation process...\",\n });\n\n if (tokenCount > 50000 && tokenCount < 195000 && !apiKey) {\n send({\n status: \"error\",\n error:\n \"File tree and README combined exceeds token limit (50,000). This repository is too large for free generation. Provide your own OpenAI API key to continue.\",\n error_code: \"API_KEY_REQUIRED\",\n });\n controller.close();\n return;\n }\n\n if (tokenCount > 195000) {\n send({\n status: \"error\",\n error:\n \"Repository is too large (>195k tokens) for analysis. Try a smaller repo.\",\n error_code: \"TOKEN_LIMIT_EXCEEDED\",\n });\n controller.close();\n return;\n }\n\n send({\n status: \"explanation_sent\",\n message: `Sending explanation request to ${model}...`,\n });\n await sleep(80);\n send({\n status: \"explanation\",\n message: \"Analyzing repository structure...\",\n });\n\n let explanation = \"\";\n for await (const chunk of streamCompletion({\n model,\n systemPrompt: SYSTEM_FIRST_PROMPT,\n userPrompt: toTaggedMessage({\n file_tree: githubData.fileTree,\n readme: githubData.readme,\n }),\n apiKey,\n reasoningEffort: \"medium\",\n })) {\n explanation += chunk;\n send({ status: \"explanation_chunk\", chunk });\n }\n\n send({\n status: \"mapping_sent\",\n message: `Sending component mapping request to ${model}...`,\n });\n await sleep(80);\n send({\n status: \"mapping\",\n message: \"Creating component mapping...\",\n });\n\n let fullMappingResponse = \"\";\n for await (const chunk of streamCompletion({\n model,\n systemPrompt: SYSTEM_SECOND_PROMPT,\n userPrompt: toTaggedMessage({\n explanation,\n file_tree: githubData.fileTree,\n }),\n apiKey,\n reasoningEffort: \"low\",\n })) {\n fullMappingResponse += chunk;\n send({ status: \"mapping_chunk\", chunk });\n }\n\n const componentMapping = extractComponentMapping(fullMappingResponse);\n\n send({\n status: \"diagram_sent\",\n message: `Sending diagram generation request to ${model}...`,\n });\n await sleep(80);\n send({\n status: \"diagram\",\n message: \"Generating diagram...\",\n });\n\n let mermaidCode = \"\";\n for await (const chunk of streamCompletion({\n model,\n systemPrompt: SYSTEM_THIRD_PROMPT,\n userPrompt: toTaggedMessage({\n explanation,\n component_mapping: componentMapping,\n }),\n apiKey,\n reasoningEffort: \"low\",\n })) {\n mermaidCode += chunk;\n send({ status: \"diagram_chunk\", chunk });\n }\n\n let candidateDiagram = stripMermaidCodeFences(mermaidCode);\n let validationResult = await validateMermaidSyntax(candidateDiagram);\n const hadFixLoop = !validationResult.valid;\n\n if (!validationResult.valid) {\n const parserFeedback = formatValidationFeedback(validationResult);\n send({\n status: \"diagram_fixing\",\n message:\n \"Diagram generated. Mermaid syntax validation failed, starting auto-fix loop...\",\n parser_error: parserFeedback,\n });\n }\n\n for (\n let attempt = 1;\n !validationResult.valid && attempt <= MAX_MERMAID_FIX_ATTEMPTS;\n attempt++\n ) {\n const parserFeedback = formatValidationFeedback(validationResult);\n send({\n status: \"diagram_fix_attempt\",\n message: `Fixing Mermaid syntax (attempt ${attempt}/${MAX_MERMAID_FIX_ATTEMPTS})...`,\n fix_attempt: attempt,\n fix_max_attempts: MAX_MERMAID_FIX_ATTEMPTS,\n parser_error: parserFeedback,\n });\n\n let repairedDiagram = \"\";\n for await (const chunk of streamCompletion({\n model,\n systemPrompt: SYSTEM_FIX_MERMAID_PROMPT,\n userPrompt: toTaggedMessage({\n mermaid_code: candidateDiagram,\n parser_error: parserFeedback,\n explanation,\n component_mapping: componentMapping,\n }),\n apiKey,\n reasoningEffort: \"low\",\n })) {\n repairedDiagram += chunk;\n send({\n status: \"diagram_fix_chunk\",\n chunk,\n fix_attempt: attempt,\n fix_max_attempts: MAX_MERMAID_FIX_ATTEMPTS,\n });\n }\n\n candidateDiagram = stripMermaidCodeFences(repairedDiagram);\n send({\n status: \"diagram_fix_validating\",\n message: `Validating Mermaid syntax after attempt ${attempt}/${MAX_MERMAID_FIX_ATTEMPTS}...`,\n fix_attempt: attempt,\n fix_max_attempts: MAX_MERMAID_FIX_ATTEMPTS,\n });\n validationResult = await validateMermaidSyntax(candidateDiagram);\n }\n\n if (!validationResult.valid) {\n send({\n status: \"error\",\n error:\n \"Generated Mermaid remained syntactically invalid after auto-fix attempts. Please retry generation.\",\n error_code: \"MERMAID_SYNTAX_UNRESOLVED\",\n parser_error: formatValidationFeedback(validationResult),\n });\n return;\n }\n\n const processedDiagram = processClickEvents(\n candidateDiagram,\n username,\n repo,\n githubData.defaultBranch,\n );\n\n if (hadFixLoop) {\n send({\n status: \"diagram_fixing\",\n message: \"Mermaid syntax validated. Finalizing diagram output...\",\n });\n }\n\n send({\n status: \"complete\",\n diagram: processedDiagram,\n explanation,\n mapping: componentMapping,\n });\n } catch (error) {\n send({\n status: \"error\",\n error:\n error instanceof Error\n ? error.message\n : \"Streaming generation failed.\",\n error_code: \"STREAM_FAILED\",\n });\n } finally {\n controller.close();\n }\n };\n\n void run();\n },\n });\n\n return new Response(stream, {\n headers: {\n \"Content-Type\": \"text/event-stream; charset=utf-8\",\n \"Cache-Control\": \"no-cache, no-transform\",\n Connection: \"keep-alive\",\n \"X-Accel-Buffering\": \"no\",\n },\n });\n}\n" }, { "path": "src/app/api/healthz/route.ts", "content": "import { NextResponse } from \"next/server\";\n\nexport const runtime = \"nodejs\";\nexport const dynamic = \"force-dynamic\";\n\nexport async function GET() {\n return NextResponse.json({ ok: true, status: \"ok\" });\n}\n" }, { "path": "src/app/layout.tsx", "content": "import \"~/styles/globals.css\";\n\nimport { GeistSans } from \"geist/font/sans\";\nimport { type Metadata } from \"next\";\nimport { Header } from \"~/components/header\";\nimport { Footer } from \"~/components/footer\";\nimport { CSPostHogProvider } from \"./providers\";\nimport { Toaster } from \"~/components/ui/sonner\";\n\nexport const metadata: Metadata = {\n title: \"GitDiagram\",\n description:\n \"Turn any GitHub repository into an interactive diagram for visualization in seconds.\",\n metadataBase: new URL(\"https://gitdiagram.com\"),\n keywords: [\n \"github\",\n \"git diagram\",\n \"git diagram generator\",\n \"git diagram tool\",\n \"git diagram maker\",\n \"git diagram creator\",\n \"git diagram\",\n \"diagram\",\n \"repository\",\n \"visualization\",\n \"code structure\",\n \"system design\",\n \"software architecture\",\n \"software design\",\n \"software engineering\",\n \"software development\",\n \"software architecture\",\n \"software design\",\n \"software engineering\",\n \"software development\",\n \"open source\",\n \"open source software\",\n \"ahmedkhaleel2004\",\n \"ahmed khaleel\",\n \"gitdiagram\",\n \"gitdiagram.com\",\n ],\n authors: [\n { name: \"Ahmed Khaleel\", url: \"https://github.com/ahmedkhaleel2004\" },\n ],\n creator: \"Ahmed Khaleel\",\n openGraph: {\n type: \"website\",\n locale: \"en_US\",\n url: \"https://gitdiagram.com\",\n title: \"GitDiagram - Repository to Diagram in Seconds\",\n description:\n \"Turn any GitHub repository into an interactive diagram for visualization.\",\n siteName: \"GitDiagram\",\n images: [\n {\n url: \"/og-image.png\", // You'll need to create this image\n width: 1200,\n height: 630,\n alt: \"GitDiagram - Repository Visualization Tool\",\n },\n ],\n },\n robots: {\n index: true,\n follow: true,\n googleBot: {\n index: true,\n follow: true,\n \"max-snippet\": -1,\n },\n },\n};\n\nexport default function RootLayout({\n children,\n}: Readonly<{ children: React.ReactNode }>) {\n return (\n \n \n \n
\n
{children}
\n