Student-Class Matcher Application

A web application that optimally assigns students to classes based on their preferences using constraint satisfaction algorithms (PuLP library).

🎯 Features

• Student Management: Add students manually or import from Excel
• Preference System: "Wants with" and "Doesn't want with" preferences
• Constraint Satisfaction: Uses PuLP optimization algorithm
• Results Visualization: Clear display of class assignments and statistics
• Multiple Export Formats: Excel, CSV, JSON, and PDF
• Configuration Backup: Save and restore complete configurations

🏗️ Architecture

Frontend

• Framework: Next.js 14+ with App Router
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS v3
• State Management: React Context API
• File Handling: SheetJS (xlsx)

Backend

• Framework: Flask (Python)
• Algorithm: PuLP (Linear Programming)
• API: RESTful endpoints with CORS
• Port: 5001 (to avoid macOS AirPlay conflict on port 5000)

📋 Prerequisites

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

🚀 Quick Start

1. Backend Setup

# Navigate to backend directory
cd python-backend

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

# Install dependencies (if not already done)
pip install -r requirements.txt

# Start the server (Option A - recommended)
./start.sh

# OR Option B - manual start
export PORT=5001  # Windows: set PORT=5001
python app.py

Backend will run on: http://localhost:5001

2. Frontend Setup

# Open new terminal, navigate to frontend directory
cd student-class-matcher

# Install dependencies (if not already done)
npm install

# Start development server
PORT=3002 npm run dev

Frontend will run on: http://localhost:3002

🔧 Configuration

Port Configuration

Backend Port (5001):

• Set in python-backend/app.py via PORT environment variable
• Default: 5001 (avoids macOS AirPlay on port 5000)

Frontend Port (3002):

• Set via PORT environment variable when starting
• Default: 3000 (we use 3002 to avoid conflicts)

API URL:

• Configured in student-class-matcher/.env.local
• Default: NEXT_PUBLIC_API_URL=http://localhost:5001

Changing Ports

If you need to use different ports:

1. Backend:

   export PORT=5002  # Your desired port
   python app.py

2. Frontend:

   • Update student-class-matcher/.env.local:

     NEXT_PUBLIC_API_URL=http://localhost:5002
     

   • Restart frontend: PORT=3003 npm run dev

📁 Project Structure

Bob_Matching/
├── python-backend/
│   ├── venv/                 # Python virtual environment
│   ├── app.py               # Flask API server
│   ├── solver.py            # PuLP algorithm implementation
│   ├── models.py            # Data models
│   ├── test_solver.py       # Backend tests
│   ├── requirements.txt     # Python dependencies
│   └── start.sh            # Startup script
│
├── student-class-matcher/
│   ├── app/                 # Next.js app directory
│   │   ├── page.tsx        # Home page
│   │   ├── configure/      # Configuration page
│   │   ├── results/        # Results page
│   │   ├── layout.tsx      # Root layout
│   │   └── globals.css     # Global styles
│   ├── components/          # React components
│   │   ├── FileUpload.tsx
│   │   ├── StudentForm.tsx
│   │   └── StudentList.tsx
│   ├── contexts/            # React contexts
│   │   ├── ConfigurationContext.tsx
│   │   └── ResultsContext.tsx
│   ├── lib/                 # Utility libraries
│   │   ├── apiClient.ts
│   │   ├── xlsxParser.ts
│   │   └── exportUtils.ts
│   ├── types/               # TypeScript types
│   ├── .env.local          # Environment variables
│   └── package.json        # Node dependencies
│
├── TESTING_GUIDE.md        # Complete testing guide
├── ALGORITHM_ANALYSIS.md   # Algorithm documentation
├── XLSX_STRUCTURE.md       # Excel format specification
└── README.md               # This file

🧪 Testing

See TESTING_GUIDE.md for comprehensive testing instructions including:

• 24 detailed test cases
• Setup verification
• Troubleshooting guide
• Success criteria

Quick test:

# Backend tests
cd python-backend
source venv/bin/activate
python test_solver.py

# Frontend (open browser)
# Navigate to http://localhost:3002
# Follow test cases in TESTING_GUIDE.md

📊 Excel File Format

Students can be imported from Excel files with the following structure:

Student_ID	Student_Name	Wants_With	Doesnt_Want_With
S001	John Doe	S002, S003	S004
S002	Jane Smith	S001

See XLSX_STRUCTURE.md for complete specification.

🔍 Algorithm Details

The application uses PuLP (Python Linear Programming) to solve the class assignment problem as a constraint satisfaction problem.

Constraints:

1. Each student assigned to exactly one class
2. Class sizes within min/max bounds
3. "Wants with" preferences satisfied (students in same class)
4. "Doesn't want with" preferences satisfied (students in different classes)

See ALGORITHM_ANALYSIS.md for detailed algorithm documentation.

🐛 Troubleshooting

Port 5000 Already in Use (macOS)

Problem: macOS AirPlay Receiver uses port 5000

Solution: Backend now uses port 5001 by default. If you still see this error:

1. Disable AirPlay Receiver in System Settings
2. Or use a different port (see Configuration section)

Backend Connection Failed

Symptoms: Frontend shows "Failed to run algorithm" error

Solutions:

1. Verify backend is running: curl http://localhost:5001/api/health
2. Check .env.local has correct API URL
3. Restart both frontend and backend
4. Check terminal for error messages

Module Not Found (Python)

Problem: ModuleNotFoundError: No module named 'flask'

Solution:

cd python-backend
source venv/bin/activate
pip install -r requirements.txt

TypeScript Errors

Problem: Type errors in VS Code

Solution:

cd student-class-matcher
npm install
# Restart VS Code TypeScript server: Cmd+Shift+P → "TypeScript: Restart TS Server"

📝 API Endpoints

Health Check

GET http://localhost:5001/api/health

Solve Assignment

POST http://localhost:5001/api/solve
Content-Type: application/json

{
  "numClasses": 3,
  "minClassSize": 5,
  "maxClassSize": 10,
  "students": [...]
}

🎓 Usage Workflow

1. Configure Students

   • Add manually or import from Excel
   • Set preferences (wants with / doesn't want with)

2. Set Class Parameters

   • Number of classes
   • Minimum class size
   • Maximum class size

3. Run Algorithm

   • Click "Run Algorithm"
   • Wait for optimization (usually <5 seconds)

4. View Results

   • See class assignments
   • Check statistics
   • Review any violations

5. Export

   • Download results (Excel, CSV, PDF)
   • Save configuration for later use

🤝 Contributing

This project follows a phased development approach:

• Phase 1-8: Complete ✅
• Phase 9: Data Persistence (Optional)
• Phase 10: Testing & QA
• Phase 11: Documentation & Deployment
• Phase 12: Final Review

📄 License

This project was built with Bob (AI Assistant).

🆘 Support

For issues or questions:

1. Check TESTING_GUIDE.md
2. Review error messages in terminal
3. Verify all prerequisites are installed
4. Ensure both frontend and backend are running

---

Made with ❤️ using Next.js, Flask, and PuLP