Project Info

CodeInsight - Google Maps for Software Systems

Inspiration

Every engineer has experienced the dread of joining a new codebase. You clone a repository, open your editor, and stare at hundreds of files with no idea where to begin. The documentation is outdated, the architecture is implicit, and the only way to understand the system is to read every file one by one. We asked ourselves: what if you could navigate a codebase the way you navigate a city — with a map? Traditional AI coding assistants like Copilot understand your current file. They answer "what does this function do?" but not "how does authentication work across the entire application?" That gap — between local context and system understanding — is where most engineering time disappears. CodeInsight was born from this frustration. We wanted to build a tool that lets you zoom out and see the architecture, zoom in and see the symbols, and ask questions that span the entire codebase.

What it does

CodeInsight is a full-stack codebase intelligence platform that imports any repository, parses source code across 8 languages, builds architectural knowledge graphs, and provides AI-powered analysis — all grounded in real repository evidence. Core capabilities: Repository Import — GitHub URLs, local paths, and ZIP uploads Multi-language Parsing — Python, JavaScript, TypeScript, C, C++, Java, Go, and Rust via Tree-sitter with regex fallback Graph Engine — Dependency graph, call graph, and knowledge graph with Neo4j, NetworkX, and SQLite persistence Hybrid Retrieval — Semantic search + keyword matching + graph traversal for grounded answers Repository Q&A — Ask questions about your codebase and get evidence-cited answers with streaming responses Technical Debt Detection — Cyclomatic complexity, god objects, dead code, circular dependencies, architecture violations Bug Impact Prediction — Paste a stack trace, get affected modules, root cause analysis, and confidence scores Documentation Generation — README, architecture docs, Mermaid diagrams, and developer onboarding guides Code Review — PR review, architecture review, and security review engines Dark-first Dashboard — 23+ interactive panels with React Flow graph visualization

How we built it

CodeInsight is a monorepo with six modules: The processing pipeline: Key architectural decisions: Triple persistence — Neo4j (optional) → NetworkX (in-memory) → SQLite (primary). The app works with zero configuration. Hybrid retrieval — Combines semantic embeddings, keyword matching, and graph traversal for grounded answers instead of hallucinated responses. Tree-sitter + regex fallback — Native grammars when available, portable regex patterns when not. OpenAI + Ollama — Works with or without an API key. Local demos use Ollama for embeddings. Quality gate: make verify runs formatting, linting, mypy strict, 90%+ coverage-gated tests, Next.js production build, and Docker Compose validation.

Challenges we ran into

1. Python 3.14 Segfaults Python 3.14.6 segfaults in worker threads while scanning repositories on macOS. This was a showstopper for live demos. Fixed by pinning Docker images to Python 3.13 and defaulting to the safe regex parser for demos. 2. Vector Store Crash Inserting all embeddings in a single transaction caused SQLite to run out of memory on large repositories. Solved with batched inserts — chunking the embedding vector table into manageable batches. 3. Non-Atomic Graph Operations Replacing an entire graph in one transaction caused data corruption on concurrent access. Implemented batched inserts with WAL (Write-Ahead Logging) mode for concurrent reads during writes. 4. CORS Hardcoded to Localhost CORS was hardcoded to localhost:3000 during early development, breaking Docker deployments. Made CORS origins configurable via environment variables. 5. Parser Accuracy The safe regex parser initially missed multi-import statements, included comments in symbol extraction, and counted function declarations as calls. Required careful iteration on scope tracking, declaration separation, and import chain detection. 6. Graph Visualization at Scale Rendering hundreds of nodes in React Flow required lazy loading, virtualized rendering, and interactive zoom/pan controls to maintain 60 FPS performance.

Accomplishments we're proud of

177 tests with 90%+ coverage gate — Every PR must pass make verify before merge Zero-config local demo — Works without Neo4j, without an OpenAI key, just Python and Node.js Real answers grounded in code — Every Q&A response cites specific files, functions, and lines 8 languages parsed — Python, JavaScript, TypeScript, C, C++, Java, Go, Rust with one unified API 25+ backend services — From repository import to bug impact prediction to documentation generation 23+ frontend panels — Dark-themed dashboard with interactive graph visualization Production-ready architecture — Docker Compose, health checks, structured logging, CORS, error recovery Streaming Q&A — Users see answers as they generate, not after a long wait

What we learned

