Assemble

A comprehensive campus management platform for the German University in Cairo (GUC)

Assemble is a full-stack web application designed to streamline campus activities, event management, facility bookings, and vendor marketplace operations. It serves as a unified platform for students, faculty, staff, and vendors to interact with various campus services including workshops, conferences, trips, court reservations, fitness sessions, and vendor marketplace participation.

---

📋 Table of Contents

• Motivation
• Build Status
• Code Style
• Screenshots
• Tech/Framework Used
• Features
• Code Examples
• Installation
• API Reference
• Tests
• How to Use
• Contribute
• Credits
• License

---

🎯 Motivation

The German University in Cairo needed a centralized platform to manage the diverse range of campus activities and services. Traditional methods of managing events, registrations, facility bookings, and vendor participation were fragmented and inefficient. Assemble was created to:

• Centralize Campus Operations: Provide a single platform for all campus activities, reducing administrative overhead and improving user experience
• Streamline Event Management: Enable efficient creation, approval, and management of workshops, conferences, trips, and bazaars
• Facilitate Vendor Participation: Simplify vendor applications for bazaars and platform booth setups with automated approval workflows
• Enhance User Experience: Offer seamless registration, payment processing, and facility booking capabilities
• Improve Communication: Implement notification systems to keep all stakeholders informed about events and updates

---

🏗️ Build Status

Current Version: 1.0.0

Status: ✅ Active Development

• Backend API: Fully functional with comprehensive endpoints
• Frontend Application: Complete with modern UI/UX
• Database: MongoDB schema implemented and documented
• Payment Integration: Stripe integration complete
• Email Services: Automated email notifications operational
• Authentication: JWT-based authentication system active

Known Issues / Limitations

• Test suite is not yet implemented (see Tests section)
• Some advanced features may require additional configuration
• Production deployment configurations need environment-specific setup

---

📐 Code Style

This project follows consistent coding standards:

• TypeScript: Strict type checking enabled
• ESLint: Configured for both frontend and backend
• Naming Conventions:
  • Files: camelCase (e.g., event.controller.ts)
  • Classes: PascalCase (e.g., EventController)
  • Variables/Functions: camelCase (e.g., getAllEvents)
• Architecture: Layered architecture (Models → Services → Controllers → Routes)
• Documentation: JSDoc comments for API endpoints (Swagger integration)

Code Style Tools

• Backend: TypeScript with ESLint
• Frontend: Next.js ESLint configuration
• Formatting: Prettier (recommended)

---

📸 Screenshots

Landing Page

Welcome page with feature overview and user role information

Gym Sessions

Role-based dashboards for different user types

Event Management

Intuitive event creation and browsing interface

Vendor Requests Portal

Streamlined vendor application and management

Wallet Interface

Secure Stripe payment integration

Court Booking

Real-time availability and reservation system

Ratings

Real-time availability and reservation system

Note: To add screenshots, place image files in the docs/screenshots/ directory and update the paths above. Supported formats: PNG, JPG, GIF, SVG.

---

🛠️ Tech/Framework Used

Backend

Technology	Version	Purpose
Node.js	Latest LTS	Runtime environment
Express.js	^5.1.0	Web framework
TypeScript	^5.9.3	Type-safe JavaScript
MongoDB	Latest	Database
Mongoose	^8.19.1	ODM for MongoDB
JWT	^9.0.2	Authentication
bcryptjs	^3.0.2	Password hashing
Stripe	^19.1.0	Payment processing
Nodemailer	^7.0.7	Email services
Multer	^2.0.2	File uploads
Joi	^18.0.1	Input validation
Swagger	Latest	API documentation
ExcelJS	^4.4.0	Excel report generation
qrcode	^1.5.4	QR code generation
Helmet	^8.1.0	Security headers
CORS	^2.8.5	Cross-origin resource sharing

Frontend

Technology	Version	Purpose
Next.js	15.5.4	React framework
React	19.1.0	UI library
TypeScript	5.9.3	Type-safe JavaScript
Tailwind CSS	^4	Utility-first CSS
shadcn/ui	Latest	Component library
Axios	^1.12.2	HTTP client
Stripe.js	^8.5.2	Payment integration
Lucide React	^0.544.0	Icons
Zod	^4.1.12	Schema validation
date-fns	^4.1.0	Date utilities

