AI-Powered Codebase Intelligence Platform
Connect your GitHub repositories and ask natural language questions about your codebase. StackMap uses AI to analyze your code structure, dependencies, and patterns to provide intelligent insights and answers.
- Intelligent Code Understanding: AI analyzes your entire codebase to understand architecture, dependencies, and patterns
- Natural Language Queries: Ask questions about your code in plain English and get precise answers with file references
- Context-Aware Responses: AI provides answers with relevant code snippets and context
- One-Click Documentation: Generate comprehensive documentation for new team members
- Architecture Guides: Automatically create architecture documentation and code explanations
- Markdown Export: Export documentation in Markdown format for easy sharing
- Repository Mapping: Visualize your codebase structure and dependencies
- File Analysis: Detailed analysis of individual files with insights and recommendations
- Churn Heatmaps: Visualize code changes and activity patterns
- GitHub Integration: Seamless integration with GitHub repositories
- User Management: Team-based access and repository management
- Query History: Track and review previous AI queries and responses
- Frontend: Next.js 16.2.0 with React 19.2.4
- Styling: Tailwind CSS with custom gradients and animations
- State Management: React Context API
- Database: Supabase (PostgreSQL)
- Authentication: Supabase Auth with GitHub OAuth
- AI Integration: Custom AI query system
- TypeScript: Full TypeScript support
@radix-ui/react-dropdown-menu- Accessible UI components@supabase/ssr&@supabase/supabase-js- Supabase integrationclsx- Conditional CSS class utilitydate-fns- Date manipulationlucide-react- Icon librarytailwind-merge- Tailwind class merging
@tailwindcss/postcss- PostCSS integration@types/node&@types/react- TypeScript definitionseslint- Code lintingsupabase- Supabase CLItypescript- TypeScript compiler
- Node.js 18+
- npm or yarn
- GitHub account
- Supabase project (for database and auth)
-
Clone the repository:
git clone https://github.com/jackson951/stackmap.git cd stackmap -
Install dependencies:
npm install # or yarn install -
Environment Setup: Create a
.env.localfile in the root directory:NEXT_PUBLIC_SUPABASE_URL=your_supabase_url NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key # GitHub OAuth GITHUB_CLIENT_ID=your_github_client_id GITHUB_CLIENT_SECRET=your_github_client_secret # Optional: AI API keys OPENAI_API_KEY=your_openai_api_key
-
Database Setup:
npx supabase login npx supabase init npx supabase start
-
Run the development server:
npm run dev # or yarn dev -
Open your browser: Visit http://localhost:3000 to see the application.
- Sign in with GitHub: Click "Get Started" and authenticate with your GitHub account
- Connect Repositories: Select repositories you want to analyze
- Ask Questions: Use natural language to query your codebase
- Generate Documentation: Create onboarding guides for your team
The main dashboard provides an overview of your connected repositories, indexing status, and quick access to AI queries.
- File Tree: Navigate your repository structure
- Code Analysis: Get AI insights about specific files
- Churn Heatmaps: Visualize code change patterns
Ask questions like:
- "Where does authentication happen?"
- "How do I add a new feature?"
- "What are the main dependencies?"
- "Explain this function's purpose"
Generate comprehensive documentation:
- Architecture overview
- Code explanations
- Setup instructions
- Best practices
src/
├── app/ # Next.js App Router pages
│ ├── dashboard/ # Main dashboard
│ ├── repo/[repoId]/ # Repository-specific pages
│ │ ├── files/ # File browser
│ │ ├── guide/ # Onboarding guide
│ │ └── query/ # AI query interface
│ └── auth/ # Authentication pages
├── components/ # Reusable UI components
│ ├── files/ # File-related components
│ ├── query/ # AI query components
│ ├── repos/ # Repository management
│ └── ui/ # Base UI components
├── contexts/ # React context providers
├── hooks/ # Custom React hooks
├── lib/ # Utility functions and API clients
├── types/ # TypeScript type definitions
└── docs/ # Documentation and API specs
| Variable | Description | Required |
|---|---|---|
NEXT_PUBLIC_SUPABASE_URL |
Supabase project URL | ✅ |
NEXT_PUBLIC_SUPABASE_ANON_KEY |
Supabase anonymous key | ✅ |
SUPABASE_SERVICE_ROLE_KEY |
Supabase service role key | ✅ |
GITHUB_CLIENT_ID |
GitHub OAuth client ID | ✅ |
GITHUB_CLIENT_SECRET |
GitHub OAuth client secret | ✅ |
OPENAI_API_KEY |
OpenAI API key (optional) | ❌ |
The application uses Supabase PostgreSQL with the following main tables:
users- User information and GitHub integrationrepositories- Connected GitHub repositoriesfiles- File metadata and analysis resultsqueries- AI query history and responsesonboarding_guides- Generated documentation
- Push to GitHub
- Connect to Vercel
- Set environment variables in Vercel dashboard
- Deploy!
docker build -t stackmap .
docker run -p 3000:3000 stackmap- Build the application:
npm run build - Start the server:
npm start - Configure your reverse proxy (nginx, etc.)
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Next.js - For the excellent React framework
- Supabase - For the amazing backend platform
- Tailwind CSS - For beautiful, utility-first styling
- GitHub - For the API that makes this all possible
- OpenAI - For the AI capabilities that power our insights
If you have any questions or need help:
- 🐛 Open an Issue
- 💬 Join our Discord
- 📧 Email us at support@stackmap.ai
Built with ❤️ by the StackMap Team