Graph structure is non-negotiable. Source code is not just text — it is a graph. Every import creates an edge. Every function call creates a relationship. Traditional grep-based search and file-tree navigation fundamentally cannot answer questions about system behavior. Hybrid retrieval beats pure vector search. Pure embedding search produces hallucinated answers. Pure keyword search misses semantic connections. Grounded answers require combining semantic, keyword, and graph signals. $$ \text{score}(q, d) = \alpha \cdot \text{semantic}(q, d) + \beta \cdot \text{keyword}(q, d) + \gamma \cdot \text{graph}(q, d) $$ Graceful degradation is a core principle. Neo4j → NetworkX → SQLite. Tree-sitter → regex. OpenAI → Ollama. Every dependency has a fallback so the app always works. Documentation is a feature, not an afterthought. Generating README, architecture docs, and onboarding guides from real repository evidence produces better documentation than manual writing.

What's next

Incremental indexing — Re-index only changed files instead of full repository scans Live repository monitoring — Watch for changes and update graphs in real-time CI/CD integration — GitHub Actions bot that comments on PRs with impact analysis Team collaboration — Shared repositories with conversation history Plugin marketplace — Community-contributed language parsers and analysis engines Cloud hosting — Managed version with persistent storage and team features Architecture decision records — Auto-generate ADRs from code changes Cross-repository analysis — Understand dependencies across multiple repositories in a monorepo or organization Built for the OpenAI Hackathon · Developer Tools Track Codex Session: 019f69f5-05dd-7bc2-9303-f1ba8c7486cf

CodeInsight

OpenAI Hackathon Submission — Developer Tools Track

CodeInsight is "Google Maps for Software Systems": a dark-first codebase intelligence app that imports repositories, parses source code, builds graph views, answers repository questions, predicts bug impact, reviews changes, and generates documentation from real repository evidence.

Live Demo: codeinsight-iota.vercel.app

Built with Codex

Codex Session ID: 019f69f5-05dd-7bc2-9303-f1ba8c7486cf

Codex with GPT-5.6 was the primary development accelerator for CodeInsight. Here's how it was used:

Architecture & Scaffolding

Codex designed the full monorepo structure (frontend/, backend/, parser/, graph/, shared/, workers/) and generated the initial scaffolding for all modules
Generated the FastAPI application factory, dependency injection container, and Pydantic schema layer from a high-level feature spec
Created the Docker Compose orchestration with 5 services, health checks, and persistent volumes

Core Intelligence Pipeline

Parser (parser/tree_sitter_parser.py): Codex implemented the Tree-sitter multi-language parser with safe regex fallback for 8 languages (Python, JS, TS, C, C++, Java, Go, Rust)
Graph Engine (graph/): Generated the knowledge graph, dependency graph, and call graph builders with Neo4j primary, NetworkX in-memory, and SQLite persistence layers
Embedding & Retrieval (backend/app/services/embedding.py, retrieval.py, vector_store.py): Built the hybrid retrieval system combining semantic search, keyword matching, and graph traversal

25+ Backend Services

Codex generated the implementation for every service module:

repository_import.py — GitHub, local path, and ZIP upload ingestion
repository_qa.py — grounded Q&A with streaming responses and conversation memory
technical_debt.py, bug_impact.py, risk_scoring.py — codebase analysis engines
security_review.py, pull_request_review.py, architecture_explanation.py
readme_generator.py, architecture_docs.py, mermaid_diagrams.py, developer_onboarding.py

Frontend (23+ Panels)

Codex built the dark-themed dashboard with React Flow graph visualization, TanStack Query data fetching, and Framer Motion animations
Generated all interactive panels: repository explorer, dependency graph, knowledge graph, bug impact, technical debt, security review, architecture docs, README generator, and more
Implemented the streaming Q&A interface and conversation history UI

Quality & DevOps

Codex set up the make verify release gate: formatting, linting, mypy strict, 90%+ coverage-gated tests, Next.js production build, Docker Compose validation
Generated 45+ pytest test files covering parser, graph, service, and API layers
Created the CI scripts, coverage enforcement, and Dockerfiles

Key Decisions Made with Codex

Neo4j + NetworkX + SQLite triple persistence: Codex evaluated tradeoffs and implemented graceful fallback (Neo4j → NetworkX → SQLite) for zero-config local demos
Hybrid retrieval over pure vector search: Codex recommended combining semantic embeddings with keyword matching and graph traversal for grounded answers
Tree-sitter + regex fallback: Codex designed the parser to use native Tree-sitter when available but fall back to regex patterns for portability
OpenAI + Ollama embedding support: Codex implemented provider abstraction so the app works with or without an OpenAI API key

What Works

