ActivityPass (活动通)

AI-Assisted Student Activity Management Platform for Zhejiang Normal University (ZJNU)

A comprehensive, bilingual (English/中文) platform that streamlines extracurricular activity management for students and staff at Zhejiang Normal University.

Project Overview

ActivityPass revolutionizes how students discover, apply for, and participate in extracurricular activities while helping staff efficiently manage the entire process. The platform features AI-assisted eligibility checking, automated student provisioning, and comprehensive activity lifecycle management.

Core Features

Smart Student Management: Automatic student profile creation, eligibility verification, and participation tracking
Intelligent Scheduling: Conflict detection with class timetables, capacity management, and deadline enforcement
Bilingual Interface: Full English and Chinese language support with automatic detection
AI-Powered Eligibility: Rule-based and AI-assisted qualification scoring and recommendations
Comprehensive Analytics: Activity participation statistics, student engagement metrics, and reporting
Secure Authentication: JWT-based authentication with role-based access control
Responsive Design: Modern React interface with Tailwind CSS styling

Architecture

Tech Stack

Component	Technology	Purpose
Backend	Python 3.11+, Django 5.2+, Django REST Framework	API, business logic, data management
Frontend	React 18+, TypeScript, Vite, Tailwind CSS	User interface, responsive design
Database	MySQL 8.0+	Data persistence, complex queries
Authentication	JWT, Django Auth	Secure user sessions, role management
Internationalization	i18next, react-i18next	Bilingual content management
Maps	AMap API, Leaflet	Location services, activity venues
Testing	pytest, Vitest, React Testing Library	Quality assurance

Repository Structure

ActivityPass/
├── backend/                 # Django REST API
│   ├── ActivityPass/        # Django settings & configuration
│   ├── accounts/           # User management & authentication
│   ├── activities/         # Activity management & eligibility
│   ├── common/             # Shared utilities & helpers
│   └── requirements.txt    # Python dependencies
├── frontend/               # React TypeScript SPA
│   ├── public/             # Static assets
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/          # Page components
│   │   ├── locales/        # Translation files
│   │   └── types/          # TypeScript definitions
│   └── package.json        # Node.js dependencies
├── reference/              # Legacy scripts (development only)
├── scripts/                # Utility scripts
├── run_all.py             # Cross-platform setup automation
├── .env.example           # Environment configuration template
├── .gitignore            # Git ignore rules
└── README.md             # This file

Quick Start

Prerequisites

Python 3.11+ - Backend runtime
Node.js 18+ - Frontend tooling
MySQL 8.0+ - Database server
Git - Version control

One-Command Setup (Recommended)

The project includes an intelligent setup script that handles everything automatically:

# Clone and setup everything
git clone https://github.com/Al-rimi/ActivityPass.git
cd ActivityPass
python run_all.py

The script will:

Check for existing .env file or prompt for MySQL credentials
Create Python virtual environment
Install backend dependencies (shows package count)
Setup database and run migrations (detailed output)
Initialize application with sample data
Install frontend dependencies
Start both backend (port 8000) and frontend (port 3000) servers

Manual Setup

If you prefer manual setup:

1. Environment Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your MySQL credentials
# The setup script can do this for you if .env doesn't exist

2. Backend Setup

cd backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py init_app  # Creates admin user and seeds data (users, students, courses, and academic terms from course data)
python manage.py runserver

3. Frontend Setup

cd frontend
npm install
npm start

Configuration

Environment Variables

Create a .env file from .env.example:

# Django Configuration
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_DEBUG=true
DJANGO_ALLOWED_HOSTS=*

# Database Configuration
DB_ENGINE=mysql
DB_NAME=activitypass
DB_USER=your_mysql_username
DB_PASSWORD=your_mysql_password
DB_HOST=127.0.0.1
DB_PORT=3306

# CORS Configuration
CORS_ALLOW_ALL=true

# Frontend API Keys
VITE_AMAP_KEY=your_amap_api_key_here

Database Setup

CREATE DATABASE activitypass CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

API Documentation

Authentication Endpoints

POST /api/token/ - Obtain JWT access/refresh tokens
POST /api/token/refresh/ - Refresh access token
POST /api/token/verify/ - Verify token validity

Student Endpoints

GET /api/students/profile/ - Get current student profile
PUT /api/students/profile/ - Update student profile
GET /api/students/activities/ - List student's activities
POST /api/students/activities/{id}/apply/ - Apply for activity

Activity Endpoints

GET /api/activities/ - List all activities
GET /api/activities/{id}/ - Get activity details
POST /api/activities/ - Create new activity (staff only)
PUT /api/activities/{id}/ - Update activity (staff only)

Admin Endpoints

POST /api/admin/create-staff/ - Create staff account
POST /api/admin/reset-password/ - Reset user password
GET /api/admin/students/ - List all students
GET /api/admin/activities/ - List all activities with stats

Frontend Features

User Interface

