Design Documentation
[Design Documentation - 2023/12/10, version 1.4] : Final change for submission
[Design Documentation - 2023/12/3, version 1.3] : User Story Updated and minor change
[Design Documentation - 2023/11/12, version 1.2] : User Story Updated
[Design Documentation - 2023/10/22, version 1.1] : Mission Updated
[Design Documentation - 2023/10/8, version 1.0]
Our project consists of frontend and backend, and it will depend on external services for some features. Screen view will be implemented with Android Studio. Backend will be built using Django, with model biding MySQL, and our server will be deployed using AWS.
Furthermore, one of the most crucial aspects we need to implement in creating our application is real-time tracking of the user's location and determining whether the user is actually running or using another mode of transportation. To achieve this, we intend to utilize the Google Maps API and the Activity Transition API. By leveraging these tools, we anticipate that we will be able to provide users with more accurate information.
And one of our two main features, the single mission mode, utilizes TensorFlow Lite to recommend learning objectives tailored to the user's experience through a machine learning model designed directly. In the other main feature, the multimode, we implemented real-time socket communication through a socket server designed in Java.
This is a ER diagram based on Django. Each tables stands for one Django model, and each pair of varaiable name and type in model stands for field.
- postLoginData() : posts login data to the server and retrieves user information.
- sendMail() : sends a temporary password to the user's email after verifying their identity.
- permissionCheck() : checks if all required permissions are granted.
- showPermissionDialog() : displays a dialog if any permissions are not granted, prompting the user to grant them.
- postSignUpData() : sends user-provided sign-up data to the server for account creation.
- findUserName() : finds and retrieves the user's ID using their email address.
- sumQueue() : processes the accumulated data in a queue.
- showModeChoice() : presents the user with the different available modes of single-mode play to choose from.
- showCustomDialog() : presents a custom dialog box to the user.
- showMarathonDialog() : shows the marathon dialog for marathon mode options.
- showTimeAttackDialog() : displays the time attack mode dialog for the user.
- setRunningStart() : prepares and sets the running activity to start.
- saveHistoryDataOnSingleMode() : saves the activity data once the single mode session is completed.
- getMission() : fetches the current mission or task for the user.
- finishPlaySingleMode() : concludes the single mode session.
- showModal() : displays a modal window for additional information or actions in the multiplayer mode.
- navigateRoomWait() : manages the navigation and UI updates during the waiting time in a multiplayer room.
- getRoomListTask() : retrieves a list of available multiplayer rooms for the user to join.
- sendRoomInfoTask() : sends the selected room information to the server to join a multiplayer game session.
- startGame() : initiates the multiplayer game.
- showExitDialog() : displays a dialog when a user attempts to exit the multiplayer session.
- updateParticipantCount() : updates the current count of participants in the room.
- addUserNameToWaitingList() : adds a new user's name to the waiting list for a room.
- makeNotification() : creates notifications for multiplayer session events.
- removeUserNameFromWaitingList() : removes a user's name from the waiting list.
- getRandomQuotes() : selects and displays a random motivational quote to the user.
- loadMonthlyData() : loads the user's activity data for the current month.
- parseStringToCalendar() : converts string data into a Calendar object.
- updateUIWithMonthlyData() : refreshes the user interface with the monthly data.
- loadDailyData() : retrieves and loads the user's daily activity data.
- updateUIWithDailyData() : updates the interface with the daily data.
- findDailyData() : searches for and finds the data pertaining to the current day.
- formatDuration() : formats the time duration data into a readable format.
- addMarkerForDaysWithHistory() : adds a visual marker on the calendar for days with recorded activity.
- resetDailyUI() : resets the daily UI elements for a new day's data.
- logoutUser() : logs the user out of the application and redirects to the LoginActivity.
- uploadImageToServer() : uploads a selected image to the server as the user's profile picture.
- updateProfileImageView() : updates the display with the new profile image.
- updateBadge() : refreshes the display of the user's achievement badges.
- openImageChooser() : opens an interface for the user to select an image for their profile.
- sumQueue() : Processes queued data for the game.
- showExitGameDialog() : Displays a dialog when exiting the game.
- updateTop3UserDistance() : Updates the leaderboard with the top three players' distances.
- saveHistoryData() : Saves the current game's data to the player's history.
- saveGroupHistoryData() : Saves multiplayer game data related to group activity.
- calculateMedian() : Calculates the median value of a data set, such as player scores.
- transitionToResultFragment() : Transitions the view to show the game results.
- startRemainTimer() : Starts a timer for remaining time in the game session.
- showExitResultDialog() : Presents a dialog box when attempting to exit the result screen.
- updateTop3UserDistance() : Refreshes the leaderboard for the top three distances.
- showLevelUpDialog() : Displays a dialog if the player levels up after the game.
| Model | API | GET | POST | PUT | DELETE |
|---|---|---|---|---|---|
| users | api/sign_up | x | create new user | x | x |
| api/sign_in | x | sign in | x | x | |
| api/sign_out | sign out | x | x | x | |
| api/find_id | x | find_id | x | x | |
| api/reset_password | x | reset_password | x | x | |
| api/user | get user info | x | patch user info | x | |
| history | api/user/history | get user history | save user history | x | x |
| api/user/badges | get badges of a user | save new badge of a user | x | x |
Model Structure: Recurrent Neural Net
Dataset: FitRec-Project Dataset
Data includes multiple sources of sequential sensor data such as heart rate, speed, GPS as well as sport type, user gender and weather condition. Our team used only selected features from dataset.
(Jianmo Ni, Larry Muhlstein, Julian McAuley, "Modeling heart rate and activity data for personalized fitness recommendation", in Proc. of the 2019 World Wide Web Conference (WWW'19), San Francisco, US, May 2019.)
Data Cleansing & Preprocessing: The records corresponding to running & users with more than 5 records were included. After removing some outliers (Total records: 70299), it was not running data that grew as desired, but actual records of people running were collected aimlessly. To prevent severe fluctuations and output decreasing, we take Exponentially Weighted Moving Average (EWMA) for input. This design choice is theoretically backed up by the assumption that random factors on dataset such as runner's condition, weather, etc are unpredictable, however will indeed have zero expected value on average.
Input: 20 continuous running records (distance & time)
Label: Next running's distance/time
Training: Trained for 30 epochs by adap optimizer with learning rate 0.01
Test result:
Inference: recommendation model suggests future running goals based on the most recent 20 running records. After converting it to TensorFlow Lite, the goal recommendations for each user are executed on-device. The reason for this is, first, a longer data transmission path would negatively impact the user experience, and second, there are concerns about privacy invasion regarding running records.
Cold Start Problem: Since the next recommendation can only be created when the user has a record, a 12-minute run is provided as a goal for users without a record. In the case of 12-minute running, criterion validity has been proven in various ways (유영란.(2011).최대산소 섭취량을 예측하기 위한 셔틀런 검사와 Cooper 12분 달리기의 준거타당도.한국체육측정평가학회지,13(2),95-104.) It is also used at public health centers in Korea to measure cardiorespiratory fitness. (https://www.ydp.go.kr/health/contents.do?key=3648&) In the case of a 12-minute run, the evaluation criteria are different for each age group. So according to research showing that obesity is the cause of decreased metabolic ability, the higher the user's BMI, the lower the goal by one grade in the evaluation standard. (정윤주, 신진희, 김경수, 박진희, 송찬희, 최환석, 염근상. (2003). 비만지표와 체력요인의 상관성. Korean Journal of Family Medicine, 24(3), 9-278)
Actual Recommendation Example
| Trial | Distance | Duration |
|---|---|---|
| 1 | 2.1 km | 00:13:20 |
| 2 | 2.2 km | 00:15:00 |
| 3 | 2.3 km | 00:15:00 |
| 4 | 2.4 km | 00:15:50 |
| 5 | 3.0 km | 00:24:30 |
-> Recommendation: 2.5 km, 17 minutes
1-1. If the user, who received the above 1st recommendation, runs 2.9 km / 20:50 min
| Trial | Distance | Duration |
|---|---|---|
| 1 | 2.9 km | 00:20:50 |
-> New Recommendation: 2.6 km, 20 minutes (Goal Increased)
| Trial | Distance | Duration |
|---|---|---|
| 1 | 2.2 km | 00:13:20 |
| 2 | 2.3 km | 00:13:20 |
| 3 | 2.4 km | 00:13:20 |
| 4 | 3.0 km | 00:13:20 |
| 5 | 3.5 km | 00:13:20 |
-> Recommendation: 2.7 km, 14 minutes
2-1. If the user, who received the above 2nd recommendation, runs 1 km in the same duration
| Trial | Distance | Duration |
|---|---|---|
| 1 | 2.1 km | 00:12:00 |
-> Adjusted Recommendation: 2.1 km, 12 minutes (Goal Decreased)
Every components, classes, and functions would be tested using following frameworks and libraries.
Main business logics and complicated logics are implemented in Django view and serializers. So, Our aim is to maintain the Django coverage over 90%. And Android's testing goal is to do as much as we can cover.-
Android Studio
- Unit test : Junit
- UI test : Espresso
-
Django
- python unit test
We chose 5 user stories for user acceptance test.
As a new user, I want to create my account and login so that I can use the app. The system should authenticate my id and password. As a user, I also want to find my id and password using my email address. Additionally, I want to change my password whenever I want.
Given I am a new or existing user of the Runus app,
When I interact with the account creation, login, and password management features,
Then the following criteria should be met:
- As a new user, I can create an account by providing a unique username, email address, and setting a password.
- Upon successful account creation, I receive a confirmation message.
- As a registered user, I can log in by authenticating my username and password.
- If I enter incorrect login credentials, I receive an error message.
- If I forget my password, I can request a reset through a 'Forgot Password' feature using my email address.
- I can successfully reset my password using the instructions received via email.
- If I forget my username or password, I can use my email for account recovery, receiving my username and a password reset.
- I receive clear notifications or messages confirming successful actions like account creation, logging in, password resetting.
As a user seeking to enhance my solo running experience by setting personalized goals beyond just time and distance, I can utilize the Single Mode's Custom Mode in RunUs. Within the Custom Mode, I can input specific distance and time targets, allowing me to track my progress in real-time during the run, including pace, distance, and time. Upon completion, I can review my final performance metrics. Additionally, the RunUs application incorporates an experience points system, providing an opportunity for leveling up based on achievements in each run. After finishing a run, I can check my gained experience points on the My Page section.
Given I am a user seeking to enhance my solo running experience,
When I interact with the Single Mode's Custom Mode in RunUs,
Then the following criteria should be met:
- In the Custom Mode, I can set personalized goals including specific distance and time targets.
- During my run, the app should provide real-time tracking of my progress, including pace, distance, and time.
- Upon completing a run, I can review my final performance metrics within the app.
- The RunUs app incorporates an experience points (XP) system that rewards me for achievements during each run.
- After finishing a run, I should be able to check the experience points I have gained in the 'My Page' section.
- The app should provide a system of leveling up, where my achievements in runs contribute to my overall progress.
As a user looking to make running more engaging, I'd like to receive missions in Single Mode, recommended by RunUs's mission recommendation model. These missions would change each time based on my records, allowing me to enjoy workouts that involve more than just time and distance
Given I am a user looking to make my running experience more engaging,
When I use the Single Mode in RunUs,
Then the following criteria should be met:
- The RunUs app should offer me missions in Single Mode, which are recommended by its mission recommendation model.
- These missions should be dynamic and change each time I use the app, based on my previous running records.
- The missions provided should offer varied workout experiences, focusing on aspects beyond just time and distance.
- The app should be able to tailor these missions to suit my fitness level and running history, ensuring they are both challenging and achievable.
As a user who wants to run with others, I can enter an existing multi-mode room. The game will start when the designated start time is reached. During the game, I can receive real-time updates on other participants' records and rankings, and check the results at the end of the game
Given I am a user who wants to run with others,
When I interact with the multi-mode feature in RunUs,
Then the following criteria should be met:
- I can easily enter an existing multi-mode room in the RunUs app.
- The run or game in the multi-mode room starts automatically at the designated start time.
- During the game, I should receive real-time updates on the records and rankings of other participants.
- The app should provide a user-friendly interface for viewing these real-time updates.
- At the end of the game, I can check the final results, including my own performance and the rankings of top3 participants.
- The app should ensure that the real-time updates are accurate and timely, enhancing the competitive and communal aspect of the run.
As a user who needs extra motivation to continuously exercise, I can earn experience points (exp) to level up, or gain badges by meating some goal criteria while using our app (such as winning multimode race for preset number of times), so that user can get some extra motivation by feeling more achievements.
Given I am a user needing extra motivation to continuously exercise,
When I use the RunUs app for my workouts,
Then the following criteria should be met:
- I can earn experience points (EXP) for various running and achievements within the app, contributing to my overall level-up process.
- I can gain badges by meeting certain goal criteria, which could include winning a multi-mode race a preset number of times or achieving specific fitness milestones.
- The criteria for earning badges should be challenging yet achievable, encouraging continuous effort and improvement.
- Each badge should have a unique design and significance, making them desirable and a symbol of achievement.
- The app should provide a section where I can view my accumulated experience points, current level, and the badges I have earned.
- The level-up system and badges should serve as motivational tools, offering tangible rewards and recognition for my efforts and achievements in exercising.
We conducted a survey with 31 participants. It includes their age group, exercise frequency (per week), expectations regarding our app's features, and satisfaction with the sample results.
- 83.9% of respondents expect about an app that allows them to set personalized goals (agree/strongly agree)
- 77.4% of respondents expect multi-mode learning to increase running effectiveness (agree/strongly agree)
- 80.6% of respondents responded that the sample goal recommendation generated by RunUS was appropriate (agree/strongly agree)
