🐛 BugBuster — DSA Debugging Arena

A gamified C++ debugging platform with 100 levels, multiple question formats, XP scoring, streaks, hints, and full login/register system. Built as a GeeksForGeeks collaboration pitch prototype.

---

🚀 How to Run (Step by Step for First-Timers)

Step 1 — Install Node.js

Go to: https://nodejs.org
Download the LTS version and install it.
Verify installation by opening a terminal and typing:

node --version
npm --version

Both should print a version number (e.g. v20.x.x).

---

Step 2 — Open a Terminal in This Folder

• Windows: Right-click the bugbuster-dsa folder → "Open in Terminal"
• Mac: Right-click the folder → "New Terminal at Folder"
• VS Code: Open the folder → press Ctrl+` (backtick)

---

Step 3 — Install Dependencies

npm install

This downloads React and all required packages into a node_modules folder. Takes about 1–2 minutes. You only need to do this once.

---

Step 4 — Start the App

npm start

Your browser will open automatically at: http://localhost:3000

The app hot-reloads — any changes you save appear instantly.

---

Step 5 — Register & Play

1. Click "Create one →" to register an account
2. Your data is saved locally in the browser (localStorage)
3. Start debugging from Level 1!

---

📁 Project Structure

bugbuster-dsa/
├── public/
│   └── index.html              ← HTML template
├── src/
│   ├── App.js                  ← Main router (screens: home/levels/game)
│   ├── index.js                ← React entry point
│   ├── index.css               ← Global CSS variables & animations
│   ├── context/
│   │   └── AuthContext.js      ← Login/register/user state
│   ├── data/
│   │   └── levels.js           ← All 100 level definitions
│   └── components/
│       ├── Login.js / .css     ← Login screen
│       ├── Register.js         ← Register screen
│       ├── Auth.css            ← Shared auth styles
│       ├── Home.js / .css      ← Home dashboard
│       ├── LevelSelect.js/.css ← Level map grid
│       └── Game.js / .css      ← Game engine + victory screen
└── package.json

---

🎮 Features

Feature	Details
100 Levels	Syntax (1–15) → Semantic (16–30) → Logical (31–45) → Algorithm (46–100)
3 Question Formats	MCQ, Click-the-Bug (click the exact line), Fill-in-the-Blank
XP System	Base XP + Speed Bonus − Hint Penalty − Attempt Penalty
Hint System	−15 XP each, reveals a conceptual clue (never the answer)
Countdown Timer	Adjusts by tier: 120s → 180s → 240s → 300s
Streaks	Consecutive correct answers tracked
Auth	Register/Login with localStorage persistence
Progress Save	XP, completed levels, streak all saved per user

---

🌐 Deploy Free Online (Share with GFG)

Option A — Vercel (Recommended, 2 minutes)

npm install -g vercel
npm run build
vercel --prod

Get a live URL like: https://bugbuster-dsa.vercel.app

Option B — Netlify

npm run build

Then drag the build/ folder to: https://app.netlify.com/drop

Option C — GitHub Pages

npm install --save-dev gh-pages

Add to package.json scripts: "deploy": "gh-pages -d build"
Then: npm run build && npm run deploy

---

🔧 Adding More Levels

Open src/data/levels.js and add a new object to the LEVELS_DATA array:

{
  n: 101,                    // Level number
  tier: 'algo',              // 'syntax' | 'semantic' | 'logical' | 'algo'
  fmt: 'mcq',                // 'mcq' | 'line_click' | 'fill_blank'
  title: 'My Level Title',
  desc: 'Description shown to the player.',
  code: `// Your C++ code here\nint main() { ... }`,
  bug_line: 5,               // (for line_click) which line has the bug
  bug: 'Explanation of bug', // shown in victory screen on wrong answer
  options: ['A','B','C','D'],// (for mcq only)
  correct: 1,                // (for mcq) 0-indexed correct option
  hint: 'Conceptual hint without giving away the answer.',
  xp: 300,                   // Base XP reward
}

---

🤝 GeeksForGeeks Integration Plan

• Phase 1: Host as standalone at bugbuster.dev
• Phase 2: Embed GFG problem links per level ("Learn more on GFG →")
• Phase 3: OAuth login via GFG account
• Phase 4: Leaderboard synced with GFG practice scores
• Phase 5: 10,000-level expansion with AI-generated questions (Claude API)

---

📝 Notes

• Auth uses localStorage (no backend). For production, replace with a real backend (Node + MongoDB, Firebase, Supabase, etc.)
• Passwords are stored in plain text in localStorage — fine for a prototype, must be hashed (bcrypt) in production
• To reset all data: open browser DevTools → Application → Local Storage → Clear All

---

Built with React · Styled with pure CSS · No external UI libraries