# University/College Complete Refactor Map

This application copy is the university/college build. It is intended for universities, colleges, TVETs, film schools, academies, and professional institutions.

## Terminology Map

| Legacy term | University term | Internal compatibility note |
| --- | --- | --- |
| Homework | Assignment | Legacy `homework` routes, tables, events, and classes may remain as hidden compatibility surfaces. |
| Homeworks | Assignments | Fresh UI, menus, permissions, notifications, and exports should say Assignments. |
| Subject | Unit | Legacy `subject_id` and `sm_subjects` remain until every academic/exam dependency can be migrated safely. |
| Subjects | Units | Fresh UI should use Unit/Units. |
| Teacher | Lecturer | Staff role id `4` may remain internally where permissions depend on it. |
| Class Teacher | Academic Advisor | Legacy assignment records may still point to class-teacher routes/permissions internally. |
| Subject Teacher | Unit Lecturer | Existing `teacher_id` fields remain as compatibility keys. |
| Dormitory | Hostel | Legacy dormitory table/model names remain internally for accommodation logic. |
| Section | Academic Grouping | New student flows use Year of Study, Semester, and Course Period; `section_id` remains as a compatibility backbone. |

## Route Strategy

Fresh university routes are added as aliases to existing controllers:

- `course-assignment-list` / `assignment.list` maps to the legacy assignment/homework list controller. The plain `assignment-list` URI already belongs to Study Material, so the course assignment workflow uses the non-conflicting `course-assignment-*` URI family.
- `add-course-assignment`, `course-assignment-edit`, `course-assignment-update`, `course-assignment-delete`, `assignment-evaluation`, and assignment reports map to legacy homework handlers.
- `unit-list`, `unit-store`, `unit-edit`, `unit-update`, `unit-delete`, `assign-unit`, and global unit routes map to legacy subject handlers.
- `academic-advisor` routes map to legacy class-teacher assignment handlers.
- `hostel-list`, `hostel-room-list`, and hostel report routes map to legacy dormitory handlers.
- `academic-grouping-settings` remains, with `academic-grouping.settings` and `academic-grouping.list` added as university-named route aliases.

The dynamic sidebar keeps legacy permission slugs, but `validRouteUrl()` maps those slugs to university route aliases for visible navigation.

Old routes are retained because many permissions, notifications, mobile clients, and packages still reference them.

## Permission Strategy

Permission display labels should use Assignment, Unit, Lecturer, Hostel, and Academic Grouping. Where changing a permission slug would break `userRolePermission` middleware checks, the slug is retained and treated as a compatibility alias.

The `2026_05_15_000003_update_university_permission_display_labels.php` migration updates existing permission/module display names without deleting old slugs.

## Database Naming Strategy

Core legacy tables are not destructively renamed in this phase:

- `sm_homeworks` remains the storage table for assignments.
- `sm_subjects` remains the storage table for units.
- `sm_sections` remains for legacy section compatibility.
- `sm_dormitories` / dormitory models remain for hostel logic.
- staff/teacher ids remain for lecturer assignments.

University-facing model aliases wrap legacy tables where helpful:

- `Assignment` maps to the homework model/table.
- `Unit` maps to the subject model/table.
- `Hostel` maps to dormitory storage.
- `Lecturer` maps to staff records with the lecturer/teacher role.

## Academic Grouping

Super Admin manages:

- Year of Study options
- Semester options
- Course Period options
- labels and display format

The system supports:

- Year of Study + Semester
- Course Period only
- Year of Study + Semester + Course Period

Starter values may be seeded for fresh installs only when option tables are empty:

- Year of Study: `Y1`, `Y2`, `Y3`, `Y4`
- Semester: `S1`, `S2`, `S3`
- Course Period: `Jan - March`, `April - June`, `September Intake`

These are editable and are not application logic.

## Why `section_id` Still Exists

Many existing modules still query by `section_id`, including exams, marksheets, attendance, timetable/class routine, assignment evaluation, reports, hostel/transport, and finance-adjacent flows. Removing it immediately would risk breaking production behavior. New university flows write the new grouping ids and retain a fallback `section_id` only for legacy query compatibility.

Do not remove `section_id`, `sm_sections`, `subject_id`, `teacher_id`, `homework_id`, or dormitory ids until each dependency has been migrated and tested.

## Fresh Install Notes

The system academic type is `university_college`. Fresh menus, labels, routes, notifications, import/export headings, and seeded display names should prefer university wording even when a legacy backend name remains.

## Testing Checklist

1. App boots and login works.
2. Dashboard and sidebar load.
3. Super Admin can manage academic grouping options.
4. Admission works with Year of Study + Semester.
5. Admission works with Course Period only.
6. Student import works with Year of Study, Semester, Course Period.
7. Legacy Section import fallback still works.
8. Assignment list, create, submission, and evaluation work.
9. Unit setup and unit assignment work.
10. Lecturer dashboard and marking work.
11. Academic Advisor assignment works.
12. Hostel list, room list, and hostel assignment work.
13. Exam schedule, admit card, marksheet, and reports show university wording.
14. Old routes still resolve.
15. New university route aliases resolve.