Repository import from local paths, GitHub URLs, and zip uploads
Recursive repository scanning with language, file, directory, and extension metadata
Tree-sitter parsing for Python, JavaScript, TypeScript, C, C++, Java, Go, and Rust
Symbol extraction for functions, classes, methods, variables, imports, exports, inheritance, and interfaces
Dependency graph, call graph, knowledge graph, Neo4j integration, NetworkX fallback, and SQLite graph persistence
Repository chunking, OpenAI or Ollama embeddings, SQLite vector storage, and hybrid retrieval
Repository summaries, architecture explanations, grounded Q&A, streaming responses, and conversation memory
Repository explorer, search, dependency graph UI, knowledge graph UI, and interactive graph controls
Technical debt, complexity, circular dependency, dead code, architecture violation, bug impact, risk scoring, PR review, architecture review, and security review
README, architecture docs, Mermaid diagrams, and developer onboarding generation
Structured API errors, accessibility affordances, production logging, Docker Compose, and coverage-gated verification

Stack

Frontend: Next.js, React, TypeScript, Tailwind CSS, TanStack Query, React Flow, Framer Motion
Backend: FastAPI, Pydantic, SQLite, Tree-sitter, NetworkX, Neo4j driver, OpenAI-compatible embeddings
Worker: Python health service scaffold for background processing
Infrastructure: Docker Compose with frontend, backend, worker, Neo4j, Redis, and durable volumes

Quick Start

Install dependencies:

npm install
python3.13 -m venv .venv313
.venv313/bin/pip install -r requirements-dev.txt

Run the backend:

.venv313/bin/uvicorn backend.app.main:app --host 127.0.0.1 --port 8002

Run the dashboard:

npm run dev --workspace @codeinsight/frontend

For local demos, point the frontend at the backend:

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8002 npm run dev --workspace @codeinsight/frontend -- --port 3002

Open the dashboard at http://localhost:3002.

Run the full release verifier:

make verify

Docker

Validate the stack:

docker-compose config

Build runtime images:

make docker-build

Start the stack:

docker-compose up --build

Embeddings

OpenAI embeddings require CODEINSIGHT_OPENAI_API_KEY.

For local demos without an OpenAI key:

export CODEINSIGHT_EMBEDDING_PROVIDER=ollama
export CODEINSIGHT_OLLAMA_EMBEDDING_MODEL=nomic-embed-text

Then run Ollama locally before vector indexing.

Demo

Live App: codeinsight-iota.vercel.app

Use the official flow in DEMO.md. The recommended real demo repository is FastAPI because it is large enough to exercise parsing, graphs, search, documentation, Q&A, debt, and bug analysis without being too large for a short recording.

Release assets:

Documentation

Document	Description
ARCHITECTURE.md	System architecture, modules, and design principles
PRODUCT_SPEC.md	Product specification and requirements
CODING_STANDARDS.md	Code style, testing, and quality standards
CONTRIBUTING.md	How to contribute to the project
SECURITY.md	Security policy and vulnerability reporting
CHANGELOG.md	Version history and changes
DEMO.md	Demo script and recording guide
TASKS.md	Development roadmap and milestones
LICENSE	MIT License

Verification Status

The release gate is make verify, which runs formatting checks, linting, type checking, coverage-gated Python tests, the Next.js production build, and Docker Compose config validation.

Current quality target: Python coverage above 90%.

Note: avoid Python 3.14 for local backend demos on macOS. Python 3.14.6 can segfault in worker threads while scanning repositories. CodeInsight defaults to the crash-resistant safe parser for live demos. Set CODEINSIGHT_PARSER_PROVIDER=tree_sitter only when the native Tree-sitter bindings are stable on your machine.

Hackathon Submission

Field	Value
Track	Developer Tools
Project	CodeInsight — Google Maps for Software Systems
Live Demo	codeinsight-iota.vercel.app
Codex Session ID	`019f69f5-05dd-7bc2-9303-f1ba8c7486cf`
Demo Video	YouTube
Repository	GitHub

What We Built

A full-stack codebase intelligence platform that imports any repository, parses source code across 8 languages, builds architectural knowledge graphs, and provides AI-powered Q&A, bug impact analysis, technical debt detection, security reviews, and documentation generation — all grounded in real repository evidence.

How Codex Was Used

Codex with GPT-5.6 was used to build the entire application — from architecture design and scaffolding through implementing 25+ backend services, 23+ frontend panels, a multi-language parser, graph engines, hybrid retrieval, and production DevOps. See the Built with Codex section above for the full breakdown.

Analysis

Compare with all teams

View

Metric

Hemang Varshney
59

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

CSSIn code
FastAPIIn code
Next.jsIn code
OpenAIIn code
PythonIn code
ReactIn code
Tailwind CSSIn code
TypeScriptIn code
DockerClaimed
VercelClaimed

8 of 10 appear in the indexed code. 2 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.

AI coding agents

No AI coding agent signals were found in this repository.

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

1.0 MB

Source files

207

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.