🏛️ The-Good-Men

A comprehensive event management platform for the German University in Cairo (GUC) that handles workshops, trips, conferences, bazaars, vendor applications, court reservations, gym sessions, and more.

📋 Table of Contents

About the Project
Motivation
Features
Screenshots
Tech Stack
Prerequisites
Installation
Configuration
How the Website Works
API Reference
Project Structure
Usage Examples
Testing
Contributing
Credits
License

🎯 About the Project

The-Good-Men is a full-stack web application designed to streamline all aspects of university event management and campus facility reservations. It provides a centralized platform where students, staff, vendors, and administrators can interact seamlessly.

Key Highlights

✅ Role-Based Access Control - 7 distinct user types with tailored permissions
✅ Event Management - Complete lifecycle management for Workshops, Trips, Conferences, and Bazaars
✅ Payment Integration - Secure Stripe payment processing with wallet support
✅ Vendor System - Booth applications, approvals, and loyalty program management
✅ Campus Facilities - Court reservations and gym session registrations
✅ Real-time Notifications - In-app and email notifications for all important events
✅ Analytics & Reports - Comprehensive attendee and revenue reporting

💡 Motivation

This project was created to solve the challenges faced by GUC in managing:

Event Registration: Manual registration processes were time-consuming and error-prone
Vendor Management: Lack of centralized system for vendor applications and booth management
Payment Processing: Need for secure, automated payment handling
Campus Facilities: Difficulty in managing court and gym reservations
Communication: Inefficient notification systems for event updates

The platform aims to digitize and automate these processes, providing a seamless experience for all stakeholders while maintaining security and proper access controls.

✨ Features

For Students

📅 Register for events (Workshops, Trips, Conferences)
🏀 Reserve sports courts
💪 Register for gym sessions
⭐ Favorite events for quick access
⭐ Rate and review attended events
💰 Manage wallet for payments
🎁 Access loyalty program discounts

For Staff/TA/Professors

📅 Register for events
💪 Register for gym sessions
⭐ Rate events
🎁 Access loyalty program

For Vendors

🏪 Apply for platform booths (permanent spaces)
🏪 Apply for bazaar booths (temporary event spaces)
💳 Pay for approved booths online
📊 View and manage applications
🎁 Apply for GUC Loyalty Program
❌ Cancel unpaid applications

For Events Office

➕ Create and manage all event types
✅ Approve/reject workshop proposals
🏪 Manage vendor booth applications
💰 Set registration prices
📱 Generate QR codes for visitors
🏋️ Create gym sessions
🏀 Manage sports courts
📊 Create polls for vendor selection
📈 View reports and analytics

For Admins

👥 Approve/reject user registrations
🚫 Block/unblock users
➕ Create admin and events office accounts
📊 Generate comprehensive reports
📄 View all documents
🎁 Manage loyalty program applications

📸 Screenshots

Note: Screenshots will be added here to showcase the application's UI and features.

Dashboard Views

Student Dashboard
Vendor Dashboard
Events Office Dashboard
Admin Dashboard

Key Features

Event Registration Flow
Payment Processing
Vendor Application Process
Court Reservation System
Gym Session Registration

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
React	18.3.1	UI Library
React Router	7.9.3	Client-side Routing
Axios	1.12.2	HTTP Client
Stripe.js	8.3.0	Payment Processing
Context API	-	State Management

Backend

Technology	Version	Purpose
Node.js	≥14.0.0	Runtime Environment
Express.js	5.1.0	Web Framework
MongoDB	-	Database
Mongoose	8.19.1	ODM
JWT	9.0.2	Authentication
Stripe	19.3.0	Payment Processing
Nodemailer	7.0.6	Email Service
QRCode	1.5.4	QR Code Generation
XLSX	0.18.5	Excel Export

📦 Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v14.0.0 or higher) - Download
MongoDB (local installation or cloud instance) - Download or MongoDB Atlas
Git - Download
Stripe Account - Sign Up (for payment processing)
Email Service - SMTP credentials (Gmail, SendGrid, etc.)

System Requirements

Operating System: Windows, macOS, or Linux
RAM: Minimum 4GB (8GB recommended)
Disk Space: At least 500MB free space
Internet Connection: Required for package installation and API calls

🚀 Installation

Step 1: Clone the Repository

git clone <repository-url>
cd The-Good-Men

Step 2: Install Backend Dependencies

cd Backend
npm install

Step 3: Install Frontend Dependencies

cd ../frontend
npm install

Step 4: Configure Environment Variables

Create a .env file in the Backend/ directory:

# Database
MONGODB_URI=mongodb://localhost:27017/guc-events
# or for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/guc-events

# JWT Secret (generate a strong random string)
JWT_SECRET=your_super_secret_jwt_key_here

# Frontend URL
FRONTEND_URL=http://localhost:3000

# Stripe Configuration
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key

# Email Configuration (using Nodemailer)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_specific_password

# Server Port
PORT=5000

