Sign InSign Up

Google Maps for Codebases: Paste a GitHub URL, Ask Anything

Navigating a large codebase for the first time is painful. You clone the repo, realize there are 300 files, and have no idea where anything lives.

You can ask an AI assistant, but it burns through context fast and you never know if it hallucinated a file path that does not even exist.

Codebase Navigator solves this. Paste a URL, ask anything in plain English, and watch a real dependency graph built from actual import statements appear in real time.

It is built using CopilotKit, Zenflow, GitHub API and React Flow. You can run it completely free using Ollama locally.

In this blog, we will go through the architecture, the key patterns and how everything works end-to-end.

What are we building?

Codebase Navigator lets you paste any public GitHub repo URL and ask questions about it in plain English. Instead of getting a wall of text back, you get four panels that all update at once.

Panel What it does
Graph Canvas Live dependency graph built from real import statements
Code Viewer File content fetched live from GitHub, relevant lines highlighted
Repo Explorer Full file tree, click any file to open it
Chat Follow-up questions and plain English explanations

The graph morphs to show every relevant file connected by real imports, the code viewer opens the file, and the chat explains what each piece does. No context switching.

You can run it completely free using Ollama locally without any API key.

ollama

Here is the full request → response flow of what happens when you ask a question:

User types "how does auth work?"
     ↓
CopilotChat → POST /api/copilotkit
     ↓
LLM receives repo context (file paths, current selection, system rules)
     ↓
LLM calls analyzeRepository tool
     ↓
Tool fetches relevant files via /api/github/file
     ↓
Extracts import/require statements → resolves paths → builds dependency graph
     ↓
Zustand store updates
     ↓
All four panels re-render live: graph, file tree, code viewer, chat response
Enter fullscreen mode Exit fullscreen mode

Tech Stack & Tools

At a high level, this project is built by combining:

  • Next.js 16 - frontend and API routes

  • CopilotKit - agent-UI state sync and chat interface. provides built-in hooks & components like useAgentContext, useFrontendTool, CopilotChat

  • Zenflow - workflow tool that planned, tested and orchestrated the build

  • React Flow & dagre - interactive dependency graphs with automatic layout

  • Octokit - GitHub API proxy for fetching repo trees and file contents

  • Zustand - shared state across all four panels

  • Tailwind CSS - styling

  • Ollama / OpenAI - local or cloud LLM backend switchable from the UI

The CopilotKit runtime is self-hosted inside a Next.js API route, which lets you plug into any OpenAI-compatible backend, including Ollama, for completely free local inference.

It connects your UI, agents, and tools into a single interaction loop.

agent interaction loop

 

What is Zenflow?

Zenflow is an AI development tool that treats building software as a structured engineering process rather than just autocompleting code.

