degreelink

Course Equivalency System - Technical Documentation

Last Updated: November 25, 2025
Production Domain: dlink.cs.uno.edu
Branch: dev-main

System Overview

The Course Equivalency and Transfer Planning System is a web application designed for academic advisors and students to manage course equivalencies, create degree plans, and track progress toward degree completion.

Core Capabilities:

Developer Setup

Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your DATABASE_URL and other settings

# Initialize database
flask db upgrade

# Run development server
flask run

Frontend Setup

cd frontend
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your API URL

# Run development server
npm run dev

# Build for production
npm run build

Technology Stack

Backend:

Frontend:

Current Features

1. Authentication System

Advisor Authentication

API Endpoints:

Admin API Token

Plan Access Sessions

2. Database

Type: PostgreSQL
Migration Tool: Flask-Migrate (Alembic)

Core Tables:

3. Requirement System

Requirement Types

Constraint Types

Constraints can apply at category-level or group-level:

  1. Credits Constraint
    • Min/max credit requirements
    • Example: “Complete 10-15 credits from BIOS electives”
  2. Course Count Constraint
    • Min/max number of courses
    • Example: “Take 3-5 courses from this list”
  3. Level Constraint
    • Minimum course level (e.g., 3000+ courses)
    • Min courses at that level
    • Example: “At least 2 courses must be 3000-level or higher”
  4. Tag Constraint
    • Filter by course attributes (has_lab, course_type, etc.)
    • Example: “At least 2 courses must have labs”
  5. Subject Code Scope
    • Limit constraints to specific subject codes (space-delimited)
    • Example: “15 credits required, but only from BIOS or CHEM courses”

Constraint Features:

4. Prerequisite System

Location: Course-level validation
Storage: courses.prerequisites field (comma-separated)
Service: backend/services/prerequisite_service.py

Features:

API Endpoints:

5. CSV Upload System

Upload Types:

  1. Courses - Course catalog entries
  2. Equivalencies - Course equivalency mappings
  3. Program Requirements - Requirements with embedded constraints

Key Features:

6. Progress Tracking

Features:

7. Frontend Architecture

Framework: React + Vite
Styling: TailwindCSS
Key Components:

File Structure

backend/
├── app.py                    # Flask application
├── config.py                 # Configuration
├── auth.py                   # Authentication decorators
├── models/
│   ├── course.py            # Course model
│   ├── equivalency.py       # Equivalency model
│   ├── program.py           # Program & requirement models
│   ├── constraint.py        # Constraint model
│   ├── plan.py              # Plan & plan_courses models
│   └── advisor_auth.py      # Advisor authentication
├── routes/
│   ├── courses.py           # Course endpoints
│   ├── equivalencies.py     # Equivalency endpoints
│   ├── programs.py          # Program endpoints
│   ├── plans.py             # Plan endpoints
│   ├── upload.py            # CSV upload endpoints
│   ├── qr.py                # QR code generation
│   ├── prerequisites.py     # Prerequisite validation
│   └── advisor_auth.py      # Advisor auth endpoints
└── services/
    ├── prerequisite_service.py   # Prerequisite logic
    └── progress_service.py       # Progress calculation

frontend/
├── src/
│   ├── App.jsx
│   ├── components/
│   │   ├── AppShell.jsx
│   │   ├── AdvisorAuthModal.jsx
│   │   ├── ProgressTracking.jsx
│   │   ├── CSVUpload.jsx
│   │   └── ...
│   ├── pages/
│   │   ├── AppManagementPage.jsx
│   │   └── ...
│   └── services/
│       └── api.js
└── public/

Environment Configuration

Backend (.env)

DATABASE_URL=postgresql://ct_user:DeptOfCs@localhost:5432/course_transfer
ADMIN_API_TOKEN=your_admin_token
FLASK_ENV=development
SECRET_KEY=your_secret_key

Frontend (.env.local)

VITE_API_BASE_URL=http://localhost:5000
VITE_ADMIN_API_TOKEN=your_admin_token

Deployment Status

Development

Production (dlink.cs.uno.edu)

Known Limitations

  1. TOTP Setup Required: All advisors need to set up authenticator app on first login
    • Email code fallback available for troubleshooting
    • Use “Regenerate TOTP Secret” for device loss/transfer
  2. Session Storage: Uses Flask server-side sessions
    • Not distributed across multiple backend instances
    • Use sticky sessions or Redis for load balancing
  3. File Upload Size: Default Flask limits apply
    • Large CSV files may need configuration adjustment

Testing

Backend Tests

cd backend
pytest

Test Coverage:

Frontend Build

cd frontend
npm run build

Next Steps

Immediate

  1. Deploy to production (dlink.cs.uno.edu)
  2. Whitelist all advisors and complete TOTP setup
  3. Monitor authentication and system usage

Short Term

  1. Configure SMTP to remove backdoor code
  2. Set up monitoring/logging for authentication
  3. Create backup/recovery procedures for lost devices
  4. Document common troubleshooting scenarios

Long Term

  1. Implement audit logging for advisor actions
  2. Add plan sharing/collaboration features
  3. Mobile-responsive improvements
  4. Enhanced error tracking

Contact & Support

Development Team: UNO CS Department
Repository: mmennelle/course-equivalency
Branch: dev-main
Production URL: dlink.cs.uno.edu

This site is open source. Improve this page.