⚠️ Important: Never commit your .env file to version control. Add it to .gitignore.

Step 5: Start the Development Servers

Terminal 1 - Backend Server:

cd Backend
npm run dev

Server will run on http://localhost:5000

Terminal 2 - Frontend Server:

cd frontend
npm start

Application will open at http://localhost:3000

⚙️ Configuration

MongoDB Setup

Option 1: Local MongoDB

Install MongoDB from official website
Start MongoDB service
Update MONGODB_URI in .env to mongodb://localhost:27017/guc-events

Option 2: MongoDB Atlas (Cloud)

Create account at MongoDB Atlas
Create a new cluster
Get connection string
Update MONGODB_URI in .env with your connection string

Stripe Setup

Create account at Stripe
Get API keys from Dashboard → Developers → API keys
Add keys to .env file
Set up webhook endpoint: http://localhost:5000/api/payment/webhook
Add webhook secret to .env

Email Service Setup

Using Gmail:

Enable 2-factor authentication
Generate app-specific password
Use your Gmail address and app password in .env

Using SendGrid:

Create account at SendGrid
Generate API key
Update email configuration in Backend/src/services/emailService.js

🔧 How the Website Works

User Roles and Access Control

The system implements role-based access control (RBAC) with 7 distinct user types:

Role	Can Register for Events	Can Reserve Courts	Can Create Events	Can Manage Vendors	Can View Reports
Student	✅	✅	❌	❌	❌
Staff/TA/Professor	✅	❌ (Gym only)	❌	❌	❌
Vendor	❌	❌	❌	❌	❌
Events Office	❌	❌	✅	✅	✅
Admin	❌	❌	❌	✅	✅

Authentication Flow

graph TD
    A[User Signs Up] --> B{User Type?}
    B -->|Student| C[Email Verification]
    B -->|Staff/TA/Professor| C
    B -->|Vendor| D[Auto-Approved]
    C --> E{Email Verified?}
    E -->|Yes| F{Student?}
    E -->|No| G[Wait for Verification]
    F -->|Yes| H[Can Login]
    F -->|No| I[Wait for Admin Approval]
    D --> H
    I --> J[Admin Approves]
    J --> H

Event Management Lifecycle

Creation → Events Office or Professor creates event
Approval → (Workshops only) Events Office approves if created by Professor
Publishing → Event is published and visible to users
Registration → Users register (payment if required)
Execution → QR codes generated for entry
Post-Event → Users rate events, reports generated

Payment Flow

User Clicks Register
    ↓
Is Event Paid?
    ├─ Yes → Redirect to Payment Page
    │         ↓
    │    Stripe Payment Intent Created
    │         ↓
    │    User Enters Card Details
    │         ↓
    │    Payment Processed
    │         ↓
    │    Registration Confirmed
    │         ↓
    │    Email with QR Code Sent
    │
    └─ No → Registration Confirmed Immediately
              ↓
         Email with QR Code Sent

Vendor Application Process

Vendor Applies for Booth
    ↓
Application Status: Pending
    ↓
Events Office Reviews
    ├─ Approved → Payment Required
    │              ↓
    │         Payment Deadline Set
    │              ↓
    │         Vendor Pays → Booth Assigned
    │              ↓
    │         QR Codes Generated
    │
    └─ Rejected → Notification Sent

📚 API Reference

Authentication Endpoints

Method	Endpoint	Description	Auth Required
POST	`/api/users/signup`	Register new user	❌
POST	`/api/users/login`	User login	❌
POST	`/api/users/vendor/signup`	Register vendor	❌
GET	`/api/users/verify-email/:token`	Verify email	❌

Event Endpoints

Method	Endpoint	Description	Auth Required
GET	`/api/events`	Get all events	❌
POST	`/api/events/register`	Register for event	✅
GET	`/api/events/user/registered`	Get user's registered events	✅
POST	`/api/events/workshop`	Create workshop	✅ (Professor/Events Office)

Payment Endpoints

Method	Endpoint	Description	Auth Required
POST	`/api/payment/create-intent`	Create payment intent	✅
POST	`/api/payment/confirm`	Confirm payment	✅
POST	`/api/payment/webhook`	Stripe webhook	❌ (Stripe signature)

📖 Full API Documentation: For complete API reference, see API Documentation (if available)

📁 Project Structure

