GitVerse

Turn any GitHub repo into an interactive map of its architecture, modules, and risks.

GitVerse is built for the moment you open a new codebase and ask: “Where do I start?”

Pitch

Problem

Open-source and internal repos are hard to contribute to because context is scattered across folders, commits, and tribal knowledge.

Why now

Repos are larger, teams are more distributed, and AI can finally summarize + connect the dots fast enough to change the contributor experience.

Solution

Paste a repo → GitVerse builds a visual map + AI onboarding so contributors can understand architecture and pick a starting point in minutes.

Impact

• Faster onboarding for new contributors
• Clearer ownership and hotspots
• Better PR quality (less back-and-forth)

“Repo-to-Map in 10 seconds” (MVP flow)

1. Paste a GitHub URL
2. GitVerse generates:
   • Architecture / module map (visual)
   • Modules + dependencies
   • Top risks / hotspots
   • 3 concrete improvement suggestions
3. Click a module → ask AI: “What does this do?” “Where should I start contributing?”

What you can do today

• Visualize repository structure and key paths
• Explore commits/branches and contributor activity
• Ask AI questions about files, folders, and architecture
• Generate analysis jobs and track progress

Quickstart (local dev)

npm install
cp .env.example .env.local
cp .env.local .env
npm run prisma:generate
npm run prisma:migrate
npm run dev

Open http://localhost:3000

Contribution-first onboarding (the hackathon angle)

GitVerse is designed to make contributing to unfamiliar repos easier:

• “How do I run this project?”
• “Where is auth?”
• “Explain this folder like I’m new.”
• “Give me 3 beginner-friendly issues.”

That’s the MVP: turn repo complexity into a contributor roadmap.

Tech stack

• Next.js 14 (App Router), React, TypeScript, Tailwind
• Prisma + Postgres (Neon)
• Gemini for AI analysis
• D3/Recharts for visualizations
• Auth: NextAuth (Google) + credentials

🏗️ Project Structure

gitverse-nextjs/
├── app/
│   ├── api/                 # API routes
│   │   ├── auth/            # Authentication endpoints
│   │   ├── repositories/    # Repository management
│   │   ├── ai/              # AI-powered features
│   │   ├── users/           # User management
│   │   └── integrations/    # Git platform integrations
│   ├── (pages)/             # Page routes
│   ├── layout.tsx           # Root layout
│   └── page.tsx             # Home page
├── src/
│   ├── components/          # React components
│   │   ├── ai/              # AI components
│   │   ├── auth/            # Authentication components
│   │   ├── layout/          # Layout components
│   │   ├── repository/      # Repository components
│   │   ├── ui/              # Reusable UI components
│   │   └── visualizations/  # Data visualization components
│   ├── contexts/            # React contexts
│   ├── hooks/               # Custom React hooks
│   ├── pages/               # Page components
│   ├── services/            # API service functions
│   └── utils/               # Utility functions
├── lib/
│   ├── services/            # Backend services
│   │   ├── gitService.ts    # Git operations
│   │   ├── geminiService.ts # AI integration
│   │   └── repositoryService.ts # Repository logic
│   ├── prisma.ts            # Prisma client
│   ├── auth.ts              # Authentication utilities
│   └── middleware.ts        # Auth middleware
├── prisma/
│   └── schema.prisma        # Database schema
├── public/                  # Static assets
└── package.json             # Dependencies

🎨 Design System

Color Palette

