Skip to content
/ Mon_9am_Team_04 Public

Comp1100 Group Project By Nathan Perrier, Joshua Borg, Bastien Walter, Hunter Saviour and Hanseong Kang

3 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

NathanPerrier/Mon_9am_Team_04

BranchesTags

Repository files navigation

Full Stack Application - Framework7 + Django

A modern web application with Framework7 frontend, Event Organizer Dashboard, and Django REST API backend.

🚀 Quick Start

Prerequisites

  • Python 3.8+
  • Node.js 14+
  • npm or yarn

Environment Setup

  1. Clone the repository
git clone https://github.com/NathanPerrier/Mon_9am_Team_04
cd Mon_9am_Team_04
  1. Set up environment variables
# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration
# Make sure to change DJANGO_SECRET_KEY in production!

🎯 Run the app

# Make the script executable (first time only)
chmod +x start-all.sh

# Run both frontend and backend
./start-all.sh

# Or use Python script (cross-platform)
python3 start-all.py

# Alternative: Run individually
cd code/frontend/campuslink && npm start  # CampusLink app (port 3000)
cd code/frontend/event-organiser-dashboard && npm start  # Organizer dashboard (port 3001)
cd code/backend && python manage.py runserver  # Backend API (port 8000)

📦 Manual Installation

Backend Setup (Django)

# Navigate to backend directory
cd code/backend

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run migrations
python manage.py makemigrations
python manage.py migrate

# Initialize cache table (required for UQ Maps integration)
python manage.py createcachetable

# Create superuser (optional, for admin access)
python create_superuser.py
# Or manually:
python manage.py createsuperuser

# Start Django server
python manage.py runserver

Loading Example Data

To populate the database with example data for testing and development, use the provided initial_data.json file located in code/backend/backend/. This file contains sample data for all database tables, including users, events, bookings, comments, and associated images for events.

# Ensure migrations are applied:
   cd code/backend
   python manage.py makemigrations
   python manage.py migrate

# Load the example data
   python manage.py loaddata initial_data.json

# Create super user (avoid UNIQUE constraint error)
   python manage.py createsuperuser

To verify the data, access the Django Admin panel at http://localhost:8000/admin to confirm that the example data (users, events, bookings, comments, etc.) has been successfully imported. Note: Event images referenced in initial_data.json are included as URLs or base64-encoded data. Ensure any external image URLs are accessible or replace them with local paths if needed.

Frontend Setup (Framework7 - CampusLink)

# Navigate to CampusLink frontend directory
cd code/frontend/campuslink

# Install dependencies
npm install

# Start development server
npm start

# Build for production
npm run build

🔗 Access Points

📁 Project Structure

Mon_9am_Team_04/
├── .env                    # Environment variables (create from .env.example)
├── .env.example           # Example environment configuration
├── .gitignore            # Git ignore rules
├── CLAUDE.md             # Claude Code assistant instructions
├── README.md             # This file
├── start.sh              # Unix/Linux startup script
├── start.py              # Python startup script (cross-platform)
├── .github/
│   ├── workflows/        # GitHub Actions CI/CD
│   ├── ISSUE_TEMPLATE/   # Issue templates
│   └── pull_request_template.md
└── code/
    ├── backend/          # Django REST API backend
    │   ├── manage.py     # Django management script
    │   ├── backend/      # Django project settings
    │   │   ├── settings.py
    │   │   ├── urls.py
    │   │   └── wsgi.py
    │   ├── api/          # Main API application
    │   │   ├── models.py           # Data models (Event, Booking, UserProfile, etc.)
    │   │   ├── views.py            # API views and authentication
    │   │   ├── serializers.py      # DRF serializers
    │   │   ├── urls.py             # API URL routing
    │   │   ├── admin.py            # Django admin configuration
    │   │   ├── uq_maps_service.py  # UQ Maps integration service
    │   │   └── management/         # Custom management commands
    │   │       └── commands/
    │   │           └── refresh_uq_maps_cache.py
    │   ├── db.sqlite3    # SQLite database (development)
    │   ├── refresh_cache_cron.sh  # Cron script for cache refresh
    │   └── venv/         # Python virtual environment
    └── frontend/         # Frontend applications
        ├── campuslink/   # Framework7 SPA frontend
        └── event-organiser-dashboard/ # Flowbite admin dashboard
        ├── package.json  # Node.js dependencies
        ├── vite.config.js # Vite build configuration
        ├── src/
        │   ├── index.html     # Entry HTML
        │   ├── app.f7         # Main app component
        │   ├── js/
        │   │   ├── app.js     # Framework7 initialization
        │   │   ├── routes.js  # Frontend routing
        │   │   ├── store.js   # State management
        │   │   └── services/
        │   │       └── api.js # Backend API client
        │   ├── pages/         # Page components (.f7 files)
        │   │   ├── home.f7
        │   │   ├── login.f7
        │   │   ├── register.f7
        │   │   └── settings.f7
        │   └── css/           # Stylesheets
        ├── www/              # Production build output
        └── cordova/          # Mobile app builds