Development Tools

• Concurrently: Run multiple npm scripts simultaneously
• Nodemon: Auto-restart backend during development
• ts-node: TypeScript execution for Node.js

---

✨ Features

Core Features

1. Event Management

• Create and manage workshops, conferences, trips, bazaars, and platform booths
• Event approval workflows for Events Office
• Search, filter, and sort events by multiple criteria
• Event archiving and status management
• Role-based event restrictions

2. User Registration & Authentication

• Multi-role user system (Students, Staff, TAs, Professors, Admins, Event Office, Vendors)
• Email verification system
• GUC email validation for campus users
• JWT-based session management
• Password reset functionality

3. Vendor Marketplace

• Vendor application system for bazaars and platform booths
• Document upload and verification (tax cards, logos, IDs)
• Platform booth slot selection with multi-slot booking
• Automated approval/rejection workflows
• QR code generation for vendor attendees

4. Payment & Wallet System

• Stripe integration for credit/debit card payments
• In-app wallet system for users
• Payment receipts via email
• Refund processing (2 weeks before event)
• Vendor participation fee management

5. Facility Booking

• Court Reservations: Basketball, tennis, and football court bookings
• Real-time availability checking
• Reservation management and cancellation
• Gym Sessions: Group fitness session registration
• Capacity management and attendance tracking

6. Workshop Management

• Faculty-led workshop creation
• Certificate generation and email delivery
• Attendance tracking
• Workshop-specific registration workflows

7. Notification System

• Email notifications for events, approvals, payments
• In-app notification preferences
• Automated reminders and updates
• Status change notifications

8. Admin Dashboard

• User management and role assignment
• Event approval and management
• Vendor request processing
• Report generation (Excel export)
• System analytics

9. Polls & Feedback

• Event polling system
• Rating and comment functionality
• User feedback collection

10. Favorites System

• Save favorite events for quick access
• Personalized event recommendations

---

💻 Code Examples

Backend API Example

Register for an Event:

// POST /registrations
{
  "eventId": "507f1f77bcf86cd799439011",
  "paymentMethod": "wallet",
  "specialRequirements": "Vegetarian meal preference"
}

Create an Event (Events Office):

// POST /events
{
  "name": "Spring Bazaar 2025",
  "eventType": "bazaar",
  "shortDescription": "Annual spring shopping event",
  "location": "GUC Main Campus - Plaza",
  "startDateTime": "2025-04-20T10:00:00Z",
  "endDateTime": "2025-04-22T18:00:00Z",
  "registrationDeadline": "2025-04-15T23:59:59Z"
}

Vendor Application:

// POST /vendor/apply-bazaar
{
  "eventId": "507f1f77bcf86cd799439011",
  "boothSize": "4x4",
  "attendees": [
    {
      "name": "John Doe",
      "email": "john@vendor.com"
    }
  ]
}

Frontend Example

Event Registration Component:

// Using Axios to register for an event
const registerForEvent = async (eventId: string) => {
  try {
    const response = await axios.post('/registrations', {
      eventId,
      paymentMethod: 'wallet'
    });
    console.log('Registration successful:', response.data);
  } catch (error) {
    console.error('Registration failed:', error);
  }
};

---

📦 Installation

Prerequisites

Before installing, ensure you have the following software installed:

• Node.js: v16 or higher (Download)
• MongoDB: v5.0 or higher (Download or use MongoDB Atlas)
• npm: Comes with Node.js (or use yarn)
• Git: For cloning the repository (Download)

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/Advanced-Computer-Lab-2025/Assemble.git
cd Assemble

2. Install Dependencies

Install dependencies for root, backend, and frontend:

npm run install:all

This command will:

• Install root dependencies
• Install backend dependencies
• Install frontend dependencies

3. Set Up Environment Variables

Backend Configuration:

cd backend
copy .env.example .env

Edit backend/.env with your configuration:

# Server Configuration
PORT=5000
FRONTEND_URL=http://localhost:3000

# Database
MONGODB_URI=mongodb://localhost:27017/assemble
# Or for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/assemble

# JWT Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRES_IN=7d

# Email Configuration (Nodemailer)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password
EMAIL_FROM=noreply@assemble.guc.edu.eg

# Stripe Payment
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

# File Upload
MAX_FILE_SIZE=5242880
UPLOAD_PATH=./uploads

Frontend Configuration:

cd ../frontend
copy .env.example .env.local

Edit frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key

4. Set Up MongoDB

Option A: Local MongoDB

1. Install MongoDB from mongodb.com
2. Start MongoDB service:

   # Windows
   net start MongoDB
   
   # macOS/Linux
   sudo systemctl start mongod

Option B: MongoDB Atlas (Cloud)

1. Create a free account at MongoDB Atlas
2. Create a new cluster
3. Get your connection string and add it to backend/.env

5. Run the Application

Development Mode (Both Frontend & Backend):

# From root directory
npm run dev

This will start:

• Backend: http://localhost:5000
• Frontend: http://localhost:3000

Run Individually:

# Backend only
npm run dev:backend

# Frontend only
npm run dev:frontend

6. Seed Sample Data (Optional)

To populate the database with sample data for testing:

# Make a POST request to /seed endpoint
curl -X POST http://localhost:5000/seed

This creates:

• Sample student and vendor accounts
• Sample events (bazaars, booths)
• Sample vendor requests
• Platform booth slots

Test Credentials:

• Student: test@student.guc.edu.eg / TestPass123!
• Vendor: vendor@company.com / VendorPass123!

---

📚 API Reference

Base URL

• Development: http://localhost:5000
• Production: (Configure in environment variables)

Authentication

Most endpoints require authentication via JWT token. Include the token in the request:

Authorization: Bearer <your-jwt-token>

Or via cookie (automatically handled by the frontend).

API Endpoints

Authentication

• POST /auth/register - User registration
• POST /auth/login - User login
• POST /auth/logout - User logout
• POST /auth/verify-email - Email verification
• POST /auth/forgot-password - Password reset request
• POST /auth/reset-password - Reset password

Events

• GET /events/all - Get all events (with search, filter, sort, pagination)
• GET /events/:id - Get event details
• POST /events - Create event (Events Office only)
• PUT /events/:id - Update event (Events Office only)
• DELETE /events/:id - Delete event (Admin/Events Office)

Registrations

• POST /registrations - Register for an event
• GET /registrations - Get user's registrations
• DELETE /registrations/:id - Cancel registration

Payments

• POST /payments/create-payment-intent - Create Stripe payment intent
• POST /payments/confirm - Confirm payment
• GET /payments - Get payment history
• GET /payments/wallet - Get wallet balance

Vendors

• POST /vendor/apply-bazaar - Apply for bazaar participation
• POST /vendor/apply-platform-booth - Apply for platform booth
• GET /vendor/requests - Get vendor requests
• POST /vendor/upload-documents - Upload vendor documents

Courts

• GET /courts - Get all courts with availability
• POST /courts/reserve - Reserve a court

Workshops

• GET /workshops - Get all workshops
• POST /workshops - Create workshop (Professors only)
• GET /workshops/:id/certificate - Download certificate

Admin

• GET /admin/users - Get all users
• POST /admin/assign-role - Assign user role
• GET /admin/vendor-requests - Get all vendor requests
• POST /admin/approve-vendor - Approve vendor request
• POST /admin/reject-vendor - Reject vendor request

Notifications

• GET /notifications - Get user notifications
• PUT /notifications/:id/read - Mark notification as read
• PUT /notifications/preferences - Update notification preferences

Reports

• GET /reports/events - Export events report (Excel)
• GET /reports/registrations - Export registrations report

API Documentation

Interactive API documentation is available via Swagger UI when the backend is running:

Swagger UI: http://localhost:5000/docs

Response Format

Success Response:

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": { ... }
}

Error Response:

{
  "status": "error",
  "message": "Error description",
  "error": "Detailed error information"
}