• Primary: Deep Blue (#1E3A8A) - Professional and trustworthy
• Secondary: Slate Gray (#475569) - Neutral and sophisticated
• Accent: Electric Green (#10B981) - Active elements and success states
• Supporting: Orange (#F59E0B) for warnings, Red (#EF4444) for errors

Typography

• Headings: Inter
• Body: Source Sans 3
• Code: JetBrains Mono

🧩 Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm start - Start production server
• npm run lint - Run Next.js linter
• npm run format - Format code with Prettier
• npm run prisma:generate - Generate Prisma client
• npm run prisma:migrate - Run database migrations
• npm run prisma:studio - Open Prisma Studio

🔧 API Routes

All API routes are available under /api:

• /api/auth/* - Authentication (login, signup, logout, me)
• /api/repositories - Repository CRUD operations
• /api/repositories/[id] - Specific repository operations
• /api/repositories/[id]/stats - Repository statistics
• /api/repositories/[id]/analyze - Trigger repository analysis
• /api/ai/analyze-repository - AI repository analysis
• /api/ai/analyze-code - AI code analysis
• /api/ai/chat - AI chat interface
• /api/users/profile - User profile management
• /api/integrations/* - Git platform integrations

📑 API Pagination

To ensure consistent performance and predictability, paginated API endpoints in GitVerse use cursor-based pagination instead of traditional offset pagination.

Query Parameters

Parameter	Type	Default	Description
limit	number	10	The maximum number of items to return (clamped to max 50 for safety).
cursor	string	null	The ID of the last item received in the previous page. Omit for the first page.

Example Request

GET /api/auth/sessions?limit=20&cursor=clq123abc

Standard Response Format

All paginated endpoints return an object containing an items array and a nextCursor string. If nextCursor is present, it indicates there is more data available.

{
  "items": [
    { "id": "clq123abd", "expires": "2026-05-21T00:00:00.000Z" },
    { "id": "clq123abe", "expires": "2026-05-20T00:00:00.000Z" }
  ],
  "nextCursor": "clq123abf"
}

Frontend Consumption Best Practices

When fetching data in the UI (e.g., via infinite scrolling or "Load More" buttons), keep track of the nextCursor and pass it to subsequent requests. Avoid duplicate fetches by ensuring UI loading states block concurrent requests.

const loadMore = async () => {
  if (!nextCursor || isLoading) return;
  setIsLoading(true);
  
  try {
    const res = await fetch(`/api/auth/sessions?limit=20&cursor=${nextCursor}`);
    const data = await res.json();
    
    setItems((prev) => [...prev, ...data.items]);
    setNextCursor(data.nextCursor);
  } finally {
    setIsLoading(false);
  }
};

🚀 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard
4. Deploy!

✅ Vercel Environment Variables Checklist

Add these in Vercel Dashboard → Settings → Environment Variables:

Variable	Required	When needed
DATABASE_URL	✅ Always	PostgreSQL connection string (use NeonDB pooler URL)
NEXTAUTH_SECRET	✅ Always	Session encryption — generate with openssl rand -base64 32
NEXTAUTH_URL	✅ Always	Your production domain e.g. https://your-app.vercel.app
GEMINI_API_KEY	✅ Always	Google Gemini AI — get from aistudio.google.com
JWT_SECRET	✅ Always	JWT signing secret
GOOGLE_CLIENT_ID	⚡ OAuth	Only if using Google login
GOOGLE_CLIENT_SECRET	⚡ OAuth	Only if using Google login
GITHUB_APP_ID	⚡ PR Reviews	Only if using GitHub App integration
GITHUB_APP_PRIVATE_KEY	⚡ PR Reviews	Only if using GitHub App integration
GITHUB_WEBHOOK_SECRET	⚡ PR Reviews	Only if using GitHub webhooks
ANALYSIS_RUNNER_SECRET	⚡ Cron	Required for scheduled analysis jobs on Vercel
GITVERSE_ANALYSIS_BACKEND	⚡ Cron	URL of your analysis worker backend
SMTP_HOST	⚡ Email	Only if using password reset emails
SMTP_USER	⚡ Email	Only if using password reset emails
SMTP_PASS	⚡ Email	Only if using password reset emails

⚠️ Common Vercel Deployment Mistakes

• Wrong DATABASE_URL — Use the pooler URL from NeonDB for Vercel (not direct connection)
• Missing NEXTAUTH_URL — Must be set to your exact production domain
• GITHUB_APP_PRIVATE_KEY format — Paste with literal \n between lines, wrapped in quotes
• ANALYSIS_RUNNER_SECRET not set — Recommended for security; without it, the cron endpoint runs unauthenticated on Vercel

Docker

docker build -t gitverse-nextjs .
docker run -p 3000:3000 gitverse-nextjs

Firebase App Hosting (Cloud Run)

This repo includes App Hosting config in apphosting.yaml.

1. Create Secret Manager entries (names must match apphosting.yaml):

firebase apphosting:secrets:set webapp-firebase-api-key
firebase apphosting:secrets:set gemini-api-key
firebase apphosting:secrets:set database-url
firebase apphosting:secrets:set jwt-secret

firebase apphosting:secrets:set nextauth-url
firebase apphosting:secrets:set nextauth-secret
firebase apphosting:secrets:set google-client-id
firebase apphosting:secrets:set google-client-secret

2. Deploy:

firebase deploy

3. In Google Cloud Console (OAuth client), add redirect URI:

• https://<your-domain>/api/auth/callback/google

📝 Environment Variables

💡 For a full Vercel deployment checklist, see the Vercel Deployment section above.

Variable	Required	Description
DATABASE_URL	✅ Always	PostgreSQL connection string (use NeonDB pooler URL for Vercel)
JWT_SECRET	✅ Always	JWT signing secret key
GEMINI_API_KEY	✅ Always	Google Gemini API key for AI features
NEXTAUTH_URL	✅ Always	Deployed base URL e.g. https://<your-domain>
NEXTAUTH_SECRET	✅ Always	Session/JWT signing secret (generate with openssl rand -base64 32)
GOOGLE_CLIENT_ID	⚡ OAuth	Google OAuth client id
GOOGLE_CLIENT_SECRET	⚡ OAuth	Google OAuth client secret
GITHUB_APP_ID	⚡ PR Reviews	GitHub App ID
GITHUB_APP_PRIVATE_KEY	⚡ PR Reviews	GitHub App private key (PEM format)
GITHUB_WEBHOOK_SECRET	⚡ PR Reviews	GitHub webhook secret
ANALYSIS_RUNNER_SECRET	⚡ Cron	Required for scheduled analysis jobs on Vercel
GITVERSE_ANALYSIS_BACKEND	⚡ Cron	URL of your analysis worker backend
SMTP_HOST	⚡ Email	SMTP server for password reset emails
SMTP_USER	⚡ Email	SMTP username
SMTP_PASS	⚡ Email	SMTP password / app password
NEXT_PUBLIC_API_URL	Optional	API URL for client-side (defaults to current domain)

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Next.js team for the amazing framework
• Vercel for hosting solutions
• Google for Gemini AI
• NeonDB for serverless PostgreSQL
• All contributors and users of GitVerse

---

Made with ❤️ by the GitVerse Team