GitDiagram — GitHub 저장소를 몇 초 만에 인터랙티브 아키텍처 다이어그램으로 변환

본문

GitDiagram은 GitHub 저장소의 디렉터리 트리, README, 그리고 제한된 범위로 추출한 소스 코드 발췌(excerpt)를 입력으로 받아 단순한 폴더 구조가 아닌 시스템 수준의 아키텍처 그래프를 생성하는 도구입니다. 생성된 다이어그램의 각 컴포넌트를 클릭하면 GitHub 상의 실제 파일이나 디렉터리로 연결되며, 결과는 Mermaid 소스 복사나 PNG 다운로드로 내보낼 수 있습니다. 비공개 저장소도 지원하는데, 브라우저에서 fine-grained GitHub PAT를 직접 제공하면 해당 토큰은 같은 origin의 관련 요청에만 실려 전송되고 공개 다이어그램 링크에는 포함되지 않습니다.

생성 파이프라인과 검증 절차

생성 과정은 여러 단계로 구성됩니다. 먼저 GitHub API로 기본 브랜치의 재귀 트리와 README를 가져오는데, 잘린 트리나 크기 초과 입력은 모델 작업 전에 거부됩니다. 이후 무결성 검사를 거친 소스 발췌를 선택하는데, 실질적인 런타임 모듈을 우선하고 긴 파일에서는 발췌를 분산시키며 샘플링된 호출의 import 바인딩을 보존합니다. 기본 관리형 파이프라인은 GPT-5.6 Luna를 medium reasoning으로 한 번 호출해 짧은 아키텍처 개요를 스트리밍한 뒤 그룹·노드·엣지·레이블·저장소 경로로 이루어진 엄격한 그래프를 반환받습니다. 서버는 식별자, 그래프 연결성, 제한, 링크된 모든 경로를 실제 저장소와 대조해 검증하고, 무효 출력은 구체적 피드백과 함께 재시도합니다. 검증된 AST는 결정론적 컴파일러가 완전한 텍스트 이스케이핑과 GitHub 전용 링크로 Mermaid로 변환하고, 브라우저에서는 Mermaid 소스를 sanitize한 뒤 strict security mode로 렌더링하고 결과 SVG를 다시 sanitize하며 링크 allowlist를 재적용합니다. Mermaid 파서 전체는 테스트 스위트의 컴파일러 계약 테스트로만 유지하고 프로덕션 생성 함수에는 로드하지 않아 서버 번들을 작게 유지합니다.

인프라와 비용 설계

애플리케이션은 Next.js 16 App Router, React 19, TypeScript, Tailwind CSS, Radix UI로 작성됐으며, Vercel의 Bun 런타임 위에서 same-origin Route Handlers가 UI와 생성 엔드포인트를 모두 제공합니다. 별도의 FastAPI 구현이나 Postgres, Neon 런타임은 없습니다. API는 비용 추정 /api/generate/cost, SSE 스트리밍 /api/generate/stream, 취소 /api/generate/cancel, 상태 영속화 /api/diagram-state, 헬스체크 /api/healthz로 구성됩니다. 장시간 생성에는 300초 Vercel 함수 예산 안에 더 짧은 애플리케이션 데드라인을 두어 쿼터 정산과 영속화가 끝날 시간을 확보하고, 명시적 업스트림 데드라인·재시도·구조화 로그·하트비트·분산 취소를 사용합니다. 스토리지는 Cloudflare R2이고, Upstash Redis가 쿼터 계산·취소·락·단기 실패 상태를 맡으며, PostHog로 분석합니다. 관리형 GPT-5.6 요청은 Fast mode(service_tier: "priority")를 명시적으로 사용해 프리미엄이 추정 비용에 포함되고, 최종 비용은 실제 서빙된 모델과 티어로 계산됩니다. 사용자 제공 키는 표준 서비스와 설정된 모델을 유지하고, 명시적 모델 오버라이드와 OpenRouter는 2단계 파이프라인을 그대로 씁니다.

영속성과 운영 전략

성공한 공개 생성물은 저장소를 키로 하는 R2 객체로, 비공개 생성물은 서버 측 시크릿으로 파생된 별도 R2 네임스페이스에 저장되어 이후 방문에서는 모델 호출 없이 다이어그램을 다시 열 수 있습니다. 동시 쓰기는 분산 락과 newest-session-wins 영속화로 처리하고, 저장물 없이 종료된 실패는 단기 Upstash 상태로 남깁니다. Vercel이 유일한 라이브 런타임이지만, 재해 복구용으로 non-root standalone Docker 이미지와 railway.json을 레포지토리에 보관해 Railway에서 전체 앱을 재구성할 수 있는 콜드 리커버리 레시피를 유지합니다(docs/deployment-failover.md). 로컬 개발은 bun install 후 .env를 구성하고 bun run dev로 실행하며, 최소한 R2·Upstash·AI 제공자 하나를 설정해야 합니다. PR 전에는 lint, typecheck, test, build 게이트를 통과해야 합니다. 프로젝트는 Romain Courtois의 Gitingest에서 영감을 받았습니다.

원문: GitHub / 번역·요약: Trawling