🗺️ Code Atlas (Local Desktop Edition)

Code Atlas is a locally-hosted, privacy-first, AI-powered codebase architecture visualizer. It instantly parses local source directories into an interactive 3D/2D architecture map, automatically detects cross-language API connections, and lets you chat with local AI models (via Ollama) or cloud models (via Google Gemini) that understand the precise structural context of your codebase—running 100% offline on your own machine.

✨ Key Features

• 🕸️ Interactive Architecture Map: Built with D3.js, visualize files, packages, classes, and functions as a physics-simulated force-directed graph. Features pre-warmed simulation physics, subtle ghost call lines to eliminate visual clutter, and smart level-of-detail (LOD) label culling.
• 📂 Native OS Folder Picker: Select any directory on your computer using your operating system's native folder chooser dialog (Windows Explorer, macOS Finder, or Linux file picker) with one click on "📂 Browse...".
• 🔌 Cross-Language API Linkage: Automatically connects Frontend fetch() / axios calls (JS/TS/React) directly to Backend endpoints (Python FastAPI/Flask) with glowing cross-service dependency lines.
• 🦙/☁️ Dual Local & Cloud AI Assistant:
  • 100% Offline AI: Chat with local models (Llama 3.2, Qwen 2.5 Coder, DeepSeek R1, Phi-3) via native Ollama auto-detection.
  • Cloud Fallback: Optional support for Google Gemini (2.5 Flash & Pro) when online.
  • Context-Aware: The AI is fed the active node's source code, upstream callers, and downstream callees.
• 🔍 100% Offline Semantic Search: Search your codebase using plain English ("Where is the token expiration handled?") powered by a local, standalone Sentence-Transformers model (all-MiniLM-L6-v2) and a local FAISS vector database with sub-10ms response times.
• 🧭 Interactive Dependency Jump Navigator: Clickable ⬅ Called by [caller] and Calls [callee] ➔ jump pills in the Code Panel to leap across relationships and follow execution flow on the map.
• 🐙 Live Local Git Authorship: Instantly inspect the Original Author and Recent Heavy Modifier for any function or class, read directly from your local repository's .git commit history.
• ⚠️ Cyclic Dependency Detection: Automatically detects circular imports (A ➔ B ➔ A) with a pulsing UI alert to help you refactor tight coupling.
• 📋 Dynamic Code Inspector: Slide-out code panel with auto-detected syntax highlighting (Python, TypeScript, JavaScript, JSX, JSON) and one-click copy.
• 🎯 Responsive Navigation Deck: Floating [+], [-], [🎯 Center] zoom controls and minimap that automatically slide out of the way when the Code Panel is opened.

🛠️ Tech Stack

Backend:

• Python 3.11+
• FastAPI (Async API, WebSocket progress streaming)
• Tree-sitter (Fault-tolerant AST parsing for Python, JS, TS, JSX, TSX)
• NetworkX (Graph modeling and Cycle detection)
• SQLite (Relational metadata storage with multi-row batching)
• FAISS & Sentence-Transformers (100% local, offline vector embeddings)
• Ollama & Google GenAI SDK (Dual local/cloud LLM inference engines)

Frontend:

• React 18 (Vite, React Router)
• D3.js (Force-directed physics, minimap, dynamic zoom deck, collision physics)
• React-Markdown & SyntaxHighlighter (Code rendering with Prism vscDarkPlus)

🚀 Getting Started

Prerequisites

• Python 3.11 or higher (Python 3.11 or 3.12 recommended for pre-built FAISS/PyTorch wheels)
• Node.js v18 or higher
• Git
• (Optional, for offline AI) Ollama installed and running locally

1. Clone the Repository

git clone https://github.com/yourusername/code-atlas.git
cd code-atlas

2. Setup the Backend

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the API server
python api.py

3. Setup the Frontend

Open a new terminal window:

cd frontend
npm install
npm run dev

4. Open the App

Navigate to http://localhost:5173/ in your browser.

---

🦙 Setting Up Offline AI (Ollama)

To run the AI software architect completely offline without sending code to the cloud:

1. Download and install Ollama.
2. Pull your preferred coding model in your terminal:

   ollama run qwen2.5-coder
   # or
   ollama run llama3.2

3. Code Atlas will automatically detect your installed Ollama models on startup (http://localhost:11434) and list them in the Code Panel's model dropdown.

(Optional: If you prefer cloud models, visit Settings in the app to enter a free Google Gemini API Key).

🎮 Usage

1. Parse a Local Codebase: Click Parse Local Codebase on the dashboard. Click "📂 Browse..." to select any project directory on your machine (or enter a local path).
2. Watch the Engine Work: Code Atlas will aggressively prune ignored directories (like node_modules, .venv, and dist), parse AST definitions via Tree-sitter, batch-commit to SQLite, build local FAISS embeddings, and link cross-language APIs.
3. Explore the Map:
   • Scroll to zoom, click and drag to pan.
   • Drag nodes to pin them to custom locations (layout state automatically saves).
   • Hover over any node to highlight its connected call lines while ghosting unrelated nodes.
   • Click empty canvas space to reset highlights and close side panels.
4. Inspect & Navigate: Click any node to slide out the Code Panel. View syntax-highlighted source code, check local Git blame stats, or click the ⬅ Called by and Calls ➔ jump pills to glide the camera to connected callers/callees.
5. Ask AI: Switch to the Ask AI tab to query your local Ollama or cloud Gemini model about that specific architectural block, downstream ripple effects, or potential bugs.
6. Semantic Search: Type queries like "database connection pool" or "user authentication middleware" in the sidebar to search your codebase semantically with sub-10ms response times.

🗺️ Roadmap (Coming Soon)

• Heuristic Type Inference (LSP-Lite): Improved tracking of class instantiations to resolve exact method calls across files without a full Language Server.
• GitHub Auto-Ingestion: Paste a GitHub URL to automatically clone (shallow), parse, and visualize a repository entirely from the UI.
• Expanded Language Support: Add tree-sitter-java, tree-sitter-go, and tree-sitter-rust.
• Live Watch Mode (watchdog): Real-time auto-reload of the architecture graph as you save file edits in your IDE without re-parsing from scratch.
• One-Command All-in-One CLI (code-atlas .): Single terminal command to parse a folder, boot the backend, and open your browser automatically.
• Export to SVG / Mermaid.js: One-click export of selected graph modules into Mermaid.js format for documentation and READMEs.
• Architecture Diff View: Inspect architecture and dependency changes between two Git branches or working trees.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

📄 License

This project is licensed under the MIT License.