The-Good-Men/
│
├── Backend/
│   ├── src/
│   │   ├── controllers/      # Business logic
│   │   │   ├── AdminController.js
│   │   │   ├── EventsController.js
│   │   │   ├── PaymentController.js
│   │   │   └── ...
│   │   ├── models/           # Database schemas
│   │   │   ├── User.js
│   │   │   ├── Workshop.js
│   │   │   ├── Payment.js
│   │   │   └── ...
│   │   ├── routes/           # API routes
│   │   │   ├── UserRoutes.js
│   │   │   ├── AdminRoutes.js
│   │   │   └── ...
│   │   ├── services/         # External services
│   │   │   ├── emailService.js
│   │   │   └── tokenService.js
│   │   ├── auth.js           # Auth middleware
│   │   └── server.js         # Entry point
│   ├── package.json
│   └── .env                  # Environment variables
│
├── frontend/
│   ├── src/
│   │   ├── components/       # Reusable components
│   │   │   ├── layout/
│   │   │   └── ui/
│   │   ├── contexts/         # React contexts
│   │   │   ├── AuthContext.js
│   │   │   ├── ThemeContext.js
│   │   │   └── ...
│   │   ├── pages/            # Page components
│   │   │   ├── Login.js
│   │   │   ├── Student.js
│   │   │   └── ...
│   │   ├── lib/              # Utilities
│   │   │   └── api.js        # API client
│   │   ├── styles/           # CSS files
│   │   └── App.js            # Main app component
│   ├── package.json
│   └── public/
│
└── README.md

Key Files Explained

File	Purpose
`Backend/src/server.js`	Express server setup and route registration
`Backend/src/auth.js`	JWT authentication and authorization middleware
`frontend/src/App.js`	React app entry point, route definitions
`frontend/src/lib/api.js`	Centralized API client functions
`frontend/src/contexts/AuthContext.js`	Authentication state management

💻 Usage Examples

Registering for an Event

// Frontend API call
import { registerForEvent } from './lib/api'

const handleRegister = async (eventId, eventType) => {
  try {
    const response = await registerForEvent(eventId, eventType)
    if (response.requiresPayment) {
      // Redirect to payment page
      navigate(`/payment?type=${eventType}&id=${eventId}`)
    } else {
      // Registration successful
      alert('Registration successful!')
    }
  } catch (error) {
    console.error('Registration failed:', error)
  }
}

Creating a Workshop (Events Office)

// Backend Controller
const createWorkshop = async (req, res) => {
  try {
    const workshopData = {
      workshopName: req.body.workshopName,
      location: req.body.location,
      startDate: req.body.startDate,
      // ... other fields
    }
    
    const workshop = new Workshop(workshopData)
    await workshop.save()
    
    res.status(201).json({ 
      message: 'Workshop created successfully',
      workshop 
    })
  } catch (error) {
    res.status(500).json({ message: error.message })
  }
}

Processing Payment

// Stripe Payment Intent Creation
const createPaymentIntent = async (eventType, eventId, registrationData) => {
  const paymentIntent = await stripe.paymentIntents.create({
    amount: eventPrice * 100, // Convert to cents
    currency: 'egp',
    metadata: {
      eventType,
      eventId,
      userId: user.id
    }
  })
  
  return {
    clientSecret: paymentIntent.client_secret,
    paymentIntentId: paymentIntent.id
  }
}

🧪 Testing

Running Tests

# Backend tests (if available)
cd Backend
npm test

# Frontend tests
cd frontend
npm test

Manual Testing Checklist

Test Accounts

Note: Create test accounts for different roles to test all features

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Code Style

Use ESLint for code linting
Follow JavaScript Standard Style
Write meaningful commit messages
Add comments for complex logic
Update documentation for new features

Reporting Issues

When reporting issues, please include:

Description of the issue
Steps to reproduce
Expected behavior
Actual behavior
Screenshots (if applicable)
Environment details (OS, Node version, etc.)

🙏 Credits

German University in Cairo (GUC) - For the project requirements and inspiration
Stripe - Payment processing infrastructure
MongoDB - Database solution
React Team - Amazing UI library
Express.js - Robust web framework
All Contributors - Who helped improve this project

Resources Used

📄 License

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

📞 Support

For support, email support@guc-events.com or open an issue in the repository.

🔄 Version History

Version 1.0.0 (Current)

✅ Initial release
✅ User authentication and authorization
✅ Event management system
✅ Payment integration
✅ Vendor system
✅ Campus facilities management
✅ Reports and analytics

Made with ❤️ for GUC Community

⬆ Back to Top

Name		Name	Last commit message	Last commit date
.vscode		.vscode
Backend		Backend
frontend		frontend
.gitignore		.gitignore
ADMIN_LOYALTY_FEATURES.md		ADMIN_LOYALTY_FEATURES.md
COMPLETE_TESTING_GUIDE.md		COMPLETE_TESTING_GUIDE.md
HOW_TO_CHECK_YOUR_POINTS.md		HOW_TO_CHECK_YOUR_POINTS.md
HOW_TO_EARN_LOYALTY_POINTS.md		HOW_TO_EARN_LOYALTY_POINTS.md
LOYALTY_PROGRAM_FRONTEND_SUMMARY.md		LOYALTY_PROGRAM_FRONTEND_SUMMARY.md
README.md		README.md
STORE_MODULE_DOCUMENTATION.md		STORE_MODULE_DOCUMENTATION.md
package-lock.json		package-lock.json

Latest commit

History

Folders and files

Repository files navigation