🔐 Environment Variables

The application uses a single .env file in the root directory for both frontend and backend configuration. See .env.example for all available options:

Key Environment Variables:

  • DJANGO_SECRET_KEY: Django secret key (⚠️ change in production!)
  • DJANGO_DEBUG: Set to False in production
  • DJANGO_ALLOWED_HOSTS: Comma-separated list of allowed hosts
  • API_BASE_URL: Backend API URL for Django backend
  • VITE_API_BASE_URL: Frontend API URL (must match API_BASE_URL for mobile apps)
  • CORS_ALLOWED_ORIGINS: Allowed CORS origins for web requests
  • CORS_ALLOW_ALL_ORIGINS_MOBILE: Set to True for mobile app development
  • JWT_ACCESS_TOKEN_LIFETIME: JWT token lifetime in minutes

Mobile Development Configuration:

For iOS devices and Android emulators, you need to configure the API URLs properly:

  1. Find your machine's IP address:

    ifconfig | grep "inet " | grep -v 127.0.0.1  # macOS/Linux
ipconfig  # Windows

  2. Update .env file with your IP:

    # For iOS devices - replace 192.168.1.100 with your machine's IP
API_BASE_URL=http://192.168.1.100:8000/api
VITE_API_BASE_URL=http://192.168.1.100:8000/api

# For Android emulator (special IP that routes to host)
# API_BASE_URL=http://10.0.2.2:8000/api
# VITE_API_BASE_URL=http://10.0.2.2:8000/api

  3. Update CORS settings for mobile:

    CORS_ALLOW_ALL_ORIGINS_MOBILE=True
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:5174,http://192.168.1.100:5174,file://,capacitor://localhost,ionic://localhost,app://localhost,null

Note: The VITE_API_BASE_URL is required for the frontend to properly load the API URL from environment variables. Both API_BASE_URL and VITE_API_BASE_URL should have the same value.

🔧 Development Workflow

Starting Fresh

  1. Clone the repository
  2. Copy .env.example to .env and configure
  3. Run ./start.sh or python3 start.py
  4. Access the application at http://localhost:3000

After Pulling Changes

  1. Check for new dependencies:
    • Backend: pip install -r requirements.txt (if exists)
    • Frontend: cd code/frontend && npm install
  2. Run migrations: cd code/backend && python manage.py migrate
  3. Start the application

🛠️ Available Scripts

Backend

  • python manage.py runserver - Start development server
  • python manage.py makemigrations - Create migrations
  • python manage.py migrate - Apply migrations
  • python manage.py createsuperuser - Create admin user
  • python manage.py test - Run tests

Frontend (CampusLink)

  • cd code/frontend/campuslink && npm start - Start CampusLink app (port 3000)

