NavGator
Architecture connection tracker that maps your stack before you change it.
The Problem
Claude Code makes changes without full context of how components connect. You ask it to modify a database schema and it updates the migration file, but misses the 12 API routes that query that table, the 3 background jobs that write to it, and the analytics dashboard that aggregates it. The change breaks in production because the AI didn’t know the full dependency graph.
Why It Matters
Modern applications are connection graphs, not isolated modules. A Stripe integration touches payment forms, webhook handlers, subscription management, invoice generation, and customer portals. Changing the Stripe API version in one place requires coordinated updates across all connection points. Without a map, you’re navigating architecture blindfolded.
What I Built
NavGator scans your codebase in two phases. Phase 1 (fast) detects packages and frameworks from package.json, requirements.txt, and lock files. This lightweight scan runs in under 1 second and identifies your stack: Next.js, PostgreSQL, Stripe, Redis, Tailwind. Phase 2 (deep) scans service calls, database operations, and AI prompts using static analysis and pattern matching. This slower scan (5-30s depending on project size) builds the full connection graph.
Tiered memory keeps context manageable. SUMMARY.md (40-150 lines) provides hot context with service inventory, database schema overview, and critical connection points. This is what Claude reads first. index.json, graph.json, and file_map.json contain structured data for programmatic access. components/ and connections/ store detailed per-file analysis only loaded on demand.
Impact Analysis
The impact command answers “what breaks if I change X?”. Running navgator impact "Stripe" shows all files that import stripe, call Stripe APIs, handle Stripe webhooks, or reference Stripe types. Results include file:line references so you can verify each connection. This pre-change analysis prevents breaking changes from landing.
For example, migrating from Stripe SDK v11 to v12 might show 47 affected files: 18 API routes, 12 React components, 8 webhook handlers, 6 utility functions, 2 background jobs, 1 CLI script. You now have a checklist of every place requiring updates.
AI Prompt Tracking
The tool detects AI prompts embedded in code: OpenAI chat completions, Claude messages, LangChain chains, and custom prompt templates. It categorizes them by type (chat, summarization, extraction, classification, generation) and tracks variables injected into prompts. A summarization prompt might reference user input, article text, and output format variables.
This helps when prompts start failing. You can see that 8 different files use the same summarization prompt template, so improving it once fixes all callsites. Or you discover that two teams independently wrote similar extraction prompts and should consolidate.
File Change Detection
SHA-256 hashing enables incremental rescans. After initial scan, NavGator stores file hashes. On subsequent runs, only modified files trigger re-analysis. A 500-file project might rescan in 2 seconds instead of 20 seconds when only 10 files changed. Deleted files automatically remove their connections from the graph.
Visualization
Diagram generation creates architecture visualizations from connection data, grouping components by layer with color-coded categories. Service-level diagrams show API → Database → Cache flows with labeled connection types (API, query, cache). File-level diagrams show import relationships. The output makes architecture visible without external tools.
AI Flow Visualization
The AI Flow view maps how prompts and model calls connect across your codebase. The pipeline flows from User Input through three color-coded layers: Input/Routing (cyan), Processing/Analysis (green), and Output/Summary (orange), ending at Response. Each layer is a bordered container holding component pills with connection counts. This makes prompt sprawl visible — you can see at a glance which layers have the most AI integration and where prompt logic concentrates.
Below the flow diagram, the Prompts section lists every file containing AI prompts with prompt counts and file paths. A file like progressive-pyramid-service with 10 prompts stands out immediately as a consolidation candidate.
Advanced Static Analysis
Optional ts-morph integration provides AST-based scanning for TypeScript projects. This catches connections that pattern matching misses: dynamic imports, computed property access, reflection-based calls. Accuracy improves 50% at the cost of 3x slower scanning. Projects with heavy metaprogramming benefit most.
The AST scanner identifies function signatures, return types, and parameter types. It knows that getUserOrders(userId: string): Promise<Order[]> reads from the orders table and depends on the User type. Pattern matching only sees string literals like “SELECT * FROM orders”, missing the semantic meaning.
Storage and Performance
Memory files use JSON for structured data, markdown for human-readable context. SUMMARY.md includes timestamps and cache invalidation logic. If packages.json modification time is newer than SUMMARY.md, the cache invalidates and Phase 1 re-runs. This keeps memory fresh without manual intervention.
The file_map.json uses relative paths as keys to avoid breaking when projects move. Absolute paths would invalidate the entire cache on directory rename. Relative paths stay valid, preserving hours of analysis work.
Technical Decisions
Two-phase scanning separates fast bootstrap from deep analysis. Phase 1 uses only file system operations (read package.json, parse imports). No execution, no compilation. This works on broken codebases that won’t build. Phase 2 runs static analysis but still avoids execution. A runtime crash in your app doesn’t break NavGator scanning.
I implemented parallel file scanning with worker threads (default 4 workers). Each worker processes a subset of files, building partial graphs that merge at the end. This scales to codebases with 10,000+ files without memory issues.
The connection graph uses adjacency list representation (Map<string, Set<string>>) for memory efficiency. A project with 1,000 files and 5,000 connections consumes ~2MB. Alternative matrix representation would use 1,000 × 1,000 = 1,000,000 entries, wasting memory on sparse graphs.
Commander provides the CLI with subcommands: scan, impact, visualize, diff (compare two scans), and export (JSON/CSV/Mermaid). The diff command is particularly useful during refactoring. Run scan before changes, make changes, run scan again, then diff to see what connection patterns changed.