GSoC Issue Finder

A full-stack web app to find open, unassigned GitHub issues suitable for GSoC contributions — with a React frontend, Flask API, and SQLite3 database.

---

Stack

Layer	Tech
Frontend	React (Vite), Lucide icons
Backend	Flask + flask-cors
Database	SQLite3 (via gsoc_finder.db)
API	GitHub REST API v3

---

Project Structure

gsoc-finder/
├── backend/
│   ├── app.py           # Flask routes
│   ├── db.py            # SQLite3 schema + helpers
│   ├── github_api.py    # GitHub API logic (ported from original script)
│   ├── requirements.txt
│   └── config.json      # Created on first token save (gitignored)
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Dashboard.jsx   # Launch scans, stats overview
│   │   │   ├── Repos.jsx       # Manage repo list
│   │   │   ├── Scans.jsx       # Scan history
│   │   │   ├── ScanDetail.jsx  # Live progress + issue browser
│   │   │   ├── Bookmarks.jsx   # Saved issues with notes
│   │   │   └── Config.jsx      # GitHub token settings
│   │   ├── components/
│   │   │   └── IssueCard.jsx   # Reusable issue card with bookmark
│   │   └── api.js              # Axios API wrapper
│   └── vite.config.js          # Proxy /api → Flask
└── start.sh             # Start both servers

---

Quick Start

1. Backend

cd backend
python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.py
# Runs on http://localhost:5000

2. Frontend

cd frontend
npm install
npm run dev
# Runs on http://localhost:5173

Or use the convenience script:

chmod +x start.sh
./start.sh

---

First-Time Setup

1. Open http://localhost:5173
2. Go to Settings and paste your GitHub token
   • Get one at https://github.com/settings/tokens?type=beta
   • Fine-grained token, public repos read-only, no extra scopes needed
3. Go to Repos and add repos to scan (or use the preset chips)
4. Go to Dashboard, select repos, pick scan mode, and hit Scan
5. Watch live progress in Scans → Scan #N
6. Bookmark issues you want to work on; add notes in Bookmarks

---

Database Schema

Table	Purpose
repos	Tracked GitHub repos with active/paused state
scans	Scan jobs with status, mode, timing
issues	All found issues per scan (refreshable)
bookmarks	User-saved issues with personal notes

---

API Endpoints

Method	Path	Description
GET	/api/config	Check token status
POST	/api/config	Save GitHub token
GET	/api/repos	List repos
POST	/api/repos	Add repo
DELETE	/api/repos/:id	Remove repo
POST	/api/repos/:id/toggle	Pause/resume repo
GET	/api/scans	List all scans
POST	/api/scans	Start a new scan
GET	/api/scans/:id	Get scan + progress
POST	/api/scans/:id/refresh	Re-run a scan
DELETE	/api/scans/:id	Delete scan + its issues
GET	/api/scans/:id/issues	Get issues (filterable)
GET	/api/bookmarks	List bookmarks
POST	/api/bookmarks	Add bookmark
DELETE	/api/bookmarks/:id	Remove bookmark
PATCH	/api/bookmarks/:id/notes	Update notes