🏏 IPL Player Rankings - Skip List Leaderboard

A high-performance cricket leaderboard powered by Skip List data structure

Lightning-fast O(log n) operations • Real-time Rankings • IPL 2024 Data • Educational UI

Live Demo • API Docs • Report Bug • Request Feature

---

✨ Features

🎯 Core Functionality

• Add/Update Players - Efficiently manage player scores with automatic ranking
• Remove Players - Clean deletion with skip list pointer management
• Top-N Leaderboard - Instant access to top performers
• Player Search - O(log n) lookup with rank information
• Bulk Operations - Load sample IPL 2024 data instantly
• Real-time Statistics - Total players, highest/lowest/average scores

⚡ Performance

• O(log n) Operations - Insert, search, and delete
• Skip List Powered - Probabilistic balanced tree alternative
• Memory Efficient - Minimal overhead compared to balanced trees

🎨 Interactive UI

• Educational Modals - Learn skip list operations visually
• Complexity Display - See average/worst-case time complexities
• Live Status - Real-time backend connection indicator
• Responsive Design - Works on desktop and mobile
• IPL Theme - Cricket-themed interface with gradient colors

🧠 Educational Value

• Modal popups explain each skip list operation
• Visual feedback for insert, search, and delete operations
• Time complexity analysis (average & worst-case)
• Understanding of pointer manipulation in skip lists

---

📁 Project Structure

SKIP-LIST-LEADERBOARD/
│
├── 🔧 backend/
│   ├── __init__.py
│   ├── app.py              # FastAPI application & all endpoints
│   ├── leaderboard.py      # Leaderboard logic wrapper
│   └── skiplist.py         # Skip List core implementation
│
├── 📄 docs/
│   └── report.txt          # Technical documentation
│
├── 🎨 frontend/
│   └── index.html          # Interactive demo interface
│
├── 💻 skiplist_implementation/
│   ├── skip_list.py        # Python implementation
│   ├── skip_list.cpp       # C++ implementation
│   ├── skip_list.java      # Java implementation
│   └── skip_list.c         # C implementation
│
├── .gitignore              # Git ignore rules
├── requirements.txt        # Python dependencies
└── README.md              # You are here!

---

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• pip package manager
• Modern web browser (Chrome, Firefox, Safari, Edge)

Installation

1. Clone the repository

   git clone https://github.com/SH-Nihil-Mukkesh-25/skiplist-leaderboard.git
   cd skiplist-leaderboard

2. Set up virtual environment (recommended)

   python -m venv venv
   
   # Activate virtual environment
   source venv/bin/activate      # macOS/Linux
   venv\Scripts\activate         # Windows

3. Install dependencies

   pip install -r requirements.txt

4. Launch the API server

   uvicorn backend.app:app --reload --host 127.0.0.1 --port 8000

   You should see:

   INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
   INFO:     Started reloader process
   INFO:     Started server process
   INFO:     Application startup complete.
   

5. Access your application 🎉

   • Frontend UI: Open frontend/index.html in your browser
   • API Base: http://127.0.0.1:8000
   • Interactive Docs: http://127.0.0.1:8000/docs
   • Alternative Docs: http://127.0.0.1:8000/redoc

6. Try it out!

   • Click "Load IPL 2024 Data" to populate with 15 cricket players
   • Add your own players or search existing ones
   • Watch the educational modals explain skip list operations

---

📚 API Endpoints

Core Operations

Method	Endpoint	Description	Request Body
GET	/	Welcome page with endpoint list	None
GET	/health	Health check & player count	None
GET	/stats	Leaderboard statistics	None
POST	/add	Add/update player score	{"name": "string", "score": number}
POST	/bulk-add	Add multiple players	{"players": [{"name": "...", "score": ...}]}
GET	/top/{n}	Get top N players (max 1000)	None
GET	/all	Get all players sorted	None
GET	/search/{name}	Find player's score & rank	None
GET	/rank/{name}	Get player's rank details	None
DELETE	/remove/{name}	Remove player from leaderboard	None
DELETE	/clear	Clear entire leaderboard	None

🔧 Example Usage

Click to expand API examples

Health Check

