Merge pull request #14 from minusunil/courseflow-documentation

Courseflow Documentation - Requirement Analysis

astro.config.mjs

@@ -174,6 +174,42 @@ export default defineConfig({
           label: 'Team',
           autogenerate: { directory: 'team' },
         },
+        {
+          label: 'Courseflow documentation',
+          autogenerate: {
+            directory: '/courseflow',
+          },
+          items: [
+            {
+              label: 'Courseflow Introduction',
+              link: '/courseflow/requirements',
+            },
+            {
+              label: 'Use Cases',
+              link: '/courseflow/usecase',
+            },
+            {
+              label: 'What is currently done?',
+              link: '/courseflow/current_stage',
+            },
+            {
+              label: 'Planned Features',
+              link: '/courseflow/future',
+            },
+            {
+              label: 'Visualisation',
+              link: '/courseflow/diagrams',
+            },
+            {
+              label: 'Frontend Structure',
+              link: '/courseflow/frontend',
+            },
+            {
+              label: 'Backend APIs',
+              link: '/courseflow/backend',
+            }
+          ],
+        },
       ],
     }),
   ],

src/content/docs/courseflow/backend.md

@@ -0,0 +1,124 @@
+---
+title: Backend API's
+---
+
+### Backend requirements of CourseFlow within OnTrack:
+
+#### Course:
+
+The routes involved with this will be relatively straightforward.
+
+| Endpoint                         | Description                                        | Request Body                    | Response Body|
+| ---------------------------------|----------------------------------------------------|---------------------------------|--------------|
+| GET /course                      | Get all course data                                | None                            | Course[]     |
+| GET /course/courseId/:courseId   | Get a course by id                                 | None                            | Course       |
+| GET /course/search               | Get courses that partially match the search params | None                            | Course[]     |
+| POST /course                     | Add a new course.                                  | Course                          | Course       |
+| PUT /course/courseId/:courseId   | Updates an existing course via its id              | Course                          | Course       |
+| DELETE /course/courseId/:courseId| Deletes an existing course via its id              | None                            | None         |
+
+Technically speaking, a course would likely only have different versions on a per year basis. However, to cater for the possibility that a course of a particular year gets updated, it would be a good idea to keep a history of this. The course map will keep track of a specific entry of a Course which will allow students to load up the correct version of the course (which by extension, will allow loading of the correct course requirements which will also be tied to specific course versions).
+
+The url will link to the course page which will provide more information about the course (that don't need to be present in CourseFlow such as contacts and entry requirements etc.). This can either be presented on the client side as a simple link or used to embed the course page within an IFrame element.
+
+#### Course Map
+
+Upon entry to the CourseFlow system within OnTrack, the course map associated with the authenticated user will need to be fetched or created.
+
+As such, the backend needs to have the following routes to cater for this:
+
+| Endpoint                                  | Description                                       | Request Body   | Response Body|
+| ------------------------------------------| --------------------------------------------------| -------------- | -------------|
+| GET /coursemap/userId/:userId             | Get a user's course map via their userId          | None           | CourseMap    |
+| GET /coursemap/courseId/:courseId         | Get all course maps via the course id.            | None           | CourseMap[]  |
+| POST /coursemap                           | Add a new course map for a user.                  | CourseMap      | CourseMap    |
+| PUT /coursemap/courseMapId/:courseMapId   | Updates an existing course map via its id.        | CourseMap      | CourseMap    |
+| DELETE /coursemap/courseMapId/:courseMapId| Deletes an existing course map via its id.        | None           | None         |
+| DELETE /coursemap/userId/:userId          | Deletes all course maps by user ID                | None           | None         |
+
+The options at present involves:
+
+- Getting student enrolment information via an API to Deakin University's systems.
+- Importing student enrolment information.
+- Manually setting the course via a client side user interface (will be an input box resulting in best matching courses based on search query).
+- Associating a course upon creation of the user and have the course map created at this point in time.
+
+#### Course Map Unit:
+
+This has a strong association with the course map and upon entry into the CourseFlow system, once we have the course map associated with the user fetched, we can use the course map id to fetch all course map units that belongs to the specific course map.
+
+| Endpoint                                | Description                                                    | Request Body   | Response Body  |
+| ----------------------------------------| ---------------------------------------------------------------| ---------------| ---------------|
+| GET /coursemapunit/courseMapId          |Get a all course map units associated with the course map id.   | None           | CourseMapUnit[]|
+| POST /coursemapunit                     |Add a new course map unit for a user.                           | CourseMapUnit  | CourseMapUnit  |
+| PUT /coursemapunit/courseMapUnitId      |Updates an existing course map unit via its id.                 | CourseMapUnit  | CourseMapUnit  |
+| DELETE /coursemapunit/courseMapUnitId   | Deletes an existing course map unit via its id.                | None           | None           |
+| DELETE /coursemapunit/courseMapId       | Deletes all course map units via the associated course map id. | None           | None           |
+
+The key factors here are:
+
+- Course map id which will associate a specific course map to the respective course map units.
+- Unit id which will associate the course map unit with a unit. This in itself will allow obtaining of unit information
+  such as name, unit  code, handbook url and requirements etc.
+- All three slot fields and their respective values will allow for matching to the correct spot on the client side visuals.
+
+#### Specialization
+
+We simply need routes that can get/add/update/delete specializations:
+
+| Endpoint                                | Description                                   | Request Body   | Response Body   |
+| ----------------------------------------| ----------------------------------------------| ---------------| --------------- |
+| GET /specialization                     | Get all specializations                       | None           | Specialization[]|
+| GET /specialization/specializationId    | Get specialization by id                      | None           | Specialization  |
+| POST /specialization                    | Add a new specialization                      | Specialization | Specialization  |
+| PUT /specialization/specializationId    | Updates an existing specialization via its id | Specialization | Specialization  |
+| DELETE /specialization/specializationId | Deletes an existing specialization via its id | None           | None            |
+
+The Specialization API provides a set of routes to manage specializations in a system. It allows users to retrieve all specializations (`GET /specialization`) or a specific one by ID (`GET /specialization/specializationId`), add new specializations (`POST /specialization`), update existing ones by ID (`PUT /specialization/specializationId`), and delete specializations by ID (`DELETE /specialization/specializationId`). Each route interacts with specialization data, supporting standard CRUD (Create, Read, Update, Delete) operations.
+
+#### RequirementsSet:
+
+This particular entity works in conjunction with Requirements where this provides a mechanism to list out required units that belong to a requirement. Additionally, this also provides a way to chain requirements to handle requirement choices. The routes will be as follow:
+
+| Endpoint                                   | Description                                   | Request Body | Response Body    |
+| -------------------------------------------| ----------------------------------------------|--------------| ---------------- |
+| GET /requirementset                        | Get all requirement sets                      | None         | RequirementSet[] |
+| POST /requirementset/requirementSetGroupId | Get all requirements set for a given group id | None         | RequirementSet[] |
+| POST /requirementset                       | Add a new requirement set                     | Requirement  | RequirementSet   |
+| PUT /requirementset/requirementSetId       | Updates an existing requirement set via its id| Requirement  | RequirementSet   |
+| DELETE /requirementset/requirementSetId    | Deletes an existing requirement set via its id| None         | None             |
+
+Each instance of this entity will be associated to a requirement and it will be our way of tracking a list of units associated with a requirement or chaining to another requirement to essentially create a group of selectable requirements.
+
+#### Unit Definition
+
+| Endpoint                                  | Description                                                | Request Body     | Response Body  |
+| ------------------------------------------|------------------------------------------------------------|------------------|----------------|
+| GET /unitDefinition                       | Get all unitDefinitions                                    |None              |UnitDefinition[]|
+| GET /unitDefinition/unitDefinitionId      | Get a specific unitDefinition based on the unitDefinitionId|None              |UnitDefinition  |
+| GET /unitDefinition/unitDefinitionId/units| Get all units associated with the unitDefinitionId         |None              |Unit[]          |
+| GET /unitDefinition/search                | Get unit definitions that match search params              |String (name/code)|UnitDefinition[]|
+| POST /unitDefinition                      | Create a new unitDefinition                                |UnitDefinition    |UnitDefinition  |
+| POST /unitDefinition/unitDefinitionId     | Create a new unit with a specific unitDefinition           |Unit              |Unit            |
+| PUT /unitDefinition/unitDefinitionId      | Updates an existing unitDefinition                         |UnitDefinition    |UnitDefinition  |
+| DELETE /unitDefinition/unitDefinitionId   | Delete a unitDefinition                                    |None              |None            |
+| PUT /unitDefintion/unitDefinitionId/unitId| Remove a unit from the unitDefinition                      |None              |Unit            |
+
+##### What is going to be missing from this semester’s deliverables for Courseflow and what needs to be worked on into the future?
+
+For this webpage there are a few key features that will need future development. Units in a course have rules that need to be followed, this includes the units’ prerequisites, maximum amount of certain level units, requiring specific subjects to be completed, ect. This will need to be implemented to check the course map is valid and follows said rules.
+
+Along side rules there are suggested unit combinations that should be completed in sequence, like part 1 and 2 of the capstone, or similar units across the degree, so maybe some warning and suggestions to the user in how they organise their course maps.
+Proper implementation to track for completed and ongoing units. At the moment this is done manually but should just work automatically in the future.
+
+With this unit definition, we want to be able to create and view various types of analytics. This could be an average mark for a type of unit over a year, number of students participating in specific units, ect. So having this unit definition be able to easily collate all the other offerings of the same unit, underperforming tasks, all sorts of information can be gleaned from this.
+
+Like units, there are different versions of courses, therefore there is space to create a similar course definition object to store the differences between the courses, including different unit groups and such. Should be implemented in basically the same way as the above unit definition.
+
+Want some way to implement a connection to the student services to get the ideal course maps/plans and maybe be able to view them inside of ontrack/courseflow.
+
+Summary:
+
+- Implement the rules for assigning units, prerequisites, ect.
+- Implement a course definition to store different versions of the courses
+- Be able to view given course maps from student services or something.

src/content/docs/courseflow/current_stage.md

@@ -0,0 +1,28 @@
+---
+title: What is currently done?
+---
+
+#### Coursemap:
+
+The Coursemap module provides students with a comprehensive tool to organize, customize, and track their course plan.It serves the following purposes:
+
+- Visualizing and Planning Units: Enables students to view and plan the units they need to undertake throughout their academic journey.
+- Managing Study Periods: Allows students to add or remove study periods (semesters or trimesters) to align their course timeline with their academic goals.
+- Adding and Removing Units: Provides the ability to add or remove units within specific study periods, ensuring flexibility in course management.
+- Handling Elective Units: Facilitates the addition and removal of elective units, giving students control over optional courses.
+- Tracking Unit Completion: Lets students mark units as completed, helping them monitor and visualize their progress towards graduation.
+
+##### Currently Implemented Features in Coursemap:
+
+1. Course Map Visualization:
+   - Ability to visualize and plan units for upcoming study periods.
+   - Options to add or remove study periods and elective units.
+   - Functionality to mark units as complete.
+2. Customizable Study Periods:
+   - Add and delete year and trimester containers with the ability to drag and drop units.
+   - Units automatically return to the required units container if a trimester is deleted.
+3. Elective Unit Management:
+   - Search bar to find elective units by code.
+   - Options to add and delete elective units from the course map.
+4. Data Integration:
+   - Integration with backend systems for saving and retrieving course maps.

src/content/docs/courseflow/diagrams.md

@@ -0,0 +1,21 @@
+---
+title: Courseflow Visualisation
+---
+
+#### CourseFlow Data Flow Diagram:
+
+##### CourseFlow Context Diagram (level 0 DFD):
+
+![CourseFlow DFD0](/CourseFlow-DFD-0.png)
+
+##### CourseFlow Context Diagram (level 1 DFD):
+
+![CourseFlow DFD1](/CourseFlow-DFD-1.png)
+
+#### CourseFlow Software Architecture Diagram:
+
+![CourseFlow SAD](/CourseFlow-SAD.png)
+
+#### Coursemap Mockup Diagram:
+
+![Coursemap Mockup](/CoursemapMockup2024.png)

src/content/docs/courseflow/frontend.md

@@ -0,0 +1,39 @@
+---
+title: Frontend Structure
+---
+
+#### Phase 1:
+
+- Create containers for study periods and required units.
+- Add/delete year and trimester containers.
+- Enable drag-and-drop functionality for units between trimesters and required units containers.
+- Units to transfer back to required units container when trimester is deleted.
+
+![Phase 1](/phase1.png)
+
+#### Phase 2:
+
+- Add elective units to the unit pool with search functionality.
+- Populate the remaining units container with relevant units for the selected course.
+- Add search bar to look up subject by unit code.
+- Add button to add to required units pool.
+- Populate remaining units container with relevant units from course.(Replace blank unit cards with to pull relevant units for a course
+  with title and code to display on card).
+
+![Phase 2](/phase2.png)
+
+![Phase 2.2](/phase2.2.png)
+
+#### Phase 3:
+
+- Enhance unit displays with more useful information.
+- Update styling for unit to display more useful information than when displaying in the required units lists.
+- Allow marking units as complete, preventing them from being moved.
+
+![Phase 3](/phase3.png)
+
+#### Phase 4:
+
+- Implement data saving and backend integration to store the course maps for each student.
+- Add ability to mark unit as complete.
+- Remove ability to move unit from study period container when marked as complete.

src/content/docs/courseflow/future.md

@@ -0,0 +1,20 @@
+---
+title: Planned Features
+---
+
+1. Enhanced Unit Information:
+   - Display of unit details (title, code) in a more useful format.
+   - Capability to mark units as complete, preventing further changes to that unit in the study plan.
+2. Skills Summary and Analytics:
+   - Summary of skills learned through the chosen units.
+   - Progress tracking towards degree completion with a focus on meeting all prerequisites and course requirements.
+3. Course Discovery:
+   - Plan and visualise requirements and dependencies for units.
+   - Explore useful elective units and possible major/minor unit sets.
+   - Find electives based on interest or skills.
+4. Trimester timetables:
+   - Expand unit api and db to include session information for lectures and classes.
+   - Ability to create timetable for current study periods using this session information for the current units.
+5. Learned skill tracker:
+   - Add skills to a unit.
+   - Generate learned skills based on units completed.

src/content/docs/courseflow/requirements.md

@@ -0,0 +1,39 @@
+---
+title: CourseFlow
+---
+
+### Introduction:
+
+CourseFlow is a product developed by Thoth Tech, launched in T1 2023. It is designed to assist students and course directors with course planning and understanding course requirements. The platform enablesusers to create personalized course maps that align with their degree requirements, providing a visual representation of all course units and prerequisites. The goal of CourseFlow is to streamline the course
+planning process, making it more accessible and efficient for students, while ensuring they stay on track to meet their graduation requirements.
+
+![logo](/logo.png)
+
+### Vision of Courseflow:
+
+#### Goal:
+
+"Support students in organizing their studies at Deakin and maximizing their time efficiently"
+
+#### End state:
+
+- Courseflow provides the ability to contact student services.
+- Verifying course rules to ensure the planned course map meets compliance requirements.
+- Units should be suggested based on the course rules and requirements already met.
+- Students marks analytics and a weighted average mark calculator.
+- Ability to defer a study period from within the coursemap.
+- Student handbook information displayed within courseflow.
+- Analysis of units from the perspective of the admin.
+
+### Potential Users:
+
+- Students: Primary users who will benefit from the personalized course planning and progress tracking features.
+- Course Directors: Utilize the platform to guide students in course selection and academic planning.
+- Universities: Benefit from improved communication and distribution of course-related information to students.
+
+### User Stories:
+
+- As a student, I want to visualize my course map so that I can easily track the units I need to complete to graduate.
+- As a student, I want to add elective units to my course map, allowing me to explore different subject areas while meeting my degree requirements.
+- As a course director, I want to ensure students can view all prerequisites and core units visually, helping them make informed decisions about their study plan.
+- As a student, I want to mark units as complete, ensuring that I can clearly see my progress and what remains in my course plan.