GitHub 코드베이스 탐험, 이제 Codebase Navigator로
Codebase Navigator는 GitHub URL을 입력하면 실제 import 문을 기반으로 한 의존성 그래프(Dependency Graph)를 실시간으로 시각화하여 코드베이스 탐색을 지원함
CopilotKit을 활용하여 AI 에이전트(AI Agent)와 UI를 통합하고, Zustand를 통해 상태를 관리하여 네 개의 패널(Graph, Code Viewer, Chat, File Tree) 간의 실시간 동기화를 구현함
Next.js API routes를 통해 GitHub API에 안전하게 접근하고, Ollama 또는 OpenAI를 백엔드로 사용하여 로컬 또는 클라우드 환경에서 AI 추론을 수행함
Zenflow를 사용하여 프로젝트를 계획, 구축, 테스트, 검토 및 배포하는 과정을 자동화하고, 코드 품질을 향상시킴
React Flow를 활용하여 인터랙티브한 의존성 그래프를 생성하고, 파일 내용 및 코드 하이라이팅 기능을 제공하여 코드베이스 이해도를 높임
Codebase Navigator의 핵심 아키텍처
Codebase Navigator는 브라우저(Browser), Next.js API routes, GitHub API 및 LLM 백엔드의 세 계층으로 구성된다. 브라우저는 UI 및 AI 도구 로직을 처리하고, Next.js API routes는 외부 서비스에 대한 보안 프록시 역할을 수행한다. GitHub API와 LLM 백엔드는 하단에 위치하며, 브라우저가 직접 GitHub 또는 LLM과 통신하지 않도록 데이터 격리 아키텍처(Data Isolation Architecture)를 적용했다.
Zustand: 상태 관리를 위해 사용되며, 네 개의 주요 패널(Chat, Graph, Code Viewer, File Tree) 간의 실시간 동기화를 담당한다.
CopilotKit: AI 에이전트와 UI를 연결하여, 사용자의 질문에 대한 답변을 생성하고, 도구를 호출하여 UI를 업데이트한다.
React Flow: 실시간으로 업데이트되는 인터랙티브한 의존성 그래프를 시각화하는 데 사용된다.
의존성 그래프(Dependency Graph) 생성 과정
Codebase Navigator는 로드 시점과 질문에 대한 답변 시점에 서로 다른 방식으로 의존성 그래프를 생성한다. 초기 로드 시에는 `buildOverviewGraph` 함수를 사용하여 파일 트리 구조를 기반으로 한 폴더 맵을 생성한다. 사용자가 질문을 하면, `buildDependencyNodes` 함수가 호출되어 실제 import 문을 분석하여 파일 간의 의존 관계를 나타내는 그래프를 생성한다.
`buildOverviewGraph`: 파일 트리 구조를 기반으로 폴더 맵을 생성하며, 파일 내용을 fetch하지 않는다.
`buildDependencyNodes`: 실제 import 문을 분석하여 파일 간의 의존 관계를 나타내는 그래프를 생성한다.
`setVisualization`: Zustand store를 업데이트하여 그래프 패널을 렌더링한다.
이러한 과정을 통해, 사용자는 코드베이스의 구조를 직관적으로 파악하고, 질문에 대한 답변과 관련된 파일들의 의존 관계를 시각적으로 확인할 수 있다.
CopilotKit을 활용한 AI 기반 코드베이스 탐색
Codebase Navigator는 CopilotKit을 사용하여 AI 에이전트와 UI를 통합하고, 사용자 질문에 대한 답변을 생성한다. `/api/copilotkit` API route는 LLM 요청을 처리하며, OpenAI 호환 백엔드(Ollama, OpenAI 등)를 사용할 수 있도록 구성되어 있다. `useCopilotContext` 훅을 사용하여 파일 목록과 시스템 지침을 LLM에 제공하며, `useFrontendTool` 훅을 통해 다양한 도구를 등록하여 LLM이 호출할 수 있도록 한다.
`analyzeRepository`: 질문에 따라 관련 파일을 찾고, 의존성 그래프를 생성하며, 분석 결과를 Zustand store에 저장한다.
`fetchFileContent`: 특정 파일의 내용을 가져와 코드 뷰어에 표시한다.
`generateFlowDiagram`: 지정된 파일들의 의존성 그래프를 생성한다.
`highlightCode`: 특정 코드 라인을 강조 표시한다.
이러한 도구들을 통해 LLM은 코드베이스를 이해하고, 사용자의 질문에 대한 답변을 시각적으로 제공한다.
Zenflow를 활용한 개발 프로세스 자동화
Codebase Navigator는 Zenflow를 사용하여 개발 프로세스를 구조화하고 자동화했다. Zenflow는 소프트웨어 개발을 코드 자동 완성 이상의 구조화된 엔지니어링 프로세스(Structured Engineering Process)로 취급하며, 프로젝트 계획, 구축, 테스트, 검토 및 배포를 단일 세션 내에서 수행할 수 있도록 지원한다. Zenflow는 다음과 같은 여섯 단계를 거쳐 프로젝트를 진행했다.
아키텍처 및 사양 정의: 프로젝트의 구조와 기능을 정의한다.
스캐폴딩 및 기초 작업: 프로젝트의 기본 구조를 설정한다.
데이터 계층 구현: GitHub API와의 통합을 구현한다.
AI 계층 구현: CopilotKit 액션 및 컨텍스트를 구현한다.
시각적 계층 구현: React Flow 그래프를 구현한다.
최종 조립 및 연결: 모든 구성 요소를 통합하고 연결한다.
각 단계는 린트(Lint), 타입 검사(Type Checks), 테스트를 통해 검증되었으며, 코드 검토를 통해 14개의 문제를 발견하고 11개를 수정했다. 이러한 과정을 통해 코드 품질을 향상시키고, 개발 효율성을 높였다.
GitHub API 프록싱 및 파일 캐싱 전략
Codebase Navigator는 Next.js API routes를 통해 GitHub API에 접근하여, API 키 노출을 방지하고 보안을 강화한다. `/api/github/*` 경로를 통해 GitHub API를 프록시하며, `fetchFile` 함수는 파일 내용을 가져오기 전에 in-memory cache를 확인하여, 5분 TTL(Time-To-Live)을 가진 캐싱 전략을 사용한다. 캐싱을 통해 불필요한 API 호출을 줄이고, 성능을 향상시킨다.
`parseRepoUrl`: GitHub URL을 파싱하여 owner와 repo 정보를 추출한다.
`getDefaultBranch`: 기본 브랜치를 가져온다.
`getRepoTree`: GitHub Trees API를 사용하여 파일 트리 구조를 가져온다.
`fetchFile`: 파일 내용을 가져오고, 캐싱을 관리한다.
이러한 전략을 통해, Codebase Navigator는 GitHub API의 rate limit을 효율적으로 관리하고, 사용자 경험을 개선한다.