Frontend (Event Organizer Dashboard)

  • cd code/frontend/event-organiser-dashboard && npm start - Start dashboard (port 3001)
  • npm run build - Build for production (creates optimized bundle)
  • npm run dev - Start development server (alias for npm start)
  • npm test - Run tests (currently not configured)
  • npm run build-cordova - Build for mobile platforms
  • npm run build-cordova-ios - Build for iOS
  • npm run build-cordova-android - Build for Android

📱 Mobile App Development

Prerequisites for Mobile Development

Common Requirements

# Install Node.js 14+ and npm
# Install Cordova globally
npm install -g cordova

# Navigate to CampusLink frontend directory
cd code/frontend/campuslink

iOS Requirements (macOS only)

  • Operating System: macOS 10.15 or later
  • Xcode: Version 13+ (from App Store)
  • Xcode Command Line Tools: 
    xcode-select --install
  • CocoaPods (optional but recommended): 
    sudo gem install cocoapods
  • iOS Simulator or physical iOS device
  • Apple Developer Account (free for testing, $99/year for App Store)

Android Requirements (Windows/macOS/Linux)

  • Java JDK: Version 11 or later 
    # macOS
brew install openjdk@11

# Ubuntu/Debian
sudo apt-get install openjdk-11-jdk

# Windows - download from Oracle or OpenJDK
  • Android Studio: Download from developer.android.com
  • Android SDK: Install via Android Studio
  • Environment Variables (add to ~/.bashrc, ~/.zshrc, or Windows Environment Variables): 
    export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
export ANDROID_HOME=$HOME/Android/Sdk           # Linux
# Windows: C:\Users\[username]\AppData\Local\Android\Sdk

export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/build-tools/[version]

🍎 iOS Build Instructions

# Navigate to CampusLink frontend directory
cd code/frontend/campuslink

# Install dependencies (first time)
npm install

# Build for iOS (from campuslink directory)
cd code/frontend/campuslink
npm run build-cordova-ios

# Alternative: Step-by-step
cd cordova
npx cordova platform add ios  # Only if not already added
npx cordova build ios

# Run on iOS Simulator
npx cordova emulate ios

# Run on specific simulator
npx cordova emulate ios --target="iPhone-14"

# Run on connected iOS device (requires npm install -g ios-deploy)
npx cordova run ios --device

# Open in Xcode for advanced configuration
open platforms/ios/Campuslink.xcworkspace

iOS Configuration & Setup

Environment Variables

Create a .env file in the project root with your Apple Developer credentials:

# iOS Development Configuration
IOS_DEVELOPMENT_TEAM=YOUR_TEAM_ID  # Found in Xcode → Settings → Accounts
APP_BUNDLE_ID=com.campuslink.app   # Your app's bundle identifier
Building for iOS Device
# Using the build script (recommended - uses .env variables)
cd code/frontend/cordova
./build-ios.sh

# Or run directly on device
./run-ios-device.sh
Device Setup Requirements
  1. Register your device:
    • Connect iPhone via USB
    • Open Xcode → Window → Devices and Simulators
    • Device will auto-register with your team
  2. Enable Developer Mode (iOS 16+):
    • Settings → Privacy & Security → Developer Mode → ON
  3. Trust the app (first install):
    • Settings → General → VPN & Device Management → Developer App → Trust
Custom App Icons

The project includes custom Campuslink icons. To update them:

cd code/frontend
# Replace public/icons/campuslink-icon.png with your logo
./create-campuslink-icon.sh  # Regenerates all icon sizes

iOS Distribution

  1. Open Xcode project: 
    open cordova/platforms/ios/Campuslink.xcworkspace
  2. Configure signing:
    • Team ID is read from .env file
    • Bundle ID: com.campuslink.app (or customize in .env)
  3. Build for App Store:
    • Product → Archive
    • Distribute App → App Store Connect

🤖 Android Build Instructions

# Navigate to CampusLink frontend directory
cd code/frontend/campuslink

# Install dependencies (first time)
npm install

# Build for Android
npm run build-cordova-android

# Alternative: Step-by-step
cd cordova
npx cordova platform add android  # Only if not already added
npx cordova build android

# Run on Android Emulator
npx cordova emulate android

