Curriculum Recommendation System

SQLite 기반 컴퓨터교육과 교육과정 추천 시스템입니다. 현재 구현은 DB seed, 선수과목 DAG, 졸업/교직 요건 검사, 과목 추천 CLI를 포함합니다.

Structure

• database/schema.sql: SQLite table schema
• database/seed.sql: course, requirement, prerequisite, sample student data
• curriculum/graph.py: prerequisite DAG loading, validation, topological sort
• curriculum/requirements.py: graduation, teaching, and non-course requirement checker
• curriculum/recommender.py: transparent scoring-based course recommender
• api/main.py: FastAPI backend for the web UI
• frontend/: React + Vite web UI
• scripts/verify_dag.py: standalone DAG verification script
• cli.py: command-based CLI

Database And DAG

Courses are graph vertices. Rows in prerequisites are directed edges from the prerequisite course to the later course.

REQUIRED edges block recommendation until completed. RECOMMENDED edges do not block recommendation, but they affect score and explanation.

Graduation credits, course-count requirements, and non-course requirements are not graph edges. They are checked separately by RequirementChecker.

Recommendation Scoring

The recommender only recommends offered courses that the student has not completed and whose REQUIRED prerequisites are satisfied.

Score signals include:

• unmet graduation or teaching requirement relevance,
• satisfied REQUIRED prerequisites,
• recommended year and semester match,
• target track match,
• completed RECOMMENDED prerequisites,
• penalty for courses recommended much later than the target year.

Each recommendation includes reasons, requirement relevance, missing required prerequisites, completed recommended prerequisites, and missing recommended prerequisites.

Commands

Initialize a local SQLite database:

python cli.py init-db

Run DAG validation:

python scripts/verify_dag.py
python cli.py check-dag
python cli.py topo
python cli.py prereq COM3026
python cli.py prereq CFTD010
python cli.py prereq CFTD103

Inspect student state and requirements:

python cli.py list-courses
python cli.py completed S001
python cli.py requirements S001
python cli.py non-course-status S001

Recommend courses:

python cli.py recommend S001 --limit 10
python cli.py recommend-semester S001 --year 1 --semester 2 --limit 10

Web UI

The web UI keeps the existing Python recommendation logic and SQLite database. Students can edit the sample profile, check completed courses, save them, and then see recommended courses calculated by CurriculumRecommender. It also shows graduation and teaching requirement status from RequirementChecker. The prerequisite graph screen visualizes course vertices and directed prerequisite edges with React Flow, highlighting completed and recommended courses for the current student.

Student Profile Editing

The web UI can edit the student's name, year, semester, and target track. Saved year and semester values are used by the recommendation score and can change recommendation ordering. The prerequisite DAG edges and edge weights remain fixed curriculum data and are not modified by student profile changes.

Non-Course Requirement Management

Non-course requirements are managed separately from completed courses. They are stored in student_non_course_records, not in completed_courses. The web UI includes a dedicated non-course requirement screen where students can check completion, enter counts, and add optional notes. Saved non-course status is reflected by RequirementChecker in the requirement dashboard.

The completed-course screen includes a sample reset button that restores S001 to the seeded demo state, including profile fields, completed courses, and non-course requirement progress.

Install backend dependencies:

python3 -m pip install -r requirements.txt

Start the FastAPI backend from the project root:

uvicorn api.main:app --reload

If uvicorn is not on your shell path, run:

python3 -m uvicorn api.main:app --reload

Start the React frontend:

cd frontend
npm install
npm run dev

Open the Vite URL printed in the terminal, usually http://localhost:5173. The frontend proxies /api requests to the FastAPI server on http://127.0.0.1:8000.

Implemented API endpoints:

GET /api/courses
GET /api/students/{student_id}
PUT /api/students/{student_id}
GET /api/students/{student_id}/completed
PUT /api/students/{student_id}/completed
GET /api/students/{student_id}/non-course-requirements
PUT /api/students/{student_id}/non-course-requirements
POST /api/students/{student_id}/reset-sample
GET /api/students/{student_id}/recommendations
GET /api/students/{student_id}/requirements
GET /api/graph
GET /api/courses/{course_id}/prerequisites

Run tests:

python -m unittest

Example Recommendation Output

Recommendations for S001
 1. CFTD094 교육학개론 (2cr, score 105, 1Y/1,2S)
    reasons: 미충족 졸업/교직 요건에 직접 기여, 필수 선수과목 충족, 1학년 권장 과목, 2학기 권장 과목, COMMON 트랙과 관련
    requirement relevance: 교직과목, 교직이론
    prerequisites: required missing=none; recommended completed=none; recommended missing=none

Sample Student

S001 is seeded as a first-year, second-semester student on the COMMON track. Completed courses are COM2002 and COM2003. Default non-course requirement records are seeded separately in student_non_course_records with completed progress for the demo scenario.

Branches

• main: FastAPI + React web implementation
• python: original Python CLI implementation