Skip to content

Improve README.md with setup instructions, how-to-play, and contributing #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
10vulture1005 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve README.md with setup instructions, how-to-play, and contributing #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 102 additions & 94 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,171 +1,179 @@
Mongo Buddy
# 🎮 Mongo Buddy

Mongo Buddy is a gamified learning platform for MongoDB. Level up through checkpoints, quizzes, and hands‑on tasks instead of dry docs. Earn points, unlock stages, and learn by doing CRUD, query operators, indexes, and aggregation pipelines.
**Mongo Buddy** is a gamified learning platform for MongoDB that makes database learning fun and interactive.

Live Demo
Level up through checkpoints, quizzes, and hands-on tasks instead of reading dry documentation. Earn points, unlock stages, and learn by doing—covering everything from CRUD operations to complex aggregation pipelines.

Try Mongo Buddy Live: https://mongobuddy.onrender.com
---

Features
## 🌐 Live Demo

1. Checkpoints: Unlock stages as concepts are completed.
**Try it here:** [Mongo Buddy Live](https://mongobuddy.onrender.com)

2. Quizzes: Interactive questions to test understanding.
---

3. Tasks: Real‑world MongoDB queries and operations.
## ✨ Features

4. Gamified Progression: Points, milestones, leveling.
- **📍 Checkpoints** – Unlock stages progressively as you complete concepts
- **❓ Interactive Quizzes** – Test your understanding with engaging questions
- **✅ Hands-On Tasks** – Practice real-world MongoDB queries and operations
- **🏆 Gamified Progression** – Earn points, hit milestones, and level up
- **💻 Learn by Doing** – Master CRUD, operators, indexes, and aggregation
- **📚 Structured Learning Path** – From MongoDB basics to advanced concepts
- **🔍 Query Operators** – Comparison, logical, array, and element operators
- **⚡ Indexes & Performance** – Optimize queries with proper indexing strategies
- **📊 Aggregation Pipelines** – `$match`, `$group`, `$project`, `$sort`, `$lookup`, and more
- **🌍 Real-World Challenges** – Apply your skills to practical scenarios

5. Learn by Doing: CRUD, operators, indexes, aggregation.
---

6. Learning Path Basics: Intro to MongoDB and CRUD operations.
## 🛠️ Tech Stack

7. Query Operators: Comparison, logical, array, element.
| Technology | Purpose |
|------------|---------|
| **MongoDB** | Database (local or Atlas) |
| **Node.js / Express** | Backend APIs and task validation |
| **Modern JavaScript** | Interactive gamified frontend |

8. Indexes & Performance: Speed up queries with the right indexes.
---

9. Aggregation: match, group, project, sort, lookup.
## ⚡ Getting Started (Run Locally)

10. Real‑World Challenges: Apply skills to practical scenarios.
### 1️⃣ Prerequisites

Tech Stack -
Ensure you have the following installed:

1. MongoDB for data (local or Atlas).
- **Node.js** `18+` and npm
- **MongoDB** (local installation or Atlas account)
- **Git**

1. Node.js/Express backend for APIs and tasks.

3. Frontend with a modern JS stack for gamified UI.

Follow these steps to run the project locally.

1. Prerequisites Node.js 18+ and npm

2. MongoDB (local) or MongoDB Atlas connection string

Git -

Check versions:

```
**Check your versions:**
```bash
node -v
npm -v
git --version
```
Fork and Clone - Fork the repository on GitHub (top-right “Fork” button).

Clone your fork:
### 2️⃣ Fork and Clone

```
1. **Fork the repository** on GitHub using the **Fork** button (top-right)
2. **Clone your fork** locally:

```bash
git clone https://github.com/<your-username>/MongoBuddy.git
cd MongoBuddy
```
Add the upstream remote (optional but recommended):

3. **Add the upstream remote** (optional but recommended):

```
```bash
git remote add upstream https://github.com/<upstream-owner>/MongoBuddy.git

git fetch upstream
```
Environment Variables - Copy the example file and fill in values:

```
### 3️⃣ Configure Environment Variables

Copy the example environment file:

```bash
cp .env.example .env
```
Edit .env with appropriate values:

text
Edit `.env` with your configuration:

```
```bash
MONGODB_URI="mongodb://localhost:27017/mongobuddy" # or your MongoDB Atlas URI
PORT=3000
SESSION_SECRET="change-this-to-a-strong-secret"
```

If using Atlas:

1. Create a free cluster.
**Using MongoDB Atlas?**
1. Create a free cluster at [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)
2. Whitelist your current IP address
3. Replace `MONGODB_URI` with your connection string

2. Whitelist current IP.
### 4️⃣ Install Dependencies

3. Replace MONGODB_URI with your connection string.

Install Dependencies
```
```bash
npm install
```

If the repo is a monorepo/workspaces project:
*For monorepo/workspace projects (if applicable):*

# Example workspace bootstrap (if applicable)
```
```bash
npm run bootstrap
```

Seed Sample Data (if available)
### 5️⃣ Seed Sample Data

```
Load initial data for learning checkpoints:

```bash
npm run seed
```

Run the App Development:
### 6️⃣ Run the Application

```
**Development mode:**
```bash
npm run dev
```

Production:

```
**Production mode:**
```bash
npm start
```

Open:


**Access the app:**
```
http://localhost:3000
```

How to Play Start at Checkpoint

1. MongoDB Basics.
---

2. Complete tasks and quizzes to move forward.
## 🎯 How to Play

3. Earn points and unlock new stages as progress is made.
1. **Start at Checkpoint 1** – MongoDB Basics
2. **Complete tasks and quizzes** to unlock the next stage
3. **Earn points** and progress through increasingly challenging content
4. **Master MongoDB** one checkpoint at a time!

Contributing -
---

1. Contributions are welcome, especially during Hacktoberfest.
## 🤝 Contributing

2. Quick Contribution Flow
Contributions are welcome! This project is perfect for **Hacktoberfest** and open-source contributions.

Create a feature branch:
### Quick Contribution Flow

```
git checkout -b feat/<short-feature-name>
```
Make changes, then commit:

```
git add .
1. **Create a feature branch:**
```bash
git checkout -b feat/<short-feature-name>
```

git commit -m "feat: add Aggregation Checkpoint 3 with 5 quiz questions"
```
Push your branch:

```
git push -u origin feat/<short-feature-name>
```
Open a Pull Request to the main branch of the upstream repo.
2. **Make your changes and commit:**
```bash
git add .
git commit -m "feat: add Aggregation Checkpoint 3 with 5 quiz questions"
```

What to Contribute
3. **Push your branch:**
```bash
git push -u origin feat/<short-feature-name>
```

1. New Checkpoints: topics, objectives, unlock criteria.
4. **Open a Pull Request** to the `main` branch of the upstream repository

2. Quizzes: multiple-choice with correct answers and explanations.
### 💡 What to Contribute

3. Tasks: CRUD and aggregation exercises with solutions/tests.
| Category | Ideas |
|----------|-------|
| **New Checkpoints** | Topics, objectives, unlock criteria |
| **Quizzes** | Multiple-choice questions with explanations |
| **Tasks** | CRUD and aggregation exercises with test cases |
| **UI/UX** | Game elements, progress bars, badges, accessibility |
| **Documentation** | Setup guides, troubleshooting, screenshots |

4. UI/UX: game elements, progress bars, badges, accessibility.
---

5. Docs: setup steps, troubleshooting, screenshots.
**Happy Learning! 🚀**