- ✨ Introduction
- ⚙️ Tech Stack
- 🔋 Features
- 🤸 Quick Start
- 🔗 Assets
- 🚀 More
This repository contains the code corresponding to an in-depth tutorial available on our YouTube channel, JavaScript Mastery.
If you prefer visual learning, this is the perfect resource for you. Follow our tutorial to learn how to build projects like these step-by-step in a beginner-friendly manner!
Cartograph is a developer tool that turns any public TypeScript or JavaScript repository into an interactive dependency map. Modern engineering teams frequently ship AI-generated code without fully reading every underlying file, creating complex architectural webs with hidden imports and coupled modules. Cartograph solves this by parsing raw source code into navigable nodes and edges, allowing developers to immediately visualize dependency chains, evaluate blast radii before making edits, and ask AI models for context-aware explanations grounded entirely in true AST parsing.
Built around a strict core principle, Cartograph guarantees that every node and edge on the canvas comes directly from real code analysis rather than AI predictions. By keeping graph arithmetic pure and standalone, the AI agent is only permitted to explain and summarize verified structure. Packed with multi-tenant organization support via Clerk, row-level security on Supabase, and full observability tracing through LangSmith, Cartograph provides production-grade infrastructure for software teams navigating large codebases.
If you're getting started and need assistance or face any bugs, join our active Discord community with over 50k+ members. It's a place where people help each other out.
-
Next.js 16 is a full-stack React framework that powers Cartograph using the App Router, Server Actions, and dynamic server-rendering capabilities for seamless frontend-backend integration.
-
TypeScript 5 is a strongly typed superset of JavaScript that ensures strict type safety across the entire application and parser pipeline.
-
ts-morph is a wrapper around the TypeScript Compiler API that parses source code files, imports, re-exports, and dynamic references into deterministic AST graph structures.
-
React Flow (@xyflow/react) is an interactive canvas library used alongside dagre for laying out, rendering, and navigating complex codebase dependency graphs.
-
Clerk provides identity management and multi-tenant organization authorization, issuing tokens that govern user access throughout the platform.
-
Supabase supplies the Postgres database layer with strict Row-Level Security (RLS) policies enforced directly via JWT claims.
-
OpenAI SDK drives the AI explanation and agentic inspection capabilities, providing answers grounded strictly in parsed code structures.
-
LangSmith is an observability platform that traces every LLM call, records dataset runs, and evaluates model responses against exact ground-truth code metrics.
-
Tailwind CSS v4 is a utility-first CSS framework that powers Cartograph's dense, high-information developer interface.
-
CodeRabbit is an AI code reviewer that automatically analyzes PRs to enforce architectural rules and codebase consistency.
👉 AST Codebase Parsing: Converts public GitHub repositories into complete node-and-edge graph maps by parsing imports, re-exports, dynamic imports, and require() calls without relying on AI predictions.
👉 Interactive Canvas Mapping: Zoom, expand folders into individual files, select modules, and view connected incoming and outgoing dependencies rendered via React Flow.
👉 Blast Radius Calculation: Instant arithmetic over the graph structure to reveal exactly which files and downstream modules break if a specific file is changed.
👉 Grounded Module Explanations: Contextual summaries generated for any file using only its real AST connections, with every mentioned filename hyperlinked directly on the map.
👉 Agentic Repository Chat: Interactive agent panel that walks verified graph paths step-by-step to answer architectural questions without inventing non-existent files or relationships.
👉 Multi-Tenant Organizations: Shared codebase analyses linked to Clerk organizations so team members collaborate from a single unified map.
👉 Row-Level Postgres Security: Automatic data isolation across teams using Supabase Postgres policies evaluated directly against Clerk JWT claims.
👉 LangSmith Trace & Evaluation: Full tracing of every AI execution call, cache hit verification, and benchmark evaluation against true repository file lists.
And many more, including code architecture and reusability.
Follow these steps to set up the project locally on your machine.
Prerequisites
Make sure you have the following installed on your machine:
Cloning the Repository
git clone https://github.com/adrianhajdin/cartograph.git
cd cartographInstallation
Install the project dependencies using pnpm:
pnpm installSet Up Environment Variables
Create a new file named .env.local in the root of your project and add the following content:
# CLERK
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
# SUPABASE
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
SUPABASE_SECRET_KEY=
# LANGSMITH
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=
LANGSMITH_PROJECT=cartograph
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
# OPENAI
OPENAI_API_KEY=
# Agent Service (deep-agent/, `pnpm dev` there).
AGENT_URL=http://localhost:2024Replace the placeholder values with your real credentials. You can get these by signing up at: Clerk, Supabase, OpenAI, and LangSmith.
Running the Project
pnpm devOpen http://localhost:3000 in your browser to view the project.
Assets and snippets used in the project can be found in the video kit.
Advance your skills with our Pro Course
Enjoyed creating this project? Dive deeper into our PRO courses for a richer learning adventure. They're packed with detailed explanations, cool features, and exercises to boost your skills. Give it a go!
