OASIS Protocol - Buildathon Platform

A comprehensive platform for hosting algorithmic challenges and buildathon competitions, inspired by the OASIS from Ready Player One.

🌟 Features

For Teams

• Team Registration & Authentication: Google OAuth2.0 + traditional email/password
• Progressive Challenge System: Unlock challenges by completing previous ones
• Advanced Code Editor: Monaco Editor with multi-language support
• Real-time Code Execution: Judge0 API integration for instant feedback
• Flag Submission System: Submit flags to unlock buildathon challenges
• Buildathon Submissions: GitHub repository submission system
• Live Leaderboard: Real-time ranking updates via WebSocket
• Responsive Design: Mobile-friendly interface

For Administrators

• Admin Dashboard: Real-time statistics and monitoring
• Challenge Management: Create, edit, and manage challenges
• Team Management: View team details and manage accounts
• Submission Monitoring: Track all submissions with detailed views
• Real-time Updates: WebSocket-powered live data

🛠️ Technology Stack

Backend

• Node.js with Express.js
• MySQL database with Sequelize ORM
• JWT authentication + Passport.js for OAuth
• Socket.IO for real-time updates
• Judge0 API for code execution
• bcryptjs for password hashing

Frontend

• React with Vite
• Tailwind CSS for styling
• Monaco Editor for code editing
• Socket.IO Client for real-time features
• React Router for navigation
• Axios for API calls

🚀 Quick Start

Prerequisites

• Node.js (v16 or higher)
• MySQL database
• Judge0 API access (or local Judge0 instance)

1. Clone the Repository

git clone https://github.com/Kasun333/-Oasis-Protocol.git
cd oasis-protocol

2. Backend Setup

cd backend
npm install

3. Environment Configuration

Create .env file in the backend directory:

# Database Configuration
DB_HOST=your_mysql_host
DB_PORT=3306
DB_NAME=oasis_protocol
DB_USER=your_mysql_username
DB_PASSWORD=your_mysql_password

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_here
JWT_EXPIRES_IN=7d

# Google OAuth Configuration
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:5000/api/auth/google/callback

# Judge0 Configuration
JUDGE0_API_URL=https://judge0-ce.p.rapidapi.com
JUDGE0_API_KEY=your_judge0_api_key

# Server Configuration
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:5173

4. Database Initialization

# Initialize database with sample data
node scripts/init-db.js

5. Start Backend Server

npm run dev

6. Frontend Setup

cd ../frontend
npm install

Create .env file in the frontend directory:

# API Configuration
VITE_API_URL=http://localhost:5000/api
VITE_SOCKET_URL=http://localhost:5000

# Google OAuth Configuration
VITE_GOOGLE_CLIENT_ID=your_google_client_id

7. Start Frontend Development Server

npm run dev

🔧 Configuration

Database Setup

1. Create a MySQL database named oasis_protocol
2. Update database credentials in backend .env file
3. Run the initialization script to create tables and sample data

Judge0 API Setup

1. Sign up for Judge0 API at RapidAPI
2. Get your API key and update JUDGE0_API_KEY in backend .env
3. Alternatively, set up a local Judge0 instance

Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URIs:
   • http://localhost:5000/api/auth/google/callback (development)
   • https://yourdomain.com/api/auth/google/callback (production)
6. Update Google credentials in both backend and frontend .env files

📁 Project Structure

oasis-protocol/
├── backend/
│   ├── config/
│   │   ├── database.js          # Database configuration
│   │   └── passport.js          # Passport authentication setup
│   ├── controllers/
│   │   ├── adminController.js   # Admin operations
│   │   ├── authController.js    # Authentication logic
│   │   └── challengeController.js # Challenge operations
│   ├── middleware/
│   │   ├── auth.js             # Authentication middleware
│   │   └── validation.js       # Request validation
│   ├── models/
│   │   ├── Admin.js            # Admin model
│   │   ├── Challenge.js        # Challenge model
│   │   ├── Submission.js       # Submission model
│   │   ├── User.js             # User model
│   │   └── index.js            # Model associations
│   ├── routes/
│   │   ├── admin.js            # Admin routes
│   │   ├── auth.js             # Authentication routes
│   │   ├── challenges.js       # Challenge routes
│   │   └── leaderboard.js      # Leaderboard routes
│   ├── scripts/
│   │   └── init-db.js          # Database initialization
│   ├── utils/
│   │   ├── judge0.js           # Judge0 API integration
│   │   └── jwt.js              # JWT utilities
│   ├── .env                    # Environment variables
│   ├── package.json
│   └── server.js               # Main server file
├── frontend/
│   ├── src/
│   │   ├── components/         # Reusable components
│   │   ├── contexts/           # React contexts
│   │   ├── pages/              # Page components
│   │   │   ├── admin/          # Admin pages
│   │   │   └── ...             # User pages
│   │   ├── services/           # API services
│   │   ├── App.jsx             # Main app component
│   │   └── main.jsx            # Entry point
│   ├── .env                    # Environment variables
│   ├── package.json
│   └── vite.config.js          # Vite configuration
└── README.md

