Transform complex codebases into interactive, navigable dependency graphs
Note: This MVP is currently optimized for small to medium codebases (up to 50 files) due to hackathon time constraints. Full enterprise-scale features are planned for future releases.
CodeMap helps developers understand unfamiliar code faster by visualizing relationships between files, functions, and modules as interactive graphs. No more getting lost in sprawling codebases or spending hours tracing dependencies manually.
Developers spend 60% of their time just trying to understand code instead of writing it. This creates:
- Slow onboarding for new team members (3-6 months to full productivity)
- Risky changes due to hidden dependencies
- Wasted time navigating complex codebases
- Knowledge silos when experienced developers leave
Cost Impact: A typical 10-developer team loses $270,000 annually in productivity due to code comprehension overhead.
CodeMap automatically analyzes your codebase and creates an interactive dependency graph that shows:
- File relationships and module boundaries
- Function calls and data flow
- Import/export dependencies across the project
- Class inheritance and component hierarchies
✅ Multi-language Support - JavaScript, Python, Go, Java
✅ Interactive Visualization - Click, zoom, and explore dependencies
✅ Dual Input Methods - GitHub repositories or ZIP file upload
✅ Real-time Analysis - Fast parsing with tree-sitter technology
✅ Clean Architecture - Built for scale from day one
- Go - High-performance API with excellent concurrency
- Neo4j - Graph database optimized for relationship queries
- PostgreSQL - User data and project metadata
- Tree-sitter - Multi-language code parsing
- Next.js - React framework with built-in routing
- Cytoscape.js - Professional graph visualization
- Tailwind CSS - Modern, responsive UI design
- Local Development - Zero cloud costs during development
- AWS Ready - Complete deployment architecture planned
- Docker - Containerized for consistent environments
- Node.js 18+
- Go 1.21+
- PostgreSQL 14+
- Neo4j 5.0+
- Yarn (recommended for tree-sitter dependencies)
-
Clone the repository
git clone https://github.com/your-username/codemap.git cd codemap -
Setup Backend
cd backend go mod download cp .env.example .env # Configure your database connections in .env go run cmd/api/main.go
-
Setup Frontend
cd frontend yarn install yarn dev -
Setup Analyzer
cd analyser yarn install node main.js
PostgreSQL:
CREATE DATABASE codemap;
-- Run migrations from backend/migrations/Neo4j:
// Create constraints for better performance
CREATE CONSTRAINT FOR (f:File) REQUIRE f.id IS UNIQUE;
CREATE CONSTRAINT FOR (fn:Function) REQUIRE fn.id IS UNIQUE;Upload your codebase via GitHub URL or ZIP file. Our analyzer uses tree-sitter to parse multiple languages and extract:
- File structure and imports
- Function definitions and calls
- Class hierarchies and relationships
- Variable usage patterns
Relationships are stored in Neo4j as a graph database:
- Nodes: Files, functions, classes, variables
- Edges: Calls, imports, contains, extends
- Properties: Metadata like complexity, size, types
The frontend renders the graph using Cytoscape.js:
- Explore: Click nodes to see connections
- Filter: Show/hide different relationship types
- Navigate: Zoom and pan through large codebases
- Understand: Visual patterns reveal architecture
- Upload Interface - GitHub integration + ZIP upload
- Project Management - Multiple codebase organization
- Analysis Status - Real-time processing updates
- Interactive Nodes - Files, functions, classes color-coded
- Relationship Edges - Calls, imports, dependencies
- Control Panel - Filtering and layout options
- Details Panel - Node properties and metadata
┌─────────────────────────────────────────────────────────┐
│ Frontend (Next.js) │
│ Interactive Graph Visualization │
├─────────────────────────────────────────────────────────┤
│ Backend API (Go) │
│ Authentication • File Processing • Queries │
├─────────────────────────────────────────────────────────┤
│ PostgreSQL │ Neo4j │
│ User Data • Projects │ Code Graph • Relations │
├─────────────────────────────────────────────────────────┤
│ Code Analyzer (Node.js) │
│ Tree-sitter • Language Parsers │
└─────────────────────────────────────────────────────────┘
- File Analysis: Up to 1,000 files per project
- Languages: JavaScript, TypeScript, Python, Go, Java
- Visualization: Interactive dependency graphs
- Performance: Smooth rendering for typical projects
- Authentication: Secure user accounts and project isolation
- Scale: Optimized for small-medium codebases
- Deployment: Local development (AWS architecture ready)
- Features: Core functionality prioritized over advanced analytics
- Collaboration: Single-user projects (team features planned)
These limitations ensure reliable performance while we validate the core concept and gather user feedback.
- Smart Clustering - Automatic component grouping
- Progressive Loading - Handle larger codebases efficiently
- Advanced Filtering - Module-level and complexity-based views
- AWS Deployment - Production cloud infrastructure
- Multi-tenant Architecture - Team workspaces
- Collaboration Tools - Shared projects and annotations
- Integration APIs - Connect with development workflows
- Advanced Analytics - Code quality and complexity metrics
- Large Repository Support - 50K+ files with AI optimization
- Custom Integrations - CI/CD pipeline integration
- Advanced Security - Enterprise compliance features
- Global Deployment - Multi-region performance
CodeMap was developed using Kiro as a strategic thinking partner, not just a coding assistant. Our approach:
- Problem Validation - Systematic analysis of developer pain points
- Solution Design - Collaborative exploration of alternatives
- Technology Decisions - Evidence-based tool selection with trade-off analysis
- Architecture Planning - Scalable design from day one
- Strategic Documentation - Complete planning artifacts for transparency
This strategic partnership with Kiro enabled us to build a production-ready foundation rather than just a hackathon demo.
# Backend tests
cd backend && go run ./cmd/api
# Frontend tests
cd frontend && npm run dev
We welcome contributions! Please see our contributing guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the installation steps above
- Ensure all tests pass before submitting
- Add tests for new features
- Update documentation as needed
This project is licensed under the MIT License - see the LICENSE file for details.
- Kiro AI - Strategic thinking partner throughout development
- Tree-sitter - Excellent multi-language parsing capabilities
- Neo4j - Powerful graph database for relationship modeling
- Cytoscape.js - Professional graph visualization library
- Hackathon Community - Inspiration and feedback
- GitHub Issues - Bug reports and feature requests
- Documentation - Complete planning docs in
/kirodirectory - Demo - Live demonstration available in project video
Built with strategic thinking. Powered by Kiro. Designed for developers.
Transform your codebase understanding from hours to minutes.