{"id":31908251,"url":"https://github.com/elyeandre/bataan-badminton-portal","last_synced_at":"2025-10-13T15:26:02.437Z","repository":{"id":315990675,"uuid":"1061502027","full_name":"elyeandre/bataan-badminton-portal","owner":"elyeandre","description":"A comprehensive badminton court management and booking system for Bataan Province. Features court scheduling, user payments, membership management, events \u0026 tournaments, and admin dashboard with PayPal integration.","archived":false,"fork":false,"pushed_at":"2025-09-22T02:46:06.000Z","size":9347,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-22T04:24:57.246Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elyeandre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T02:18:37.000Z","updated_at":"2025-09-22T02:46:10.000Z","dependencies_parsed_at":"2025-09-22T04:25:01.874Z","dependency_job_id":"24bb22c5-b483-48d3-b315-d676f95058a9","html_url":"https://github.com/elyeandre/bataan-badminton-portal","commit_stats":null,"previous_names":["elyeandre/bataan-badminton-portal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/elyeandre/bataan-badminton-portal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyeandre%2Fbataan-badminton-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyeandre%2Fbataan-badminton-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyeandre%2Fbataan-badminton-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyeandre%2Fbataan-badminton-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elyeandre","download_url":"https://codeload.github.com/elyeandre/bataan-badminton-portal/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyeandre%2Fbataan-badminton-portal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015920,"owners_count":26085778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-13T15:26:00.352Z","updated_at":"2025-10-13T15:26:02.430Z","avatar_url":"https://github.com/elyeandre.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏸 Bataan Badminton Management Portal\n\n[![Made With Javascript][made-with-javascript]][forthebadge-url]\n[![Built With Love][built-with-love]][forthebadge-url]\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n\nA comprehensive **full-stack web application** that serves as a unified platform for the badminton community in Bataan, Philippines. This capstone project seamlessly integrates court reservations, membership management, community engagement, e-commerce, and real-time communications into one powerful portal.\n\n## 📋 Table of Contents\n- [🎯 Project Overview](#-project-overview)\n- [✨ Key Features](#-key-features)\n- [🛠️ Tech Stack](#️-tech-stack)\n- [🏗️ Architecture](#️-architecture)\n- [📁 Project Structure](#-project-structure)\n- [🚀 Quick Start](#-quick-start)\n- [⚙️ Configuration](#️-configuration)\n- [📱 Usage Guide](#-usage-guide)\n- [🔒 Security Features](#-security-features)\n- [🌐 API Documentation](#-api-documentation)\n- [🚀 Deployment](#-deployment)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n\n## 🎯 Project Overview\n\nThe **Bataan Badminton Management Portal** is a sophisticated web application designed to revolutionize how the badminton community in Bataan, Philippines, interacts with court facilities and each other. Built as a capstone project, it demonstrates enterprise-level development practices while solving real-world problems in sports facility management.\n\n### 🎪 Live Demo\n**Admin Dashboard (Portfolio Demo)**\n- **URL**: http://212.69.85.122:5000/\n- **Username**: `superadmin`\n- **Password**: `superadmin`\n- ⚠️ **Note**: Demo credentials for portfolio purposes only. Remove or change in production.\n\n### 🎯 Target Users\n- **🏃‍♂️ Players**: Book courts, join events, connect with community\n- **👨‍🏫 Coaches**: Manage training sessions, organize events\n- **🏢 Court Owners**: Manage facilities, track reservations, handle payments\n- **👑 Administrators**: Oversee platform operations and user management\n\n### 🌟 Problem Statement\nThe badminton community in Bataan lacked a centralized platform for:\n- Finding and booking available courts\n- Managing reservations efficiently\n- Connecting players and organizing events\n- Purchasing badminton equipment\n- Real-time communication and updates\n\n## ✨ Key Features\n\n### 🏟️ **Court Management System**\n- **Court Registration**: Owners can register and manage their facilities\n- **Real-time Availability**: Live court slot updates via WebSocket\n- **Interactive Mapping**: 2D map integration for easy court location\n- **Operating Hours**: Flexible scheduling with custom time slots\n- **Multi-court Support**: Handle multiple courts per facility\n\n### 📅 **Advanced Reservation System**\n- **Smart Booking**: Intelligent conflict prevention and validation\n- **Real-time Updates**: Instant availability changes across all users\n- **Payment Integration**: Seamless PayPal payment processing\n- **Automated Cleanup**: Cron jobs for expired and cancelled reservations\n- **Reservation History**: Complete booking timeline and status tracking\n\n### 👥 **User Management \u0026 Authentication**\n- **Multi-role System**: Player, Coach, Court Owner, Superadmin roles\n- **JWT Security**: Secure token-based authentication\n- **OTP Verification**: Email-based two-factor authentication\n- **Profile Management**: Comprehensive user profiles with file uploads\n- **Password Security**: Advanced password policies and reset flows\n\n### 🏆 **Community Features**\n- **Social Feed**: Community posts with hashtag support\n- **Interactive Engagement**: Comments, likes, and real-time interactions\n- **Events \u0026 Tournaments**: Organize and participate in badminton events\n- **Announcements**: Broadcast important updates to community\n- **Member Directory**: Connect with other badminton enthusiasts\n\n### 🛒 **E-commerce Integration**\n- **Product Catalog**: Badminton equipment and accessories\n- **Shopping Cart**: Full-featured cart with session persistence\n- **Order Management**: Complete order lifecycle tracking\n- **PayPal Integration**: Secure payment processing with webhooks\n- **Inventory Tracking**: Real-time stock management\n\n### 📧 **Communication System**\n- **Email Notifications**: Automated emails for all major events\n- **Real-time Alerts**: Instant in-app notifications via Socket.IO\n- **OTP Management**: Secure one-time password system\n- **Transactional Emails**: Order confirmations, reservation updates\n- **Broadcast Messaging**: System-wide announcements\n\n### 🗺️ **Location Services**\n- **Court Locator**: Interactive map with facility markers\n- **Address Geocoding**: Automatic coordinate generation\n- **Directions Integration**: Easy navigation to court locations\n\n## 🏗️ Architecture\n\n### **System Architecture**\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Client Side   │    │   Server Side   │    │   External      │\n│                 │    │                 │    │   Services      │\n│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │\n│ │    EJS      │ │    │ │  Express.js │ │    │ │   MongoDB   │ │\n│ │  Templates  │ │    │ │   Server    │ │    │ │   Database  │ │\n│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │\n│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │\n│ │  JavaScript │◄├────┤►│  Socket.IO  │ │    │ │ Cloudflare  │ │\n│ │   Modules   │ │    │ │  WebSocket  │ │    │ │     R2      │ │\n│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │\n│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │\n│ │   Webpack   │ │    │ │   REST API  │ │    │ │   PayPal    │ │\n│ │   Bundler   │ │    │ │  Endpoints  │ │    │ │   Gateway   │ │\n│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n### **Real-Time Communication (Socket.IO)**\n| Event Type          | Direction    | Purpose                           |\n|-------------------- |------------- |---------------------------------- |\n| `reservation:update`| Server→Client| Court availability changes       |\n| `post:new`          | Server→Client| New community posts              |\n| `comment:new`       | Server→Client| New comments on posts            |\n| `payment:status`    | Server→Client| PayPal transaction updates       |\n| `notification:new`  | Server→Client| System notifications             |\n| `user:connect`      | Client→Server| User authentication for socket   |\n| `user:disconnect`   | Client→Server| Clean up user socket connections |\n\n### **Database Schema Overview**\n```\nUsers ←→ Courts (1:Many - Court Ownership)\nUsers ←→ Reservations (1:Many - User Bookings)\nCourts ←→ Reservations (1:Many - Court Bookings)\nUsers ←→ Posts (1:Many - User Posts)\nPosts ←→ Comments (1:Many - Post Comments)\nUsers ←→ Orders (1:Many - User Purchases)\nProducts ←→ Orders (Many:Many - Order Items)\nUsers ←→ Notifications (1:Many - User Alerts)\n```\n\n## 🛠️ Tech Stack\n\n### **Backend Technologies**\n- **Runtime**: Node.js 18+\n- **Framework**: Express.js 4.21.0\n- **Database**: MongoDB with Mongoose ODM\n- **Authentication**: JWT + OTP via email\n- **Real-time**: Socket.IO for WebSocket connections\n- **File Storage**: Cloudflare R2 (S3-compatible)\n- **Payments**: PayPal REST SDK with webhooks\n- **Email**: Nodemailer (Gmail App Password integration)\n- **Security**: Helmet.js, CORS, Rate Limiting\n\n### **Frontend Technologies**\n- **Template Engine**: EJS (Embedded JavaScript)\n- **Build Tool**: Webpack 5 with custom configuration\n- **Styling**: Modern CSS with responsive design\n- **JavaScript**: ES6+ with modular architecture\n- **Maps**: Leaflet.js for interactive mapping\n- **Icons**: Font Awesome for UI elements\n\n### **Development Tools**\n- **Process Manager**: Nodemon for development\n- **Code Quality**: ESLint and Prettier (configured)\n- **Build Optimization**: Terser, CSS Minimizer\n- **File Management**: Webpack plugins for asset handling\n- **Environment**: dotenv for configuration management\n\n### **Infrastructure \u0026 DevOps**\n- **Hosting**: Evennode (Node.js hosting platform)\n- **Database**: MongoDB Atlas (cloud database)\n- **CDN**: Cloudflare R2 for static assets\n- **Email Service**: Gmail (App Password based)\n- **Monitoring**: Morgan for HTTP request logging\n- **Process Management**: PM2-ready with graceful shutdown\n\n## 📁 Project Structure\n\n```\nbataan-badminton-portal/\n├── 📁 build/                          # Webpack build output\n│   ├── *.html                         # Generated HTML pages\n│   ├── *.js                          # Bundled JavaScript files\n│   └── *.css                         # Compiled CSS files\n├── 📁 certs/                          # SSL certificates\n├── 📁 client/                         # Frontend source code\n│   ├── 📁 css/                        # Stylesheets\n│   │   ├── components/                # Component-specific styles\n│   │   └── pages/                     # Page-specific styles\n│   ├── 📁 html/                       # Static HTML files\n│   ├── 📁 js/                         # Frontend JavaScript\n│   │   ├── components/                # Reusable UI components\n│   │   ├── pages/                     # Page-specific scripts\n│   │   └── utils/                     # Frontend utilities\n│   ├── 📁 utils/                      # Client-side utilities\n│   └── 📁 views/                      # EJS templates\n│       ├── template.ejs               # Base template\n│       ├── error.ejs                  # Error page template\n│       └── 📁 partials/               # Reusable template parts\n├── 📁 config/                         # Configuration files\n│   ├── checkEnvVars.js               # Environment validation\n│   ├── commonConfig.js               # Shared configuration\n│   ├── db.js                         # Database connection\n│   ├── development.js                # Development settings\n│   └── production.js                 # Production settings\n├── 📁 public/                         # Static assets\n├── 📁 scripts/                        # Build and utility scripts\n├── 📁 src/                            # Backend source code\n│   ├── 📁 controllers/                # Request handlers\n│   │   ├── authController.js          # Authentication logic\n│   │   └── userController.js          # User management\n│   ├── 📁 middleware/                 # Express middleware\n│   │   ├── authJwt.js                # JWT validation\n│   │   ├── rateLimiter.js            # Rate limiting\n│   │   └── roleChecker.js            # Role-based access\n│   ├── 📁 models/                     # Mongoose schemas\n│   │   ├── User.js                   # User model\n│   │   ├── Court.js                  # Court model\n│   │   ├── Reservation.js            # Reservation model\n│   │   ├── Post.js                   # Community post model\n│   │   ├── Product.js                # E-commerce product model\n│   │   └── ...                       # Other models\n│   ├── 📁 routes/                     # API route definitions\n│   │   ├── authRoutes.js             # Authentication endpoints\n│   │   ├── userRoutes.js             # User-related endpoints\n│   │   ├── indexRoutes.js            # Public endpoints\n│   │   └── superadminRoutes.js       # Admin endpoints\n│   ├── 📁 services/                   # Business logic services\n│   │   ├── emailService.js           # Email notifications\n│   │   ├── paypalService.js          # Payment processing\n│   │   └── r2Service.js              # File storage\n│   ├── 📁 utils/                      # Utility functions\n│   │   ├── generateToken.js          # JWT token generation\n│   │   ├── fileUpload.js             # File handling\n│   │   ├── courtAvailability.js      # Booking logic\n│   │   ├── reservationCleanup.js     # Cron job handlers\n│   │   └── ...                       # Other utilities\n│   └── 📁 validation/                 # Input validation schemas\n├── 📄 server.js                       # Application entry point\n├── 📄 package.json                    # Project dependencies\n├── 📄 webpack.config.js               # Webpack configuration\n├── 📄 nodemon.json                    # Nodemon settings\n├── 📄 vercel.json                     # Vercel deployment config\n└── 📄 README.md                       # Project documentation\n```\n\n### **Key Directories Explained**\n\n- **`/src`**: Backend application code following MVC pattern\n- **`/client`**: Frontend assets and templates (EJS-based)\n- **`/config`**: Environment-specific configuration files\n- **`/build`**: Webpack-generated production assets\n- **`/public`**: Static files served directly by Express\n\n## ⚙️ Configuration\n\n### **Environment Variables (.env)**\n\nThe backend validates required variables at startup via `config/checkEnvVars.js`. All of the following are **required** for the app to boot (use placeholder values for features you are not yet using):\n\n#### **Required Core / Infrastructure**\n```env\n# Server\nPORT=3000\nHOST_DEV=127.0.0.1\nHOST_PROD=0.0.0.0\nNODE_ENV=development            # development | production\nDISABLE_SECURITY=false          # set to true ONLY for local relaxed security\n\n# Frontend origin (used in email links, redirects)\nFRONTEND_URL=http://localhost:3000\n\n# JWT / Auth\nJWT_SECRET=your_access_token_secret\nJWT_REFRESH_SECRET=your_refresh_token_secret\n\n# File limits\nMAX_FILE_SIZE=10485760          # 10MB (used in config for express-fileupload)\n```\n\n#### **Database (MongoDB)**\n```env\nDB_URI=mongodb://localhost:27017/bataan-badminton-portal\nDB_USERNAME=                      # (optional if not required locally)\nDB_PASSWORD=                      # (optional if not required locally)\n```\n\nFor Atlas example:\n```env\nDB_URI=mongodb+srv://cluster-host/dbname?retryWrites=true\u0026w=majority\nDB_USERNAME=atlasUser\nDB_PASSWORD=strongPasswordHere\n```\n\n#### **Gmail (App Password Based)**\nThis project uses Nodemailer with Gmail's built-in service shortcut. Only two env vars are required:\n\n```env\nEMAIL_USER=your_email@gmail.com\nEMAIL_PASSWORD=your_16_char_app_password   # Generated from Google App Passwords\n```\n\nApp Password creation: enable 2FA → App Passwords → Select \"Mail\" + device → copy 16‑char password.\nNo host/port variables are needed (do not add SMTP_* variables).\n\n#### **PayPal Integration**\n```env\nPAYPAL_CLIENT_ID=your_paypal_client_id\nPAYPAL_SECRET_KEY=your_paypal_client_secret\nPAYPAL_WEBHOOK_ID=your_webhook_id_for_signature_verification\n```\n\n#### **Cloudflare R2 (Custom Worker Gateway)**\n```env\nR2_AUTH_KEY=your_custom_auth_key\nR2_UPLOAD_URL=https://r2-api.example.workers.dev\n```\n\n#### **Optional (Tokens Expiry Override)**\nThese are not validated by `checkEnvVars.js` but you can document them if you implement dynamic expiry config.\n```env\n# Not currently enforced by startup script, but used in logic if referenced\nJWT_EXPIRES_IN=7d\nJWT_REFRESH_EXPIRES_IN=30d\n```\n\n#### **PayPal Integration**\n```env\n# PayPal API Credentials\nPAYPAL_CLIENT_ID=your_paypal_client_id\nPAYPAL_CLIENT_SECRET=your_paypal_client_secret\nPAYPAL_WEBHOOK_ID=your_webhook_id_for_signature_verification\n\n# PayPal Environment (sandbox/live)\nPAYPAL_MODE=sandbox\n```\n\n#### **Cloudflare R2 Storage**\n```env\n# R2 Storage Configuration\nR2_AUTH_KEY=ely\nR2_UPLOAD_URL=https://r2-api.mayor.workers.dev\n```\n\n#### **File Upload Settings**\n```env\n# File Upload Limits (in bytes)\nMAX_FILE_SIZE=10485760  # 10MB\n```\n\n\n### **Configuration Files**\n\nThe application uses a hierarchical configuration system:\n\n- **`config/commonConfig.js`**: Shared settings across environments\n- **`config/development.js`**: Development-specific overrides\n- **`config/production.js`**: Production-specific settings\n- **`config/checkEnvVars.js`**: Validates required environment variables\n\n### **Development vs Production**\n\n#### **Development Settings**\n- Detailed error messages\n- No SSL certificate validation\n- PayPal sandbox mode\n- Reduced security measures for easier debugging\n\n#### **Production Settings**\n- Error messages hidden from users\n- SSL certificate validation enforced\n- PayPal live mode\n- Enhanced security features enabled\n- Compression and caching optimized\n\n## 🚀 Quick Start\n\n### **Prerequisites**\n- Node.js 18+ and npm\n- MongoDB (local or MongoDB Atlas)\n- Git for version control\n\n### **Installation**\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/elyeandre/bataan-badminton-portal.git\n   cd bataan-badminton-portal\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Set up environment variables**\n   ```bash\n   # Copy environment template\n   cp .env.example .env\n   \n   # Edit .env with your configurations\n   # See Configuration section below for details\n   ```\n\n4. **Build the application**\n   ```bash\n   npm run build\n   ```\n\n5. **Start the development server**\n   ```bash\n   npm run devStart\n   ```\n\n6. **Create superadmin account (optional)**\n   ```bash\n   npm run create-superadmin\n   ```\n\n### **Available Scripts**\n\n| Script | Description |\n|--------|-------------|\n| `npm start` | Build and start production server |\n| `npm run dev` | Start webpack dev server |\n| `npm run devStart` | Start server with nodemon (development) |\n| `npm run build` | Build production assets |\n| `npm run watch` | Watch for changes and rebuild |\n| `npm run clean-build` | Clean build directory before building |\n| `npm run deploy` | Deploy to Evennode hosting |\n| `npm run create-superadmin` | Create superadmin account |\n\n### **Development Workflow**\n\n1. **Start development environment**\n   ```bash\n   npm run devStart\n   ```\n\n2. **Access the application**\n   - Frontend: `http://localhost:3000`\n   - Auth endpoints: `http://localhost:3000/auth/*`\n   - User endpoints: `http://localhost:3000/user/*`\n   - Superadmin endpoints: `http://localhost:3000/superadmin/*`\n\n## 📱 Usage Guide\n\n### **User Registration \u0026 Authentication**\n\n1. **Account Creation**\n   - Navigate to `/signup`\n   - Fill in personal information (name, email, username)\n   - Choose role: Player, Coach, or Court Owner\n   - Submit registration form\n   - Check email for OTP verification code\n   - Enter OTP to activate account\n\n2. **Login Process**\n   - Visit `/signin`\n   - Enter username/email and password\n   - Select appropriate role\n   - System generates JWT token for session management\n\n3. **Password Reset**\n   - Click \"Forgot Password\" on login page\n   - Enter email address\n   - Check email for reset link with OTP\n   - Follow link and enter new password\n\n### **Court Management (Court Owners)**\n\n1. **Register Your Court**\n   - Complete court owner verification\n   - Fill in business details (name, contact, hours)\n   - Upload court images and documents\n   - Set pricing and availability\n\n2. **Manage Reservations**\n   - View incoming booking requests\n   - Approve or decline reservations\n   - Set special rates for events\n   - Track payment status\n\n3. **Post Announcements**\n   - Create court-specific announcements\n   - Schedule maintenance windows\n   - Promote special events\n\n### **Making Reservations (Players/Coaches)**\n\n1. **Find Courts**\n   - Browse available courts on map\n   - Filter by location, price, amenities\n   - View court details and images\n   - Check real-time availability\n\n2. **Book a Court**\n   - Select desired date and time slot\n   - Choose number of courts needed\n   - Review booking details and pricing\n   - Proceed to PayPal payment\n   - Receive confirmation email\n\n3. **Manage Bookings**\n   - View upcoming reservations\n   - Cancel bookings (subject to policy)\n   - Track payment status\n   - Download booking receipts\n\n### **Community Features**\n\n1. **Social Feed**\n   - Create posts with text and images\n   - Use hashtags to categorize content\n   - Like and comment on posts\n   - Follow trending hashtags\n\n2. **Events \u0026 Tournaments**\n   - Browse upcoming events\n   - Register for tournaments\n   - Pay entry fees via PayPal\n   - Receive event updates\n\n### **E-commerce (Shopping)**\n\n1. **Browse Products**\n   - View badminton equipment catalog\n   - Filter by category, price, brand\n   - Read product descriptions and reviews\n\n2. **Purchase Items**\n   - Add items to shopping cart\n   - Review cart and apply discounts\n   - Proceed to PayPal checkout\n   - Track order status\n\n### **Notifications \u0026 Communication**\n\n- **Real-time Notifications**: Instant alerts for reservations, comments, payments\n- **Email Updates**: Comprehensive email notifications for all major actions\n- **In-app Messaging**: Direct communication between users\n- **System Announcements**: Important platform updates and news\n\n## 🔒 Security Features\n\n### **Authentication \u0026 Authorization**\n- **JWT Tokens**: Secure, stateless authentication with configurable expiration\n- **Token Blacklisting**: Immediate token invalidation on logout\n- **Role-Based Access Control**: Granular permissions for different user types\n- **OTP Verification**: Two-factor authentication via email for critical actions\n- **Password Security**: Bcrypt hashing with salt rounds, minimum complexity requirements\n\n### **Data Protection**\n- **Input Validation**: Comprehensive validation using Joi schemas\n- **SQL Injection Prevention**: MongoDB native protection + input sanitization\n- **XSS Protection**: HTML sanitization for user-generated content\n- **CSRF Protection**: Token-based protection for state-changing operations\n- **File Upload Security**: Type validation, size limits\n\n### **Network Security**\n- **HTTPS Enforcement**: SSL/TLS encryption for all communications\n- **CORS Configuration**: Controlled cross-origin resource sharing\n- **Rate Limiting**: Prevent brute force attacks and API abuse\n- **Helmet.js**: Security headers for common vulnerabilities\n- **Content Security Policy**: XSS protection through CSP headers\n\n### **Infrastructure Security**\n- **Environment Variables**: Sensitive data stored securely\n- **Database Security**: MongoDB connection with authentication\n- **File Storage**: Secure Cloudflare R2 integration with access controls\n- **Error Handling**: No sensitive information in error responses\n- **Logging**: Comprehensive audit trails without sensitive data\n\n\n## 🌐 API Documentation\n\n\u003e Base URL examples:\n\u003e Development: `http://localhost:3000`\n\u003e Production: `https://your-domain.com`\n\nAll JSON responses follow the structure:\n```\n{\n   success: boolean,\n   message?: string,\n   data?: any,\n   code?: number,\n   errors?: object\n}\n```\n\nAuthentication uses Bearer JWT in the `Authorization` header unless marked Public. Some routes also set HTTP-only cookies for refresh tokens.\n\n### Legend\n| Symbol | Meaning |\n|--------|---------|\n| 🔓 | Public (no auth) |\n| 🔐 | Requires JWT |\n| 👤 | Player or Coach role |\n| 🛠️ | Admin role |\n| 👑 | Superadmin role |\n| 🏛️ | Any authenticated role |\n\n### Rate Limiting\n| Scope | Limit | Window |\n|-------|-------|--------|\n| Auth sensitive (login / forgot / reset) | 15 req | 15 min |\n| General (most data/file endpoints) | 100 req | 15 min |\n\nExceeding limits returns HTTP 429 with a JSON error.\n\n---\n### 1. Authentication (`/auth`)\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /auth/register | Register user (player/coach/owner) |\n| POST | /auth/register/courts | Court registration submission |\n| POST | /auth/login | Login (returns access + refresh) |\n| POST | /auth/logout | Logout / blacklist token |\n| POST | /auth/refresh | Refresh access token |\n| POST | /auth/verify | Verify email / OTP |\n| DELETE | /auth/delete | Delete own account |\n| POST | /auth/forgot-password | Request password reset (rate-limited) |\n| POST | /auth/reset-password | Complete password reset |\n\n---\n### 2. Public \u0026 Utility\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /ping | Authenticated health check |\n| GET | /data/:filename | Secure file access (permissions) |\n| GET | /user/data/:filename | Same as above (legacy alias) |\n| POST | /paypal-webhook | PayPal webhook (signature verified) |\n| GET | /register | Registration HTML |\n| GET | /register/courts | Court registration HTML |\n| GET | /reset-password | Reset-password HTML (token) |\n| GET | /verification | Email verification HTML (token) |\n| GET | /login | Login HTML |\n\n---\n### 3. Superadmin (`/superadmin`)\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /superadmin/dashboard | Platform overview |\n| PATCH | /superadmin/court/:action/:courtId | Approve / reject court |\n| GET | /superadmin/users | List users |\n| GET | /superadmin/users/search | Search users |\n| GET | /superadmin/users/:userId | Get user info |\n| PUT | /superadmin/users/:userId | Update user |\n| DELETE | /superadmin/users/:userId | Delete user |\n| GET | /superadmin/courts | List court owners |\n| GET | /superadmin/court-details/:courtId | Court detail |\n\n---\n### 4. User Core (`/user`)\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /user/me | Current user profile |\n| GET | /user/get-user/:id | Get user by ID |\n| PUT | /user/update | Update player/coach profile |\n| GET | /user/courts | List courts |\n| GET | /user/court/:id | Court details |\n| PUT | /user/admin/settings/update-court-info | Update court owner info |\n\n---\n### 5. Reservations \u0026 Availability\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /user/availability | Availability (query params) |\n| POST | /user/reserve | Create reservation |\n| GET | /user/reservations | User reservations |\n| POST | /user/reservations/cancel | Cancel reservation |\n| GET | /user/admin/reservations | Owner reservations |\n| PATCH | /user/admin/reservations/:id/bill-status | Update billing status |\n| GET | /user/court-reservation | Reservation HTML UI |\n\n---\n### 6. Announcements / Events / Tournaments\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /user/admin/announcement | Create announcement |\n| PUT | /user/admin/announcement/:announcementId | Update announcement |\n| DELETE | /user/admin/announcement/:announcementId | Delete announcement |\n| POST | /user/admin/event | Create event |\n| PUT | /user/admin/event/:eventId | Update event |\n| DELETE | /user/admin/event/:eventId | Delete event |\n| POST | /user/admin/tournament | Create tournament |\n| GET | /user/admin/events/participants | Event participants |\n| GET | /user/admin/get-event/:id | Get event |\n| POST | /user/admin/membership | Create membership plan |\n\nPlayer / Coach Event Interaction:\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /user/event/check-joined/:eventId | Check join status |\n| POST | /user/event/join | Join event |\n| GET | /user/events/ongoing | Ongoing events |\n| GET | /user/confirm-event-payment | Event payment confirmation |\n\n---\n### 7. Community / Social\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /user/posts | User feed |\n| GET | /user/admin/posts | Admin posts view |\n| POST | /user/community/post | Create post |\n| GET | /user/community/posts | List posts |\n| DELETE | /user/community/posts/:postId | Delete post |\n| PUT | /user/community/posts/:postId | Edit post |\n| POST | /user/community/posts/:postId/like | Like post |\n| DELETE | /user/community.posts/:postId/like | Remove like |\n| POST | /user/community/posts/:postId/comment | Add comment |\n| PUT | /user/community/posts/:postId/comment/:commentId | Edit comment |\n| POST | /user/community/posts/:postId/comment/:commentId/like | Like comment |\n| DELETE | /user/community/posts/:postId/comment/:commentId/like | Unlike comment |\n| DELETE | /user/community/posts/:postId/:commentId/comment | Delete comment |\n| GET | /user/community/posts/:postId/comments | Post comments |\n| GET | /user/community/posts/popular | Popular hashtags |\n| GET | /user/community/posts/:hashtag | Posts by hashtag |\n| GET | /user/announcements | Announcements HTML |\n\n---\n### 8. Products \u0026 Orders\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /user/products | Create product |\n| PUT | /user/products/:id | Update product |\n| DELETE | /user/products/:id | Delete product |\n| GET | /user/get-products | List products |\n| GET | /user/get-products/:id | Product detail |\n| GET | /user/cart | User cart |\n| POST | /user/cart/add | Add to cart |\n| PATCH | /user/cart/update-quantity | Update quantity |\n| DELETE | /user/cart/remove/:productId | Remove from cart |\n| DELETE | /user/cart/clear | Clear cart |\n| GET | /user/products/checkout | Checkout HTML |\n| POST | /user/products/orders/create | Create order |\n| GET | /user/products/orders/confirm | Confirm order |\n| GET | /user/products/orders/status | Order status |\n| GET | /user/products/orders/paid | Paid orders |\n| GET | /user/products/order-list | Orders HTML |\n| GET | /user/admin/products/get-orders | Owner order list |\n\n---\n### 9. Memberships \u0026 Subscriptions\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /user/admin/membership/create | Create membership |\n| GET | /user/admin/membership/get-memberships | Owner memberships |\n| DELETE | /user/admin/membership/:membershipId | Delete membership |\n| PUT | /user/admin/membership/:membershipId | Update membership |\n| GET | /user/admin/membership/:subscriptionId/subscribers | Membership subscribers |\n| DELETE | /user/admin/membership/:subscriptionId/remove/:userId | Remove subscriber |\n| GET | /user/membership/get-memberships | All membership cards |\n| POST | /user/membership/subscribe/:membershipId | Subscribe |\n| POST | /user/membership/cancel/:membershipId | Cancel subscription |\n| GET | /user/membership/get-subscriptions | Active subscriptions |\n| GET | /user/membership/confirm | Confirm payment |\n| POST | /user/feedback/submit | Submit feedback |\n\n---\n### 10. Notifications\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /user/notifications | List notifications |\n| PATCH | /user/notification/mark-read/:notificationId | Mark one read |\n| PATCH | /user/notifications/mark-read | Mark all read |\n| DELETE | /user/notifications/clear | Clear notifications |\n| POST | /user/notifications/test | Test notification |\n\n---\n### 11. Billing \u0026 Payments\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /user/check-payment-status | Generic payment status |\n| GET | /user/membership/confirm | Membership payment confirmation |\n| GET | /user/confirm-event-payment | Event payment confirmation |\n\n---\n### 12. WebSocket Events\nClient connects with:\n```javascript\nconst socket = io(BASE_URL, { query: { userId: currentUserId } });\n\nsocket.on('welcome', (msg) =\u003e console.log(msg));\nsocket.on('notification', (notif) =\u003e {/* display */});\n// Additional custom events are emitted server-side when announcements, reservations, posts, etc. change.\n```\n\nCommon emitted events (inferred):\n- `notification` – new notification object\n- Court / reservation update events (emitted through reservation logic) – implement client listeners as needed.\n\n---\n### Error Handling\nErrors return JSON:\n```\n{\n   success: false,\n   code: 400,\n   message: \"Validation failed\",\n   errors: { field: \"reason\" }\n}\n```\n\n### Pagination \u0026 Filtering (Recommended)\nSome list endpoints (posts, products, reservations) support / should support query params:\n`?page=1\u0026limit=20\u0026sort=createdAt:desc\u0026search=term`\nIf not yet implemented, consider adding consistent middleware for pagination.\n\n### Authentication Notes\nInclude header:\n`Authorization: Bearer \u003caccess_token\u003e`\n\nAccess token rotation strategy: use `/auth/refresh` with refresh cookie before expiry; logout invalidates tokens via blacklist.\n\n---\nFuture Improvement Ideas:\n1. Generate OpenAPI (Swagger) specification automatically.\n2. Add pagination parameters documentation per endpoint.\n3. Provide example request/response bodies per main resource.\n4. Introduce versioning (`/v1`) for future breaking changes.\n5. Add HATEOAS-style links for navigable APIs.\n\n\n## 🚀 Deployment\n\n### **Deployment Platforms**\n\n#### **Evennode (Current)**\n```bash\n# Deploy to Evennode\nnpm run deploy\n\n# Or manually:\ngit push evennode main\n```\n\n#### **Self-Hosted VPS (PM2)**\nUse this approach when deploying on your own Linux VPS (Ubuntu/Debian/CentOS, etc.).\n\n```bash\n# 1. SSH into your server\nssh user@your_server_ip\n\n# 2. (Recommended) Install Node.js via nvm (if Node 18+ not installed)\ncurl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash\nsource ~/.nvm/nvm.sh\nnvm install 18\n\n# 3. Clone the repository\ngit clone https://github.com/elyeandre/bataan-badminton-portal.git\ncd bataan-badminton-portal\n\n# 4. Set environment variables\ncp .env.example .env\nnano .env   # (or vim) then configure production values\n\n# 5. Install dependencies\nnpm install\n\n# 6. Build production assets\nnpm run build\n\n# 7. Install pm2 globally (if not yet)\nnpm install -g pm2\n\n# 8. Start the app with PM2 (uses your package.json start script)\npm2 start npm --name \"bataan-badminton-demo\" -- run start\n\n# 9. (Optional) Auto-start on reboot\npm2 startup systemd\npm2 save\n\n# 10. View logs\npm2 logs bataan-badminton-demo\n\n# 11. Updating a new release later\ngit pull\nnpm install\nnpm run build\npm2 restart bataan-badminton-demo\n```\n\nKey PM2 commands:\n| Command | Purpose |\n|---------|---------|\n| `pm2 list` | List processes |\n| `pm2 restart \u003cname\u003e` | Restart app |\n| `pm2 stop \u003cname\u003e` | Stop app |\n| `pm2 delete \u003cname\u003e` | Remove process |\n| `pm2 logs \u003cname\u003e` | Stream logs |\n| `pm2 save` | Save current process list |\n\n### **Environment-Specific Configurations**\n\n#### **Production Environment Variables**\n```env\nNODE_ENV=production\nPORT=443\nMONGO_URI=mongodb+srv://prod-user:password@cluster.mongodb.net/badminton-prod\nJWT_SECRET=ultra_secure_production_secret_key\nPAYPAL_MODE=live\nDISABLE_SECURITY=false\n```\n\n## 🤝 Contributing\n\nWe welcome contributions from the community! Here's how you can help improve the Bataan Badminton Management Portal:\n\n### **Getting Started**\n\n1. **Fork the Repository**\n   ```bash\n   # Click the \"Fork\" button on GitHub\n   # Then clone your fork\n   git clone https://github.com/elyeandre/bataan-badminton-portal.git\n   cd bataan-badminton-portal\n   ```\n\n2. **Set Up Development Environment**\n   ```bash\n   npm install\n   cp .env.example .env\n   # Configure your .env file\n   npm run devStart\n   ```\n\n3. **Create a Feature Branch**\n   ```bash\n   git checkout -b feature/your-feature-name\n   # or\n   git checkout -b bugfix/issue-description\n   ```\n\n### **Development Guidelines**\n\n#### **Code Style**\n- Follow existing code formatting and naming conventions\n- Use meaningful variable and function names\n- Add comments for complex logic\n- Keep functions small and focused on single responsibility\n\n#### **Commit Messages**\nUse conventional commit format:\n```\ntype(scope): description\n\nfeat(auth): add email verification for new users\nfix(reservation): resolve double booking issue\ndocs(readme): update installation instructions\nstyle(css): improve mobile responsiveness\nrefactor(api): optimize database queries\ntest(auth): add unit tests for login validation\n```\n\n#### **Pull Request Process**\n\n1. **Before Submitting**\n   - [ ] Test your changes thoroughly\n   - [ ] Run linting and formatting tools\n   - [ ] Update documentation if needed\n   - [ ] Add/update tests for new features\n   - [ ] Ensure all tests pass\n\n2. **PR Description Template**\n   ```markdown\n   ## Description\n   Brief description of changes\n\n   ## Type of Change\n   - [ ] Bug fix\n   - [ ] New feature\n   - [ ] Breaking change\n   - [ ] Documentation update\n\n   ## Testing\n   - [ ] Unit tests added/updated\n   - [ ] Integration tests pass\n   - [ ] Manual testing completed\n\n   ## Screenshots (if applicable)\n   Add screenshots for UI changes\n   ```\n\n3. **Review Process**\n   - PRs require at least one review\n   - Address reviewer feedback promptly\n   - Keep PRs focused and reasonably sized\n   - Squash commits before merging\n\n### **Types of Contributions**\n\n#### **🐛 Bug Reports**\n- Use GitHub Issues with bug report template\n- Include steps to reproduce\n- Provide system information\n- Add screenshots/logs if helpful\n\n#### **💡 Feature Requests**\n- Open GitHub Issue with feature request template\n- Describe the problem and proposed solution\n- Consider impact on existing functionality\n- Discuss with maintainers before implementing large features\n\n#### **📖 Documentation**\n- Improve README, API docs, or code comments\n- Fix typos and grammatical errors\n- Add examples and usage guides\n- Translate documentation to other languages\n\n\u003c!-- Testing section intentionally removed per project scope --\u003e\n\n### **Community Guidelines**\n\n- Be respectful and inclusive\n- Follow the code of conduct\n- Help newcomers get started\n- Share knowledge and best practices\n- Participate in discussions constructively\n\n### **Recognition**\n\nContributors will be recognized in:\n- GitHub contributors list\n- Changelog for releases\n- Special mentions in documentation\n- Community spotlight features\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n### **MIT License Summary**\n- ✅ Commercial use allowed\n- ✅ Modification allowed\n- ✅ Distribution allowed\n- ✅ Private use allowed\n- ❌ No liability\n- ❌ No warranty\n- ❗ License and copyright notice required\n\n```\nCopyright (c) 2025 Bataan Badminton Management Portal Contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n\u003c!-- Acknowledgements section removed per request --\u003e\n\n---\n\n**🏸 Built with ❤️ for the Bataan Badminton Community**\n\n*\"Connecting players, courts, and communities through technology\"*\n\n---\n\n\n*Last updated: September 23, 2025 (env vars \u0026 email config updated)*\n\n[made-with-javascript]: http://forthebadge.com/images/badges/made-with-javascript.svg\n[built-with-love]: https://forthebadge.com/images/badges/built-with-love.svg\n[forthebadge-url]: http://forthebadge.com\n[contributors-shield]: https://img.shields.io/github/contributors/elyeandre/bataan-badminton-portal.svg?style=for-the-badge\n[contributors-url]: https://github.com/elyeandre/bataan-badminton-portal/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/elyeandre/bataan-badminton-portal.svg?style=for-the-badge\n[forks-url]: https://github.com/elyeandre/bataan-badminton-portal/network/members\n[stars-shield]: https://img.shields.io/github/stars/elyeandre/bataan-badminton-portal.svg?style=for-the-badge\n[stars-url]: https://github.com/elyeandre/bataan-badminton-portal/stargazers\n[issues-shield]: https://img.shields.io/github/issues/elyeandre/bataan-badminton-portal.svg?style=for-the-badge\n[issues-url]: https://github.com/elyeandre/bataan-badminton-portal","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felyeandre%2Fbataan-badminton-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felyeandre%2Fbataan-badminton-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felyeandre%2Fbataan-badminton-portal/lists"}