Grader Assignment System

A modern, FERPA-compliant system for assigning graduate students to grading positions using automated stable matching algorithms. Replaces legacy Microsoft Access database with a robust, multi-user web application.

🎯 Overview

This system manages the assignment of approximately 150 graduate students to grading positions each semester at Vanderbilt University's Computer Science department. It automates the complex matching process between student preferences and faculty requirements while respecting various constraints and qualifications.

Key Features

• Automated Matching: Modified Gale-Shapley algorithm ensures stable, fair assignments
• Excel Integration: Import/export data from existing systems (Kuali, OAS)
• Multi-User Concurrent Access: SQLite with WAL mode supports simultaneous editing
• Real-Time Updates: WebSocket-based live updates across connected users
• FERPA Compliant: Comprehensive audit logging and access controls
• Manual Overrides: Administrators can adjust automated assignments with justification
• Rich Reporting: Generate faculty feedback forms and assignment summaries

📊 Success Metrics

Primary Validation: System matches 80%+ of historical Fall 2024 assignments when given the same input data.

Performance Targets:

• Import 150 applications in <10 seconds
• Complete matching algorithm in <5 seconds
• Database queries return in <500ms
• 90%+ test coverage

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     User's Computer                          │
│                                                              │
│  ┌────────────────────────────────────────────────────┐    │
│  │         React Frontend (Port 3000)                  │    │
│  │  • TypeScript + shadcn/ui                          │    │
│  │  • TanStack Query for state management             │    │
│  └────────────────────────────────────────────────────┘    │
│                           ↕ HTTP/WebSocket                   │
│  ┌────────────────────────────────────────────────────┐    │
│  │         FastAPI Backend (Port 8000)                 │    │
│  │  • REST API endpoints                               │    │
│  │  • WebSocket for real-time updates                 │    │
│  │  • Business logic & matching algorithm             │    │
│  └────────────────────────────────────────────────────┘    │
│                           ↕ SQLAlchemy ORM                   │
│  ┌────────────────────────────────────────────────────┐    │
│  │         SQLite Database (WAL mode)                  │    │
│  │  • Student records & applications                   │    │
│  │  • Course details & grades                          │    │
│  │  • Faculty rankings & assignments                   │    │
│  │  • FERPA-compliant audit log                        │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• Git

Installation

# Clone the repository
git clone https://github.com/vanderbilt-data-science/grade-match.git
cd grade-match

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Initialize database
alembic upgrade head

# Start backend server
uvicorn app.main:app --reload

# Frontend setup (in new terminal)
cd frontend
npm install
npm run dev

Access the application at http://localhost:3000

📁 Project Structure

grade-match/
├── backend/
│   ├── app/
│   │   ├── models/          # SQLAlchemy database models
│   │   ├── schemas/         # Pydantic validation schemas
│   │   ├── api/             # FastAPI route handlers
│   │   ├── services/        # Business logic & matching algorithm
│   │   ├── utils/           # Helper functions
│   │   ├── database.py      # Database configuration (WAL mode)
│   │   └── main.py          # FastAPI application entry
│   ├── tests/
│   │   ├── critical/        # Fall 2024 validation test
│   │   ├── integration/     # Workflow tests
│   │   └── performance/     # Performance benchmarks
│   ├── alembic/             # Database migrations
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   ├── pages/           # Application pages
│   │   ├── lib/             # Utilities and API client
│   │   └── App.tsx          # Main application component
│   ├── package.json
│   └── vite.config.ts
└── docs/                    # Comprehensive documentation
    ├── 00-quick-start.md
    ├── 01-project-overview.md
    ├── 02-database-schema.md
    ├── 03-api-specification.md
    ├── 04-matching-algorithm.md
    ├── 05-excel-specification.md
    ├── 06-implementation-checklist.md
    ├── 07-ferpa-security.md
    └── 08-testing-strategy.md

🔄 Workflow

Typical Semester Cycle

1. Import Student Data - Load student bio information from Kuali export
2. Import Applications - Load student course preferences
3. Import Course Grades - Load historical grades from OAS
4. Generate Faculty Feedback Forms - Export Excel forms for each course
5. Import Faculty Rankings - Load completed faculty feedback
6. Prepare Matching Worksheet - Build all valid student-course combinations
7. Run Matching Algorithm - Execute stable matching algorithm
8. Review & Adjust - Manual overrides if needed with justification
9. Finalize Assignments - Lock in final decisions
10. Export Results - Generate assignment summaries and reports

