File Structure Documentation

Workflow

The recommended workflow for this project is:

main → staging-2 → example-branch

The original staging branch is obsolete, any new branches should be made from staging-2 then pushed back into staging-2 and from staging-2 to main. The staging-2 and main branches are caught up with each other except for the readme file which is different in main. A new staging branch can be created from main to continue development or simply update the readme file in staging-2 to avoid merge conflicts.

Backend

main.py

Purpose:
FastAPI entrypoint for the CourseMatcher backend.

Use:

• Configures CORS for local and deployed frontends.
• Defines endpoints:
  • GET /courses/ → Returns all courses from BIT.db.
  • GET /search/ → Performs semantic search using stored embeddings and parsed user input.
• Integrates with extract_courses_from_input from course_parser.py.

---

course_parser.py

Purpose:
Handles all LLM-based parsing and structuring of course text.

Use:

• extract_text, split_blocks, extract_data:
  Extract structured course data from local text or documents.
• Course, CourseList:
  Pydantic models defining valid structured outputs for courses.
• extract_courses_from_input(user_text):
  Parses live user input (from frontend search form) into course objects {course_title, description} used by the search API.

---

model.py

Purpose:
Defines the Pydantic models used for validation, serialization, and computed field logic.

Use:

• Course: Represents a full course record with level, credits, prerequisites, learning hours, and description.

---

seed.py

Purpose:
Initializes and populates the SQLite database with course data and embeddings.

Use:

• Reads data from app/static/courses_BIT.json.
• Recreates and seeds the courses table in app/data/BIT.db.
• Generates embeddings for each course using SentenceTransformer("all-MiniLM-L6-v2").
• Inserts all metadata and embeddings into the database.
• Run this manually whenever data updates occur.

---

requirements.txt

Purpose:
Lists Python dependencies for the backend.

Use:

• Install backend environment in the project root with:

  ./setup.bat

• This automatically reads Python dependencies from the requirements.txt file.

---

app/data/BIT.db

Purpose:
SQLite database used by the backend to store courses and their vector embeddings.

Use:

• Queried by FastAPI endpoints /courses/ and /search/.
• Populated automatically by running seed.py.

---

app/static/courses_BIT.json

Purpose:
JSON source of structured data for the IT courses.

Use:

• Used by seed.py to seed BIT.db.
• Updated whenever course information changes.

---

Frontend

SearchBar.tsx

Purpose:
Main input component for user search queries.

Use:

• Displays a textarea for pasting one or more course descriptions.
• Reads and updates q query parameters in the URL.
• Navigates to the appropriate route (e.g. /it) with search text for backend processing.

---

BachelorIT.tsx

Purpose:
Displays Bachelor of Information Technology courses and search results.

Use:

• Reads q parameters from the URL.
• If empty:
  • Calls GET /courses/ to show all courses.
• If present:
  • Calls GET /search/ for each query to get semantic matches.
  • Groups and displays results with similarity scores and colored bars.
• Includes “Read More / Show Less” for long course descriptions.

---

ProgramNav.tsx

Purpose:
Fixed navigation component for switching between programs and returning to the home page.

Use:

• Displays a top-right floating menu.
• Home button → Navigates to /.
• Hamburger menu → Expands a list of available programs (/it, /business, /design, /culinary).
• Used across all pages for consistent navigation.

---

frontend/public

• homeIcon.png → Used for the navigation home button.
• appBackground.jpg → Background image used in course listing pages for visual consistency.
• courseMatcher.png → Legacy logo.
• landingIcon.png → Current icon shown on the main landing page.
• vite.svg → Default Vite logo (kept for development reference or fallback asset).

---