curl "http://127.0.0.1:8000/health"

Response:

{
  "status": "healthy",
  "total_players": 15
}

Add/Update a Player

curl -X POST "http://127.0.0.1:8000/add" \
     -H "Content-Type: application/json" \
     -d '{"name": "Virat Kohli", "score": 7500}'

Response:

{
  "message": "Added Virat Kohli with 7500",
  "name": "Virat Kohli",
  "score": 7500,
  "rank": 1
}

Bulk Add Players (Load IPL Data)

curl -X POST "http://127.0.0.1:8000/bulk-add" \
     -H "Content-Type: application/json" \
     -d '{
       "players": [
         {"name": "Rohit Sharma", "score": 6628},
         {"name": "MS Dhoni", "score": 5243}
       ]
     }'

Response:

{
  "message": "Successfully added 2 players",
  "total_players": 17
}

Get Top 5 Players

curl "http://127.0.0.1:8000/top/5"

Response:

[
  {"name": "Virat Kohli", "score": 7500},
  {"name": "Shikhar Dhawan", "score": 6769},
  {"name": "Rohit Sharma", "score": 6628},
  {"name": "David Warner", "score": 6565},
  {"name": "Suresh Raina", "score": 5528}
]

Search for a Player

curl "http://127.0.0.1:8000/search/Virat%20Kohli"

Response:

{
  "name": "Virat Kohli",
  "score": 7500,
  "rank": 1,
  "found": true
}

Get Player Rank

curl "http://127.0.0.1:8000/rank/MS%20Dhoni"

Response:

{
  "name": "MS Dhoni",
  "rank": 7,
  "score": 5243,
  "total_players": 15
}

Get Statistics

curl "http://127.0.0.1:8000/stats"

Response:

{
  "total_players": 15,
  "highest_score": 7500,
  "lowest_score": 2434,
  "average_score": 4982.73,
  "top_player": {"name": "Virat Kohli", "score": 7500}
}

Remove a Player

curl -X DELETE "http://127.0.0.1:8000/remove/Virat%20Kohli"

Response:

{
  "message": "Removed Virat Kohli",
  "success": true
}

Clear All Players

curl -X DELETE "http://127.0.0.1:8000/clear"

Response:

{
  "message": "Cleared 15 players",
  "total_players": 0
}

---

🛠️ Tech Stack

• 🐍 Python 3.11+ - Modern Python with type hints
• ⚡ FastAPI - High-performance async web framework
• 📊 Skip List - Probabilistic data structure for O(log n) operations
• 🦄 Uvicorn - Lightning-fast ASGI server
• ✅ Pydantic - Data validation and serialization
• 🌐 CORS - Cross-origin resource sharing enabled
• 🎨 Vanilla JavaScript - No framework dependencies
• 💅 Modern CSS - Gradients, hover effects, responsive design

---

🧠 How It Works

Architecture Overview

┌─────────────┐     HTTP      ┌──────────────┐     Python     ┌────────────┐
│   Browser   │ ◄──────────► │   FastAPI    │ ◄────────────► │ Skip List  │
│  (HTML/JS)  │   REST API    │   Backend    │   Operations   │ Leaderboard│
└─────────────┘               └──────────────┘                └────────────┘

Data Structure Design

1. Player Storage: Dictionary for O(1) name lookups

   self.players = {}  # name → score

2. Score Ranking: Skip list maintains descending order

   self.skiplist.insert(-score, name)  # Negative for DESC order

3. Update Mechanism: Remove old entry, insert new one

   if name in self.players:
       old_score = self.players[name]
       self.skiplist.delete(-old_score)
   self.skiplist.insert(-score, name)

Time Complexity Analysis

Operation	Average	Worst Case	Explanation
Insert	O(log n)	O(n)	Traverse levels top-down, probabilistic balancing
Delete	O(log n)	O(n)	Find node, update forward pointers across levels
Search	O(log n)	O(n)	Express lanes (higher levels) speed up traversal
Top-N	O(n)	O(n)	Linear scan through first n nodes
Get Rank	O(n)	O(n)	Count nodes until target found

Skip List Advantages