# List available Android Virtual Devices (AVDs)
npx cordova run android --list

# Run on specific emulator
npx cordova emulate android --target="Pixel_4_API_30"

# Run on connected Android device (USB debugging enabled)
npx cordova run android --device

# Build release APK (unsigned)
npx cordova build android --release

# Build release Bundle for Play Store
cd platforms/android
./gradlew bundleRelease

Android Distribution

  1. Generate signed APK/AAB: 
    # Generate keystore (first time only)
keytool -genkey -v -keystore campuslink.keystore -alias campuslink -keyalg RSA -keysize 2048 -validity 10000

# Build signed APK
npx cordova build android --release -- --keystore=campuslink.keystore --alias=campuslink
  2. The signed APK will be at: platforms/android/app/build/outputs/apk/release/
  3. The AAB bundle will be at: platforms/android/app/build/outputs/bundle/release/

📱 Platform-Specific Features

Updating App Icons and Splash Screens

# Icons are located in:
# iOS: cordova/res/icon/ios/
# Android: cordova/res/icon/android/

# Splash screens are located in:
# iOS: cordova/res/screen/ios/
# Android: cordova/res/screen/android/

# After updating images, rebuild:
npm run build-cordova-ios    # or
npm run build-cordova-android

Configuring App Details

Edit cordova/config.xml:

<widget id="com.yourcompany.campuslink" version="1.0.0">
    <name>CampusLink</name>
    <description>Your app description</description>
    <author email="your@email.com">Your Name</author>
</widget>

🔧 Mobile Development Troubleshooting

iOS Issues

  • "No profiles for 'xxx' were found": Configure signing in Xcode
  • "Command failed with exit code 65": Clean build: cd cordova/platforms/ios && xcodebuild clean
  • Simulator not starting: Reset simulator: Device → Erase All Content and Settings

Android Issues

  • "SDK location not found": Create local.properties in cordova/platforms/android/ with: 
    sdk.dir=/path/to/Android/Sdk
  • "Gradle build failed": Clean build: cd cordova/platforms/android && ./gradlew clean
  • Device not recognized: Enable USB debugging in Developer Options

Common Issues

  • White screen on app launch: Check console for errors using:
    • iOS: Safari → Develop → Simulator
    • Android: Chrome → chrome://inspect
  • CORS errors: Ensure backend allows mobile app origin
  • Build errors after update: Remove and re-add platform: 
    npx cordova platform remove ios/android
npx cordova platform add ios/android

🔄 API Endpoints

Authentication

  • POST /api/auth/register/ - User registration (with role selection)
  • POST /api/auth/login/ - User login (returns JWT tokens)
  • POST /api/auth/logout/ - User logout
  • GET /api/auth/user/ - Get current user details
  • GET/PUT/PATCH /api/auth/profile/ - User profile management

Events

  • GET /api/events/ - List all events (with pagination, search, filters)
  • POST /api/events/ - Create new event (organizers only)
  • GET /api/events/{id}/ - Get event details
  • PUT/PATCH /api/events/{id}/ - Update event (organizer only)
  • DELETE /api/events/{id}/ - Delete event (organizer only)
  • POST /api/events/{id}/save_event/ - Save/bookmark an event
  • DELETE /api/events/{id}/unsave_event/ - Unsave an event
  • GET /api/events/saved/ - Get user's saved events
  • GET /api/events/my_events/ - Get events created by user

Event Filters (Query Parameters)

  • ?search= - Search in name, description, location, tags
  • ?start_date=YYYY-MM-DD - Events after this date
  • ?end_date=YYYY-MM-DD - Events before this date
  • ?min_price=0 - Minimum ticket price
  • ?max_price=100 - Maximum ticket price
  • ?tags=music,sports - Filter by tags
  • ?organizer={user_id} - Filter by organizer

Bookings

  • GET /api/bookings/ - List user's bookings
  • POST /api/bookings/ - Create new booking
  • GET /api/bookings/{id}/ - Get booking details
  • POST /api/bookings/{id}/cancel/ - Cancel a booking

