RepoSense 🚀

Turn idea into impact faster — Understand any codebase in 2 minutes, not 2 weeks.

RepoSense is an AI-powered repository onboarding tool that analyzes GitHub repositories and generates comprehensive onboarding reports using IBM Bob. Built for the IBM Bob Hackathon.

🎯 Problem We Solve

Developers waste weeks understanding new codebases:

• Reading scattered documentation
• Tracing data flows manually
• Finding the right files to start with
• Understanding architecture patterns

RepoSense solves this in 2 minutes.

✨ Features

🤖 Powered by IBM Bob (All 4 Modes)

RepoSense leverages all IBM Bob modes for comprehensive analysis:

1. Plan Mode — Analyzes repository architecture and creates structured onboarding plans
2. Ask Mode — Answers questions about the codebase with full context
3. Code Mode — Generates actual code fixes and improvements
4. Orchestrator Mode — Chains all modes together for complete task automation

📊 What You Get

• Project Overview — What it does, tech stack, complexity rating
• Architecture Analysis — Design patterns, data flow, folder structure
• Key Files Guide — Ordered list of files to read first with explanations
• Onboarding Steps — Step-by-step checklist generated by Bob
• Gotchas & Warnings — Common pitfalls and important notes
• Interactive Q&A — Ask Bob anything about the codebase
• Code Kickstarter — Bob finds an issue, writes the fix, explains it
• Export — Download your full onboarding guide as Markdown

🏗️ Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   React     │─────▶│   FastAPI    │─────▶│  IBM Bob    │
│  Frontend   │      │   Backend    │      │     API     │
└─────────────┘      └──────────────┘      └─────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │  GitHub API  │
                     └──────────────┘

Tech Stack

Frontend:

• React 18 with Hooks
• Tailwind CSS for styling
• Vite for build tooling

Backend:

• Python 3.11+
• FastAPI for REST API
• httpx for async HTTP
• Pydantic for validation

AI Integration:

• IBM Bob API (all 4 modes)
• Custom prompt engineering
• Context-aware responses

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.11+
• IBM Bob API key (or use mock mode)

Backend Setup

cd reposense/backend

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your IBM_BOB_API_KEY
# Or set IBM_BOB_API_KEY=mock for development

# Run server
python server.py

Backend runs on http://localhost:8000

Frontend Setup

cd reposense/frontend

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env if needed (default: http://localhost:8000)

# Run development server
npm run dev

Frontend runs on http://localhost:5173

Using Mock Mode (No API Key Required)

For development and testing without IBM Bob API access:

Backend:

# In backend/.env
IBM_BOB_API_KEY=mock

Frontend:

# In frontend/.env
VITE_MOCK_MODE=false  # Keep false, backend handles mocking

Mock mode returns realistic sample data for expressjs/express repository.

📖 Usage

1. Open the app at http://localhost:5173
2. Paste a GitHub URL (e.g., https://github.com/expressjs/express)
3. Click "Analyze repo" - Bob reads the entire codebase
4. Explore the report:
   • Overview tab: Architecture, key files, onboarding steps
   • Coding tab: Bob finds an issue and writes the fix
   • Chat tab: Ask Bob questions about the code
5. Export as Markdown

Example Repositories to Try

• https://github.com/expressjs/express - Node.js web framework
• https://github.com/facebook/react - React library
• https://github.com/fastapi/fastapi - Python web framework

🔧 API Endpoints

POST /api/analyze

Analyzes a GitHub repository and returns complete onboarding report.

Request:

{
  "github_url": "https://github.com/owner/repo"
}

Response:

{
  "project_name": "express",
  "what_it_does": "Fast, unopinionated web framework for Node.js",
  "architecture_type": "MVC",
  "tech_stack": [...],
  "key_files": [...],
  "onboarding_steps": [...],
  "gotchas": [...],
  "bob_modes_used": ["Plan", "Ask"]
}

POST /api/ask

Ask questions about the repository.

Request:

{
  "github_url": "https://github.com/owner/repo",
  "question": "How does routing work?",
  "history": []
}

POST /api/task

Generate code for a task (Orchestrator mode).

Request:

{
  "github_url": "https://github.com/owner/repo"
}

POST /api/export/markdown

Export onboarding report as Markdown.

GET /api/health

Health check endpoint.

🎯 IBM Bob Integration

RepoSense demonstrates complete IBM Bob integration across all modes:

1. Plan Mode

# Used for repository analysis
response = bob_client.analyze(repo_context)
# Returns: architecture, tech stack, onboarding plan

2. Ask Mode

# Used for Q&A and explanations
response = bob_client.ask(repo_context, question, history)
# Returns: contextual answers with file references

3. Code Mode

# Used for code generation
response = bob_client.generate_code(repo_context, plan)
# Returns: actual code with diffs

4. Orchestrator Mode

# Chains all modes together
response = bob_client.orchestrate(repo_context)
# Pipeline: find_issue → plan → code → explain

Why This Matters for Judges

• Full Bob Utilization - Uses all 4 modes, not just one
• Real Context - Sends actual repository structure to Bob
• No Hallucinations - Bob only references real files
• Production Ready - Error handling, retries, timeouts
• Extensible - Easy to add more Bob-powered features

🏆 Hackathon Theme Alignment

Theme: "Turn idea into impact faster"

RepoSense embodies this by:

• ✅ Reducing onboarding time from weeks to minutes
• ✅ Accelerating contribution with AI-generated code
• ✅ Lowering barriers for new contributors
• ✅ Increasing impact by helping developers start faster

🛠️ Development

Project Structure

reposense/
├── backend/
│   ├── server.py           # FastAPI application
│   ├── github_parser.py    # GitHub API integration
│   ├── bob_client.py       # IBM Bob API client
│   ├── prompts.py          # Prompt engineering
│   └── requirements.txt    # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── App.jsx         # Main React component
│   │   └── services/
│   │       └── api.js      # API client
│   ├── package.json        # Node dependencies
│   └── vite.config.js      # Vite configuration
└── README.md

Running Tests

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

Building for Production

# Backend
cd backend
pip install -r requirements.txt

# Frontend
cd frontend
npm run build
# Output in frontend/dist/

🚢 Deployment

Backend (Railway/Render)

# Set environment variables
IBM_BOB_API_KEY=your_key
PORT=8000
ALLOWED_ORIGINS=https://your-frontend.vercel.app

Frontend (Vercel)

# Set environment variables
VITE_API_URL=https://your-backend.railway.app

📝 Environment Variables

Backend (.env)

Variable	Description	Required
IBM_BOB_API_KEY	IBM Bob API key (or "mock")	Yes
IBM_BOB_BASE_URL	Bob API base URL	No
PORT	Server port	No (default: 8000)
ALLOWED_ORIGINS	CORS origins	No

Frontend (.env)

Variable	Description	Required
VITE_API_URL	Backend API URL	No (default: localhost:8000)
VITE_MOCK_MODE	Enable mock mode	No (default: false)

🤝 Contributing

This is a hackathon project, but contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details

👥 Team

• Ranveer Kumar | Team Apocalypto
• Built for the IBM Bob Hackathon

🙏 Acknowledgments

• IBM Bob - For the amazing AI capabilities
• GitHub - For the public API
• FastAPI - For the excellent Python framework
• React - For the frontend framework

📞 Support

For questions or issues, open a GitHub issue.

---

Made with ❤️ and IBM Bob