✅ Simpler than balanced trees (AVL, Red-Black)
✅ Lock-free concurrent access possible
✅ Memory efficient - No color/balance metadata
✅ Probabilistic balancing - No rotations needed
✅ Cache-friendly - Sequential memory access patterns

---

🎨 Frontend UI Features

Main Interface

• Status Bar: Real-time backend connection indicator (Online ✓ / Offline ✗)
• Player Form: Add players with name and score validation
• Action Buttons:
  • 🏆 Load Rankings - Refresh top N players
  • 🔍 Search Player - Find specific player
  • 📊 Get Player Rank - View rank details
  • ❌ Remove Player - Delete from leaderboard
• Sample Data: Load IPL 2024 data (15 players) instantly
• Statistics Panel: Shows total players, highest/lowest/average runs

Educational Modals

Each operation displays a modal explaining the skip list mechanics:

Insert Operation

• Average: O(log n), Worst: O(n)
• Explains level traversal and pointer updates
• Shows player name, score, and resulting rank

Search Operation

• Average: O(log n), Worst: O(n)
• Describes express lane traversal
• Displays found player's score and rank

Delete Operation

• Average: O(log n), Worst: O(n)
• Explains pointer rewiring across levels
• Confirms successful removal

Visual Design

• Modern Gradients: Blue gradient header (#1e3a8a → #3b82f6)
• Rank Badges: Gold/Silver/Bronze for top 3 players
• Hover Effects: Interactive row highlighting
• Responsive Layout: Grid-based design adapts to screen size
• Loading States: Visual feedback during API calls
• Error/Success Messages: Toast-style notifications

---

🚦 Performance Benchmarks

Skip List vs. Other Data Structures

Data Structure	Insert	Delete	Search	Get Min/Max	Space
Skip List	O(log n)	O(log n)	O(log n)	O(1)	O(n)
Sorted Array	O(n)	O(n)	O(log n)	O(1)	O(n)
Binary Heap	O(log n)	O(log n)	O(n)	O(1)	O(n)
AVL Tree	O(log n)	O(log n)	O(log n)	O(log n)	O(n)
Hash Table	O(1)*	O(1)*	O(1)*	O(n)	O(n)

*Hash tables don't maintain order, so can't efficiently get top-N

Real-World Performance

Tested with IPL 2024 dataset (15 players):

• Bulk Insert: ~1ms for all 15 players
• Single Search: <0.1ms average
• Top-10 Query: <0.5ms
• Delete + Reinsert: ~0.2ms

---

👥 Contributors

This project features Skip List implementations in multiple programming languages:

Language	Implementation	Contributor
🐍 Python	Web API + Frontend + SkipList Implementation	SH Nihil Mukkesh
☕ Java	SkipList Implementation	P Dakshin Raj
⚡ C++	SkipList Implementation + PPT	Vibin Ragav S
🔧 C	SkipList Implementation	Shre Raam PJ

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

Ways to Contribute

1. 🐛 Report bugs - Open an issue with detailed description
2. 💡 Suggest features - Share your ideas for improvements
3. 📝 Improve documentation - Help others understand the code
4. 🎨 Enhance UI - Make the interface more beautiful
5. ⚡ Optimize performance - Make skip list operations faster
6. 🌍 Add translations - Support multiple languages

Development Workflow

1. Fork the project
2. Create your feature branch

   git checkout -b feature/AmazingFeature

3. Make your changes and test thoroughly
4. Commit with descriptive messages

   git commit -m 'Add: New player statistics endpoint'

5. Push to your branch

   git push origin feature/AmazingFeature

6. Open a Pull Request with detailed description

---

📖 Learn More

Skip List Resources

• Original Paper by William Pugh (1990)
• Skip List Visualization
• Redis Implementation

FastAPI Resources

• Official Documentation
• Tutorial
• Deployment Guide

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• William Pugh - For inventing the skip list data structure
• FastAPI Team - For making Python APIs enjoyable
• IPL - For providing cricket statistics inspiration
• Open Source Community - For continuous inspiration and support

---

⭐ Star this repo if you found it helpful!

Made with ❤️ and ☕ by SH-Nihil-Mukkesh-25

⬆ Back to Top