Responsive Design: Works on desktop, tablet, and mobile
Dark/Light Mode: Automatic theme switching
Bilingual Support: English and Chinese with persistent language preference
Modern UI: Clean, intuitive interface with Tailwind CSS

Key Components

Authentication Flow: Login, registration, password reset
Student Dashboard: Activity browsing, application tracking, profile management
Staff Dashboard: Activity creation, student management, analytics
Location Picker: Interactive map for activity venues
Date/Time Picker: User-friendly scheduling interface

Internationalization

Translation files are located in frontend/src/locales/:

import { useTranslation } from "react-i18next";

function MyComponent() {
  const { t } = useTranslation();
  return <h1>{t("welcome.title")}</h1>;
}

Development

Available Scripts

Backend

cd backend
python manage.py runserver          # Start development server
python manage.py test              # Run tests
python manage.py makemigrations    # Create database migrations
python manage.py migrate           # Apply migrations
python manage.py init_app          # Initialize with sample data
python manage.py seed_students     # Seed student data

Frontend

cd frontend
npm start         # Start development server
npm run build     # Build for production
npm test          # Run tests
npm run typecheck # TypeScript type checking

Code Quality

Backend: Follows PEP 8 style guide, uses Black for formatting
Frontend: ESLint and Prettier for code quality
Testing: pytest for backend, Vitest for frontend
Git Hooks: Pre-commit hooks for quality checks

Database Management

# Reset database (development only)
python manage.py flush
python manage.py migrate
python manage.py init_app

Deployment

Production Checklist

Set DJANGO_DEBUG=false in environment
Configure production database settings
Set strong DJANGO_SECRET_KEY
Configure allowed hosts and CORS settings
Enable HTTPS and secure headers
Setup static file serving (nginx/apache)
Configure log rotation and monitoring
Setup backup strategy for database

Deploying Without Docker

Use scripts/sh/deploy.sh for both bootstrap and updates (see README_DEPLOYMENT.md).
Ensure the target host provides python3, python3-venv, pip, git, npm, and sudo before running the script (or set USE_VENV=false PYTHON_BIN=python to rely on a pre-provisioned system interpreter).
./scripts/sh/deploy.sh bootstrap --domain yourdomain.com creates/refreshes the virtualenv, installs dependencies, runs migrations and seed data, builds the frontend, and syncs assets into /opt/1panel/apps/openresty/openresty/www/sites/yourdomain.com/index (the virtualenv step is skipped when USE_VENV=false).
./scripts/sh/deploy.sh update --domain yourdomain.com pulls the latest code (when PULL_FIRST=true), refreshes the backend environment, rebuilds the frontend, and executes any RESTART_COMMAND you provide inline.
Export overrides inline (e.g. RUN_COLLECTSTATIC=true, WAIT_FOR_DB=true, RESTART_COMMAND="sudo systemctl restart activitypass") as needed for your environment.
Hook your process manager (systemd, supervisor, etc.) to the virtualenv in backend/.venv—or the system interpreter when USE_VENV=false—and let the script restart it via RESTART_COMMAND.

Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes with tests
Run tests: python manage.py test and npm test
Commit with clear messages: git commit -m "Add: feature description"
Push to your fork: git push origin feature/your-feature
Create a Pull Request

Code Standards

Python: PEP 8 compliant, type hints encouraged
TypeScript: Strict mode, descriptive variable names
React: Functional components with hooks
Git: Conventional commit messages

Testing

# Backend tests
cd backend
python manage.py test --verbosity=2

# Frontend tests
cd frontend
npm test -- --coverage

Project Status

Current Features

Planned Features

License

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

Acknowledgments

Zhejiang Normal University for the hackathon opportunity
Django Community for the excellent web framework
React Community for the powerful frontend library
Open Source Contributors for the amazing tools and libraries

Support

For questions or support:

Create an issue on GitHub
Contact the development team
Check the documentation

Built for ZJNU Hackathon 2025-2026

Name		Name	Last commit message	Last commit date
Latest commit History 200 Commits
backend		backend
frontend		frontend
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_DEPLOYMENT.md		README_DEPLOYMENT.md
run_all.py		run_all.py

License

Al-rimi/ActivityPass

Folders and files

Latest commit

History

Repository files navigation

ActivityPass (活动通)

Project Overview

Core Features

Architecture

Tech Stack

Repository Structure

Quick Start

Prerequisites

One-Command Setup (Recommended)

Manual Setup

1. Environment Configuration

2. Backend Setup

3. Frontend Setup

Configuration

Environment Variables

Database Setup

API Documentation

Authentication Endpoints

Student Endpoints

Activity Endpoints

Admin Endpoints

Frontend Features

User Interface

Key Components

Internationalization

Development

Available Scripts

Backend

Frontend

Code Quality

Database Management

Deployment

Production Checklist

Deploying Without Docker

Contributing

Development Workflow

Code Standards

Testing

Project Status

Current Features

Planned Features

License

Acknowledgments

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Contributors 3

Uh oh!

Languages