This project was planned, built, tested, reviewed and deployed using Zenflow (Zencoder's workflow engine) in a single session.

zenflow

It ran a six-phase process from scratch:

  • Architecture and spec
  • Scaffolding and foundation
  • Data layer (GitHub API integration)
  • AI layer (CopilotKit actions and context)
  • Visual layer (React Flow graphs)
  • Final assembly and wiring

Each phase was verified with lint, type checks and tests before moving to the next. After the build, it performed a code review, found 14 issues and fixed 11 systematically:

  • API keys exposed in headers → moved to httpOnly cookies
  • Fake star-shaped graphs → replaced with real import-based dependency resolution
  • Duplicate file-fetching logic → consolidated into a single cached utility

The .zenflow/ folder in the repo contains the task plan, spec, and report files it generated along the way.

That's how we built it with Zenflow. Here's the architecture that came out of it.

Architecture & Project Structure

The app is split into three layers: the browser handles all UI and AI tool logic, Next.js API routes act as a secure proxy to external services, and GitHub API, plus the LLM backend sits at the bottom. Nothing in the browser talks to GitHub or the LLM directly.

Below is a high-level overview of all the layers and how they are organized.

┌─────────────────────────────────────────────────────────┐
│                        BROWSER                          │
│                                                         │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐    │
│  │  Chat   │  │  Graph   │  │  Code    │  │  File  │    │
│  │  Panel  │  │  Canvas  │  │  Viewer  │  │  Tree  │    │
│  └────┬────┘  └────┬─────┘  └────┬─────┘  └───┬────┘    │
│       └────────────┴─────────────┴────────────┘         │
│                          │                              │
│                   ┌──────▼──────┐                       │
│                   │   Zustand   │  ← shared state       │
│                   └──────┬──────┘                       │
│                          │                              │
│              ┌───────────▼────────────┐                 │
│              │      CopilotKit        │                 │
│              │   frontend tools       │                 │
│              │  analyzeRepository     │                 │
│              │  fetchFileContent      │                 │
│              │  highlightCode         │                 │
│              └───────────┬────────────┘                 │
└──────────────────────────┼──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                    NEXT.JS API ROUTES                   │
│                                                         │
│   /api/copilotkit     /api/github/*     /api/settings   │
│   (LLM runtime)       (proxy)          (httpOnly cookie)│
└──────────┬────────────────┬─────────────────────────────┘
           │                │
     ┌─────▼─────┐   ┌──────▼──────┐
     │  Ollama   │   │  GitHub API │
     │  / OpenAI │   │  (Octokit)  │
     └───────────┘   └─────────────┘
Enter fullscreen mode Exit fullscreen mode

architecture

Here is a simplified view of how the project is structured.

src/
├── app/api/
│   ├── copilotkit/route.ts    → CopilotKit runtime endpoint
│   ├── github/
│   │   ├── tree/route.ts      → fetch repo tree
│   │   ├── file/route.ts      → fetch + base64-decode file
│   │   └── search/route.ts    → code search
│   └── settings/route.ts      → LLM config (httpOnly cookie)
├── components/
│   ├── panels/     → 5 UI panels (chat, graph, code, analysis, repo)
│   └── flow/       → custom React Flow node types
├── hooks/          → AI tool registration, agent context sync, repo loading
├── lib/            → import extraction, dagre layout, Octokit client
├── store/          → Zustand (AppState + SettingsState)
└── .zenflow/       → Zenflow task plan, spec and report
Enter fullscreen mode Exit fullscreen mode

Let's get into how everything works behind the scenes. This will help you understand the key patterns.

How everything works under the hood

Now that you have the big picture, let's go through each piece in detail.

A lot is happening under the surface, so we will break it down into ten parts, starting from when you first load a repo all the way to how state flows across the panels.

1. Loading a repository

When you paste a GitHub URL and click Explore, useRepository.loadRepository() fires (from useRepository.ts hook).

It calls /api/github/tree on the server, which uses Octokit to:

  • Parse the repo URL into { owner, repo }
  • Fetch the default branch
  • Get the full recursive file tree from the GitHub Trees API
  • Convert the flat array into a nested TreeNode structure

Here is what the src/api/github/tree/route.ts route looks like:

export async function GET(request: NextRequest) {
  const { owner, repo } = parseRepoUrl(repoUrl);
  const resolvedBranch = branch || (await getDefaultBranch(owner, repo));
  const tree = await getRepoTree(owner, repo, resolvedBranch);

  return NextResponse.json({ owner, repo, branch: resolvedBranch, tree });
}
Enter fullscreen mode Exit fullscreen mode

That nested tree powers the sidebar file explorer and becomes the starting point for everything else.

All GitHub calls are proxied through Next.js API routes. The browser never talks to GitHub directly to keep tokens secure.

file tree loaded on the left sidebar

 

2. From architecture view to dependency graph

This is the visual moment that makes the app feel alive. The graph you see on load (the architecture view) and the graph you see after asking a question (the dependency graph) are two completely different things, built two different ways.

Both live in src/lib/analyzer.ts - buildOverviewGraph for the architecture view and buildDependencyNodes for the dependency graph.

When the repo loads, useRepository.ts calls buildOverviewGraph right after the tree response comes back and pushes the result straight to the graph:

const overview = buildOverviewGraph(data.tree);
setVisualization(overview.nodes, overview.edges, "architecture");
Enter fullscreen mode Exit fullscreen mode

buildOverviewGraph never fetches any files. It just walks the tree structure and builds a folder map: root node at the top, top-level directories as children, one level of sub-folders below that:

export function buildOverviewGraph(tree: TreeNode) {
  const rootId = `node-${nodeId++}`;
  nodes.push({ id: rootId, type: "module", label: tree.path || "root" });

  const topDirs = (tree.children || []).filter((c) => c.type === "directory");

  for (const dir of topDirs) {
    const fileCount = flattenTree(dir).length;
    nodes.push({ id, label: `${dir.name} (${fileCount})`, type: categorizeDirType(dir.path) });
    edges.push({ source: rootId, target: id, type: "flow" });
  }
}
Enter fullscreen mode Exit fullscreen mode

The edges here mean nothing beyond "this folder is inside that folder."

edges

Once you ask a question, useCopilotActions.ts fetches the actual file content and calls buildDependencyNodes instead:

const graph = buildDependencyNodes(fileData);
setVisualization(graph.nodes, graph.edges, "dependency");
Enter fullscreen mode Exit fullscreen mode

buildDependencyNodes creates one node per file and one edge per real import statement:

export function buildDependencyNodes(files: { path: string; imports: string[] }[]) {
  const nodes = files.map((file) => ({
    id: file.path,
    type: "file",
    label: file.path.split("/").pop() || file.path,
    metadata: { fullPath: file.path },
  }));

  for (const file of files) {
    for (const imp of file.imports) {
      const resolved = resolveImportPath(imp, file.path, filePathSet);
      if (resolved) {
        edges.push({ source: file.path, target: resolved, type: "import" });
      }
    }
  }

  return { nodes, edges };
}
Enter fullscreen mode Exit fullscreen mode

Same setVisualization call, different data. React Flow re-renders and the graph morphs from a folder map into a real dependency graph focused on exactly the files relevant to your question.

 

3. The CopilotKit runtime

The /api/copilotkit route is where LLM requests actually land. The API key and provider config are stored in an httpOnly cookie, meaning they live on the server and never get sent to the browser.

The route reads that config, creates an OpenAI-compatible client, and hands the request to the CopilotKit runtime:

export const POST = async (req: NextRequest) => {
  const { baseURL, apiKey, model } = await getLLMConfig();

  const openai = new OpenAI({ baseURL, apiKey });
  const serviceAdapter = new OpenAIAdapter({ openai, model });
  const runtime = new CopilotRuntime();

  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};
Enter fullscreen mode Exit fullscreen mode

The defaults point to Ollama on localhost:11434/v1 with qwen2.5.

Because the OpenAI SDK accepts a custom baseURL, swapping to OpenAI, Groq or any other provider is just a config change with no code changes needed.

settings modal

settings modal

 

4. Feeding the LLM context

Before the LLM can answer anything useful, it needs to know what repo is loaded and what files exist. That is the job of the useCopilotContext.ts hook.

It calls useAgentContext, a CopilotKit hook that attaches structured data to every message you send. You can call it multiple times to attach different pieces of context.

Here it is called twice: once for the file list and once for the system instructions that tell the LLM how to behave:

useAgentContext({
  description: "File paths in the repository (max 500), one per line",
  value: fileList,  // flattened from the TreeNode structure
});

useAgentContext({
  description: "System instructions",
  value: `You are a Codebase Navigator assistant. You MUST use tool calls to answer questions.
CRITICAL RULES:
1. For ANY question about the repository call the "analyzeRepository" tool.
2. To show a file, call "fetchFileContent" with the exact file path.
3. NEVER respond with only text. ALWAYS call a tool first.
4. Use ONLY file paths from the file list above.`
});
Enter fullscreen mode Exit fullscreen mode

The file list is capped at 500 paths to stay within token limits.

Because this hook re-runs every time the Zustand store changes, the LLM always sees the current repo, selected file and analysis state rather than a stale snapshot from when the page loaded.

Note: If you are running a local model with a large context window, you can raise this limit in useCopilotContext.ts.

 

5. The four frontend tools

This is the core of how the app works. Instead of just replying with text, the LLM can call tools. Each tool has a name, a set of parameters it accepts and a handler, which is just a function that runs when the LLM calls it.

CopilotKit lets you register these tools directly in the browser using the useFrontendTool hook, which is defined in useCopilotActions.ts.

When a tool's handler runs, it updates Zustand state directly, which is why all four panels, the graph, code viewer, analysis panel, and chat, react at the same time without any extra wiring.

analyzeRepository is the main tool the LLM calls for almost every question. Here is what it does step by step:

useFrontendTool({
  name: "analyzeRepository",
  parameters: z.object({
    query: z.string(),
    explanation: z.string(),
  }),
  handler: async ({ query, explanation }) => {
    // 1. Find relevant files using keyword matching
    const matchedPaths = findFilesByQuery(repo.tree, query);

    // 2. Cap at 15 files to keep things fast
    const capped = matchedPaths.slice(0, 15);

    // 3. Fetch each file content (cached)
    const fileData = await Promise.all(
      capped.map(async (p) => ({
        path: p,
        imports: extractImports(await fetchFile(owner, repo, p, branch)),
      }))
    );

    // 4. Build real dependency graph from actual import statements
    const graph = buildDependencyNodes(fileData);

    // 5. Categorize each node by file type
    graph.nodes.forEach(node => {
      node.type = categorizeFileType(node.metadata.fullPath);
    });

    // 6. Push to Zustand - all four panels react
    setAnalysisResult({ explanation, relevantFiles, flowDiagram: graph });
    setVisualization(graph.nodes, graph.edges, "dependency");
  },
});
Enter fullscreen mode Exit fullscreen mode

fetchFileContent opens a specific file in the code viewer. The LLM calls this when you ask it to show you a file, it just fetches the content and calls setCodeViewer:

useFr

Visit Website