An AI-powered code repository analysis and documentation platform that helps developers understand, navigate, and onboard to codebases quickly using Claude AI.
- Repository Indexing: Automatically index GitHub repositories and extract file structure
- AI-Powered Code Analysis: Use Claude AI to analyze code files and generate summaries
- Intelligent Q&A: Ask questions about your codebase and get context-aware answers
- Onboarding Guides: Generate structured onboarding guides for new developers
- File Management: Track file changes, commit history, and code evolution
- GitHub Integration: Seamless integration with GitHub repositories
- RESTful API: Comprehensive API for programmatic access
StackMap Server is built with a modern tech stack:
- Backend: Node.js with Express.js
- Database: PostgreSQL with Prisma ORM
- AI Integration: Claude AI (Anthropic) for code analysis
- Authentication: JWT-based authentication with GitHub OAuth
- API Documentation: Swagger/OpenAPI integration
- File Storage: Supabase for file content storage
- Node.js (v18 or higher)
- PostgreSQL database
- GitHub account with repository access
- Claude AI API key
- Supabase project
git clone https://github.com/jackson951/Stackmap-Server.git
cd stackmap-servernpm installCreate a .env file in the root directory:
# Database
DATABASE_URL="postgresql://username:password@localhost:5432/stackmap?schema=public"
# Server
PORT=5000
FRONTEND_URL="https://stackmap-8ipx.vercel.app"
# Authentication
JWT_SECRET="your-super-secret-jwt-key"
# GitHub Integration
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"
# AI Services
ANTHROPIC_API_KEY="your-claude-api-key"
# Supabase
SUPABASE_URL="your-supabase-url"
SUPABASE_ANON_KEY="your-supabase-anon-key"
SUPABASE_SERVICE_KEY="your-supabase-service-key"# Generate Prisma client
npm run db:generate
# Push schema to database
npm run db:push
# Or create and run migrations
npm run db:migrate# Development mode
npm run dev
# Production build
npm run build
npm startThe API is documented using Swagger/OpenAPI and can be accessed at:
http://localhost:5000/api/docs
All API endpoints (except health check) require authentication via JWT token in the Authorization header:
Authorization: Bearer <your-jwt-token>
POST /api/auth/login- GitHub OAuth loginPOST /api/auth/logout- Logout and invalidate token
GET /api/repos- List user repositoriesPOST /api/repos- Add a new repositoryDELETE /api/repos/:repoId- Remove a repository
POST /api/repos/:repoId/index- Index repository filesGET /api/repos/:repoId/files- List indexed files
POST /api/repos/:repoId/query- Ask questions about the codebaseGET /api/repos/:repoId/queries- List previous queriesGET /api/repos/:repoId/guide- Generate onboarding guide
curl -X POST http://localhost:5000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"code": "github-auth-code"}'curl -X POST http://localhost:5000/api/repos \
-H "Authorization: Bearer your-jwt-token" \
-H "Content-Type: application/json" \
-d '{"fullName": "owner/repository-name"}'curl -X POST http://localhost:5000/api/repos/repo-id/index \
-H "Authorization: Bearer your-jwt-token"curl -X POST http://localhost:5000/api/repos/repo-id/query \
-H "Authorization: Bearer your-jwt-token" \
-H "Content-Type: application/json" \
-d '{"question": "How does the authentication system work?"}'curl -X GET http://localhost:5000/api/repos/repo-id/guide \
-H "Authorization: Bearer your-jwt-token"The application uses the following main entities:
- GitHub authentication and user management
- Stores GitHub ID, username, email, and access tokens
- Repository metadata and indexing status
- Links to user and associated files
- Individual file information within repositories
- Includes file paths, summaries, commit counts, and content
- Stores user questions and AI-generated answers
- Tracks referenced files for each query
- Automatically generates concise summaries for important files
- Focuses on key files like README, package.json, and main entry points
- Uses Claude AI for intelligent analysis
- Context-aware answers based on repository structure
- Cites specific files when providing answers
- Maintains conversation history for better context
- Structured Markdown guides for new developers
- Includes project overview, key files, architecture summary
- Provides starting points and known patterns
- JWT-based authentication with secure token generation
- GitHub OAuth for secure user authentication
- Input validation and sanitization
- Rate limiting on API endpoints
- Secure environment variable management
# Build the image
docker build -t stackmap-server .
# Run with environment variables
docker run -p 5000:5000 \
-e DATABASE_URL="your-database-url" \
-e JWT_SECRET="your-secret" \
stackmap-server- Create a new Heroku app
- Add PostgreSQL addon
- Set environment variables
- Deploy from GitHub
- Connect to GitHub repository
- Set environment variables in project settings
- Configure build command:
npm run build - Set output directory:
dist
# Run tests (if available)
npm test
# Run linting
npm run lint
# Check TypeScript
npm run typecheck- 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
This project is licensed under the MIT License - see the LICENSE file for details.
- Claude AI for the powerful AI capabilities
- GitHub for the excellent API
- Prisma for the fantastic ORM
- Express.js for the robust web framework
For support, email support@stackmap.com or join our Slack channel.
- StackMap Frontend - The companion frontend application
- StackMap CLI - Command-line interface for StackMap
Built with ❤️ by the StackMap Team