Achievement System Developer Guide
This is the developer guide for the Source Academy's Achievement System.
This developer guide assumes basic familiarity with React, Redux-Saga
- Important Notes to know
- Achievement System Structure
- Achievement Dashboard Components
- Achievement Control Components
- Interactions of Components
- Achievement Store
All the source code of the achievement system can be found in src/commons/achievement, src/features/achievement and src/pages/achievement of this repository.
The key objectives of the Achievement system are:
- Create a sense of progress for the students
- Incentivize good learning behavior
- Monitor student's academic performance
All the development of the Achievement system follows two main guidelines:
- The Achievement system UI should be useful, intuitive and user-friendly without having to read a user guide or ask the developer.
- Exercise good software principles and strictly adhere to the Source Academy Coding Standard.
Issues and bugs report should be reported normally through Github Issues. Please tag the issue with achievement label so the team can identify it easily.
The Achievement system consists of 4 main features:
- Achievement Dashboard
- Achievement Control
- Leaderboard (KIV)
- Performance Lab (KIV)
The Achievement Dashboard is the homepage of the Achievement system. Students can view their current XP progress and detail of every achievement such as completion criteria, potential XP reward, difficulty and other relevant information. Staffs can modify student's achievement progress via the Achievement Dashboard.
The Achievement Control is the control panel of the Achievement system for the staffs to create, edit and remove achievements.
The Leaderboard displays an overview of the cohort's XP and the student's XP ranking in real time. This feature is still under planning phase and is not developed yet.
The Performance Lab provides analytics tools to analyse student's academic performance and achievement progress. This feature is still under planning phase and is not developed yet.
Below is a screenshot of the Achievement Dashboard Beta testing page annotated with the name of React components. The actual site should look similar to the Beta page.
The main React function of the Achievement Dashboard is located at \pages\achievement\subcomponents\AchievementDashboard.tsx. You should be able to identify the React components from there.
Below is a screenshot of the Achievement Control Beta testing page annotated with the name of React components. The actual site should look similar to the Beta page.
The main React function of the Achievement Control is located at \pages\achievement\control\AchievementControl.tsx. You should be able to identify the React components from there.
Achievement related data are fetched and updated to the Source Academy Backend. Additionally, image assets such as achievement card background, cover image, etc. are uploaded to the AWS S3 server for performance issue.
The Achievement Dashboard & Control containers use a helper function called Achievement Inferencer to encapsulate and infer useful information for the child components.
The Achievement State in the frontend Redux Store consists of 2 arrays: achievements[] and goals[]
Each AchievementItem in the achievements[] represents an achievement.
| AchievementItem | Data Type | Description |
|---|---|---|
| id | number | unique id of the achievement item |
| title | string | title of the achievement item |
| ability | AchievementAbility | ability of the achievement |
| deadline (Optional) | Date | deadline of the achievement |
| release (Optional) | Date | release date of the achievement |
| isTask | boolean | if true, the achievement is rendered as an achievement task |
| position | number | ordering of the achievement task, 0 for non-task |
| prerequisiteIds | number[] | an array of prerequisite ids |
| goalIds | number[] | an array of goal ids |
| cardBackground | string | background image URL of the achievement card |
| view | AchievementView | the achievement view |
Each AchievementGoal in the goals[] represents a goal.
| AchievementGoal | Data Type | Description |
|---|---|---|
| id | number | unique id of the goal |
| text | string | goal description |
| meta | GoalMeta | metadata of the goal |
For more information please refer to \features\achievement\AchievementTypes.ts