Comments

  • GET /api/comments/?event={id} - Get event comments
  • POST /api/comments/ - Post a comment
  • PUT/PATCH /api/comments/{id}/ - Edit comment
  • DELETE /api/comments/{id}/ - Delete comment
  • POST /api/comments/{id}/like/ - Like a comment
  • DELETE /api/comments/{id}/unlike/ - Unlike a comment

Social Features

  • GET /api/friends/ - List friends/followers
  • POST /api/friends/ - Follow a user
  • DELETE /api/friends/unfollow/ - Unfollow a user
  • GET /api/users/search/?q=query - Search users

UQ Maps Integration

  • GET /api/uq-maps/campuses/ - List all UQ campuses
  • GET /api/uq-maps/buildings/ - Get buildings for default campus (St Lucia)
  • GET /api/uq-maps/buildings/{campus}/ - Get buildings for specific campus
  • GET /api/uq-maps/building/{campus}/{building_id}/ - Get building details
  • GET /api/uq-maps/search/?q={query}&campus={campus} - Search locations
  • GET /api/uq-maps/parking/ or /api/uq-maps/parking/{campus}/ - Get parking availability
  • GET /api/uq-maps/computers/ or /api/uq-maps/computers/{campus}/ - Get computer lab availability
  • GET /api/uq-maps/library/ or /api/uq-maps/library/{campus}/ - Get library occupancy
  • GET /api/uq-maps/parse-room/?code={room_code} - Parse UQ room code format
  • GET /api/uq-maps/build-url/ - Build UQ Maps URL with parameters
  • POST /api/uq-maps/refresh-cache/ - Refresh cache (admin only)

For detailed UQ Maps API documentation, see Documents/UQ_MAPS_API_README.md

🧪 Testing

Backend Testing

cd code/backend
python manage.py test

Frontend Testing

Frontend testing is currently not configured. Consider adding Jest or Vitest for unit testing.

🚀 Deployment

Production Checklist

  1. Environment Variables

    • Set DJANGO_DEBUG=False
    • Generate new DJANGO_SECRET_KEY
    • Update DJANGO_ALLOWED_HOSTS
    • Set NODE_ENV=production

  2. Database

    • Configure production database (PostgreSQL recommended)
    • Update DJANGO_DATABASE_URL

  3. Static Files

    python manage.py collectstatic

  4. Security

    • Enable HTTPS
    • Configure proper CORS origins
    • Set secure headers

🐛 Troubleshooting

Common Issues

  1. Blank page in frontend

    • Check browser console for errors
    • Ensure backend is running
    • Verify CORS settings

  2. API connection errors

    • Check if Django server is running on port 8000
    • Verify proxy settings in webpack.config.js
    • Check CORS_ALLOWED_ORIGINS in .env

  3. Authentication issues

    • Ensure JWT settings are configured
    • Check token expiration times
    • Verify API endpoints

🔄 Git Workflow

  • Main branch: main - Production-ready code
  • Development branch: dev - Active development
  • Feature branches: Create from dev for new features
  • Pull requests: Use the template in .github/pull_request_template.md

📄 License

This project is part of COMP1100 coursework at the University of Queensland.

🙏 Acknowledgments

  • Framework7 for the mobile framework
  • Django REST Framework for the API
  • All contributors and team members

The Team 👅👅🫦🫦

Nathan Perrier, 49684388, NathanPerrier, s49684388@uq.edu.au
Joshua Borg, 49135684, ijlb, joshua.borg@student.uq.edu.au
Bastien Walter, 48909589, bastienwalter-jpg. s4890958@uq.edu.au
Hunter Siviour, 49216912, HuntSiv6, s4921691@uq.edu.au
Hanseong Kang, 48911078, Hanslmnop, hanseong.kang@student.uq.edu.au

About

Comp1100 Group Project By Nathan Perrier, Joshua Borg, Bastien Walter, Hunter Saviour and Hanseong Kang

Topics

mvp uq comp1100

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors 5

Languages