---

📖 How to Use

For Students

1. Sign Up: Create an account using your GUC email (@student.guc.edu.eg)
2. Verify Email: Check your email and click the verification link
3. Browse Events: Explore workshops, trips, conferences, and bazaars
4. Register: Register for events you're interested in
5. Make Payment: Pay using Stripe or your wallet balance
6. Book Facilities: Reserve courts or join gym sessions
7. View Certificates: Download workshop certificates after completion

For Professors

1. Get Account: Request account creation from Admin
2. Create Workshops: Create and manage your workshops
3. Track Attendance: Monitor workshop registrations
4. Generate Certificates: Automatically generate certificates for participants

For Staff/TA

1. Get Account: Request account creation from Admin
2. Organize Events: Create and manage campus events
3. Manage Registrations: View and manage event registrations

For Event Office

1. Get Account: Admin creates your account
2. Create Events: Create bazaars, trips, conferences
3. Approve Events: Review and approve event submissions
4. Manage Vendors: Process vendor applications
5. Generate Reports: Export event and registration reports

For Vendors

1. Sign Up: Create vendor account with company email
2. Upload Documents: Upload tax card and company logo
3. Apply for Events: Apply to participate in bazaars or set up platform booths
4. Select Slots: Choose booth locations for platform booths
5. Make Payment: Pay participation fees upon approval
6. Manage Attendees: Upload attendee IDs and manage participation

For Admins

1. Manage Users: Create accounts, assign roles, manage user status
2. Approve Vendors: Review and approve/reject vendor applications
3. System Management: Access admin dashboard for system-wide operations
4. Generate Reports: Export comprehensive system reports

---

🤝 Contribute

We welcome contributions! Here's how you can help:

Contribution Guidelines

1. Fork the Repository: Create your own fork of the project
2. Create a Branch: Create a feature branch from main

   git checkout -b feature/your-feature-name

3. Follow Code Style: Adhere to the project's code style and conventions
4. Write Clean Code: Write readable, well-documented code
5. Test Your Changes: Ensure your changes work correctly
6. Update Documentation: Update relevant documentation
7. Commit Changes: Write clear, descriptive commit messages

   git commit -m "Add feature: description of changes"

8. Push and Create Pull Request: Push to your fork and create a PR

Development Workflow

1. Create feature branch from main
2. Make changes in appropriate directory (backend/frontend)
3. Test locally using npm run dev
4. Ensure no linter errors
5. Commit with descriptive messages
6. Push and create Pull Request

Code Review Process

• All PRs require review before merging
• Ensure all checks pass (linting, type checking)
• Address review comments promptly

Reporting Issues

If you find a bug or have a feature request:

1. Check existing issues to avoid duplicates
2. Create a new issue with:
   • Clear description
   • Steps to reproduce (for bugs)
   • Expected vs actual behavior
   • Environment details

---

🙏 Credits

Development Team

Assemble

Technologies & Libraries

• Next.js: nextjs.org - React framework
• Express.js: expressjs.com - Web framework
• MongoDB: mongodb.com - Database
• Stripe: stripe.com - Payment processing
• Tailwind CSS: tailwindcss.com - CSS framework
• shadcn/ui: ui.shadcn.com - Component library
• TypeScript: typescriptlang.org - Type-safe JavaScript

Inspiration & Resources

• University campus management systems
• Modern event management platforms
• E-commerce marketplace patterns

---

📄 License

This project is licensed under the ISC License.

ISC License

Copyright (c) 2025, Advanced Computer Lab 2025

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

---

📞 Support

For questions, issues, or contributions:

• GitHub Issues: Create an issue
• Repository: GitHub Repository

---

📝 Version History

Version 1.0.0 (Current)

• Initial release
• Core event management functionality
• User authentication and authorization
• Vendor marketplace system
• Payment integration (Stripe + Wallet)
• Facility booking (Courts & Gym)
• Workshop management with certificates
• Notification system
• Admin dashboard
• API documentation (Swagger)

---

Last Updated: 2025

Maintained by: Advanced Computer Lab 2025