🧮 Matching Algorithm

The system uses a modified Gale-Shapley stable matching algorithm with the following features:

Student Preferences

• Ranked course choices (1st through 5th)
• Validated against course availability

Faculty Preferences

• Rankings: 1 (Best), 2 (Acceptable), 3 (Not Suitable)
• Tiebreaking based on:
  • Previous grader experience (+100 points)
  • Course grade (A+ to F scale)
  • Overall GPA (0-4 scale × 10)
  • Student preference ranking

Hard Constraints

• do_not_hire flag exclusion
• Faculty rank 3 (not suitable) exclusion
• Course capacity limits
• Grade prerequisites

Validation

• Stability verification (no blocking pairs)
• Metrics calculation (student/faculty satisfaction)
• 80%+ historical accuracy target

📚 Documentation

Comprehensive documentation is available in the /docs directory:

• Quick Start Guide - Get up and running
• Project Overview - Architecture and requirements
• Database Schema - Complete data model
• API Specification - All endpoints documented
• Matching Algorithm - Algorithm details and logic
• Excel Specification - Import/export formats
• Implementation Checklist - 15-week roadmap
• FERPA Security - Compliance requirements
• Testing Strategy - Test approach and coverage

🧪 Testing

# Run all backend tests
cd backend
pytest

# Run with coverage report
pytest --cov=app --cov-report=html

# Run critical Fall 2024 validation test
pytest tests/critical/

# Run frontend tests
cd frontend
npm test

# Run E2E tests
npm run test:e2e

Critical Test: Fall 2024 Recreation

The most important test validates that the matching algorithm can recreate historical Fall 2024 assignments with 80%+ accuracy. This proves the system works correctly.

🔒 Security & Compliance

FERPA Compliance

• Comprehensive audit logging of all data access
• Role-based access control (Admin, Coordinator, Faculty, Read-Only)
• PII encryption at rest for sensitive fields
• Secure file permissions and data handling
• 7-year audit log retention

Data Protection

• Input validation on all endpoints (Pydantic schemas)
• SQL injection prevention (SQLAlchemy ORM)
• Secure file upload handling
• Generic error messages (no info leakage)

🛠️ Development

Backend Development

cd backend
source venv/bin/activate

# Run development server with auto-reload
uvicorn app.main:app --reload

# Run linters
black app/
ruff check app/
mypy app/

# Create new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

Frontend Development

cd frontend

# Development server
npm run dev

# Linting
npm run lint

# Type checking
npm run type-check

# Build for production
npm run build

📦 Deployment

Local Deployment

System runs entirely on local machine - no cloud dependencies required.

Network Deployment (Optional)

Can be deployed on shared network drive with:

• Multiple users accessing same SQLite database
• WAL mode ensuring concurrent access safety
• HTTPS/TLS for secure connections

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Write tests for all new features (90%+ coverage target)
• Follow Python style guide (black + ruff)
• Use TypeScript strict mode
• Update documentation for API changes
• Ensure FERPA compliance for data handling

📝 License

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

👥 Authors

Vanderbilt University Data Science Institute

🙏 Acknowledgments

• Computer Science department for requirements and historical data
• Carter and Graham for domain expertise and user testing
• Student graders who will benefit from improved assignment process

📞 Support

For questions or issues:

• Create an issue in this repository
• Contact: Vanderbilt Data Science Institute
• Documentation: See /docs directory

🗺️ Roadmap

• Complete system specifications
• Phase 1: Core backend (Weeks 1-2)
• Phase 2: Excel processing (Weeks 3-4)
• Phase 3: Matching algorithm (Weeks 5-6)
• Phase 4: Frontend UI (Weeks 7-10)
• Phase 5: Real-time features (Week 11)
• Phase 6: Integration & testing (Weeks 12-13)
• Phase 7: Documentation & deployment (Week 14)
• Phase 8: Training & handoff (Week 15)

---

Built with ❤️ by Vanderbilt Data Science