🎮 Usage

Default Admin Credentials

• Username: admin
• Password: admin123

Team Registration

1. Teams can register using email/password or Google OAuth
2. Each team gets a unique team name and email
3. Teams start at Challenge 1 and progress sequentially

Challenge Flow

1. Algorithmic Phase: Solve coding problems using the built-in editor
2. Flag Submission: Submit the correct flag to unlock buildathon
3. Buildathon Phase: Submit GitHub repository with project solution
4. Progression: Complete both phases to advance to next challenge

Admin Operations

1. Dashboard: Monitor real-time statistics
2. Challenge Management: Create/edit challenges with algorithmic and buildathon components
3. Team Management: View team details and manage accounts
4. Submission Monitoring: Track all submissions with execution details

🔒 Security Features

• JWT-based authentication with secure token handling
• Password hashing using bcryptjs
• Input validation and sanitization
• CORS configuration for cross-origin requests
• Environment-based configuration management
• SQL injection prevention through Sequelize ORM

🌐 Deployment

Backend Deployment (Railway)

1. Connect your GitHub repository to Railway
2. Set environment variables in Railway dashboard
3. Deploy the backend service
4. Update FRONTEND_URL to your frontend domain

Frontend Deployment (Netlify)

1. Build the frontend: npm run build
2. Deploy the dist folder to Netlify
3. Update VITE_API_URL to your backend domain
4. Configure redirects for SPA routing

Database Hosting

• Use Railway PostgreSQL, PlanetScale, or any MySQL hosting service
• Update database credentials in environment variables
• Run initialization script on production database

🧪 Testing

Backend Testing

cd backend
npm test

Frontend Testing

cd frontend
npm test

Manual Testing Checklist

• Team registration and login
• Google OAuth authentication
• Admin login and dashboard
• Challenge creation and editing
• Code execution with Judge0
• Flag submission system
• Buildathon GitHub submission
• Real-time leaderboard updates
• Responsive design on mobile

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature-name
5. Submit a pull request

📝 API Documentation

Authentication Endpoints

• POST /api/auth/register - Team registration
• POST /api/auth/login - Team login
• GET /api/auth/google - Google OAuth login
• POST /api/auth/admin/login - Admin login

Challenge Endpoints

• GET /api/challenges - Get available challenges
• GET /api/challenges/:id - Get specific challenge
• POST /api/challenges/:id/submit-code - Submit code for execution
• POST /api/challenges/:id/submit-flag - Submit flag
• POST /api/challenges/:id/submit-buildathon - Submit buildathon solution

Admin Endpoints

• GET /api/admin/dashboard - Dashboard statistics
• GET /api/admin/challenges - Manage challenges
• GET /api/admin/teams - Manage teams
• GET /api/admin/submissions - View submissions

Public Endpoints

• GET /api/leaderboard - Public leaderboard

🐛 Troubleshooting

Common Issues

1. Database Connection Error

   • Check MySQL service is running
   • Verify database credentials in .env
   • Ensure database exists

2. Judge0 API Error

   • Verify API key is correct
   • Check API quota limits
   • Ensure internet connectivity

3. Google OAuth Error

   • Check client ID and secret
   • Verify redirect URIs in Google Console
   • Ensure OAuth consent screen is configured

4. WebSocket Connection Issues

   • Check CORS configuration
   • Verify Socket.IO client/server versions match
   • Check firewall settings

📄 License

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

🙏 Acknowledgments

• Inspired by "Ready Player One" by Ernest Cline
• Judge0 API for code execution
• Monaco Editor for code editing experience
• Socket.IO for real-time features
• Tailwind CSS for beautiful UI components

📞 Support

For support and questions:

• Create an issue in the GitHub repository
• Contact the development team
• Check the troubleshooting section above

---

Ready Player One? Welcome to the OASIS Protocol! 🎮✨