Developer Guide - Orbital-Knewbie/Knewbie GitHub Wiki

1. Setting up
2. Design
    2.1. Architecture
    2.2. Model component
    2.3. View component
    2.4. Controller component
    2.5. Database
3. Implementation
    3.1. User
    3.2. Quiz
    3.3. Adaptive Testing
4. Documentation
5. Testing
6. User Stories
7. Frequently Asked Questions (FAQ)

Refer to the guide here.

Flask is a micro web framework written in Python. This Web App makes use of the framework for its overall design. The rationale behind choosing Flask may be found in the Development Practices document. The explanation of the diagrams used in this Guide can be found in the Documentation section below.

Fig 1. Overall Architecture

The Model-View-Controller (MVC) is a software design pattern that divides the program logic into the components. While some of the components may have some overlap with the others due to the nature of the Flask framework design, the Web App can still be said to consist of these three main components.

• Model: Manages data, logic and rules of application
• View: The representation to the users
• Controller: Converts input to commands for Model or View

CRUD (Create, read, update and delete) are the 4 basic operations of persistent storage and will be a basis for all operations done.

The Web App will use the RESTful API architectural style to perform its HTTP requests.

The Sequence Diagram below shows how a POST request for a RegistrationForm - registering for an account - will cause the different components to interact.

Fig 2. Component Interactions for register

The Model component includes files:

├── *
    └── forms.py
├── models.py
├── quiz
    └── cat.py
└── ...

Fig 3. Structure of Model components

The Model component

• stores User data.
• stores Question, Option, Answer data.
• defines the various FlaskForms used.
• defines Student used in CAT, explained under Implementation
• does not depend on the other components.

The FlaskForm is used in two scenarios. They are converted into <form> tags and fields in HTML and allow POST requests to be made, with built-in CSRF protection. These requests may or may not include data with them, depending on the use case.

The View component includes folders (and all the files within them):

├── templates
    └── ...
├── content
    └── ...
└── ...

Fig 4. Structure of View component

The View component consists of the HTML templates along with CSS styling. Templates also have Jinja syntax, which is a templating language. Under the Flask framework, the Jinja syntax acts as part of the Controller component, changing the view logic depending on inputs from the Model component.

The View component

• Executes user commands using the Controller component
• Updates with changes to the Model data

The Controller component includes files:

├── *
    └── views.py
├── decorator.py
├── quiz
    └── questions.py
├── *
    ├── email.py
    └── profile.py
├── token.py
├── forum
    └── forum.py
├── group
    └── group.py
└── ...

Fig 5. Structure of Controller Component

The Controller component converts input from View to commands for Model and vice versa. The files in this component consist of functions to control the logic of the application, ranging from email verification to quiz question generation. It is important to note that in Flask, there is a file specific to route the various URLs along with their HTTP methods to the right function - which in this case is views.py. This function can display a webpage (View component), or redirect to another function. As such, the main interaction between the View and Controller component will happen here. The other files under the Controller component would then be mainly used to interact with the Model component.

1. Controller uses views.py to route the URL.
2. Correct route function is called (e.g. as a GET or POST request).
3. Function carried out can affect the Model.
4. The result will be seen in the View component as a HTML webpage, either from a redirect or an update to the WebPage itself.

The Sequence Diagram below shows the interactions within the Controller component for the submission of the RegistrationForm using a POST request from /register.

Fig 6. Interactions within Controller Component for register

The database design is centered around the users, quizzes, and forum posts. The Entity-Relationship (ER) Diagram below showcases the attributes and relationships used. Explanation of the diagram can be found under the Documentation section.

Fig 7. Database Design

This section describes some noteworthy details on how certain features are implemented.

An overview of user registration had already been provided under the Architecture and Controller sections earlier. In essence, it takes 4 steps:

1. Submission in View component
2. Validation check in Controller component
3. Register in Controller component
4. Create user in Model component
5. Save to database

In line with modern practices, there is also email verification, which verifies that the email used belongs to whomever had registered. Immediately after the above steps are taken, the User account is still unconfirmed, and certain features will not be accessible. Trying to do so will result in the following page.

Fig 8. Unconfirmed webpage

Using the ItsDangerous module, a token is generated and a clickable confirmation link will be available from the user's email. From the Database Design, the User properties confirmed and confirmed_on will be updated when the account is confirmed, to be True and the current datetime respectively. In case a user forgets their password, or had their account compromised, there is a reset password feature available. Similarly, the reset password feature also uses the same module to produce the secure tokens to provide the links used.

Account details include the user's login information, name, and statistics having to do with the quizzes.

• Currently, there are 2 different types of a User that can register for an account in the application - Student and Educator.

Overall, account details can be retrieved simply by doing a GET request at the appropriate URLs provided that the user is authenticated. Updating and/or deletion of the account can be explained quite similarly to the registration procedure mentioned, in that there is the submission, validation, and saving of the information being updated. Details can be found in the User Guide.

The Contact Us page is also another example of the FlaskForm being used - in this case to communicate with the technical team. Provided is the Sequence Diagram for a POST request for a ContactForm.

Fig 9. Interactions of Components for a ContactForm

Both Students and Educators can be part of Classes. Classes are created to let Educators monitor their students progress collectively, and also can allow interaction between Educators and Students as well as Students with other Students using the forum. A simple demonstration of a Student-Educator relationship, along with the Classes is shown in the ER Diagram below. Note that the User properties were omitted for brevity - the full database design can still be found earlier in the Database section.

Fig 10. Relationship of Student-Educator-Class

In the creation of a Class, the Educator will input a name and click a button leading to it being saved in the database. Further information can be found in the User Guide (Educator).

Interactions between are part of peer learning and can enhance the knowledge gained from the platform. The forum created for each class will allow for the clarification of questions students may have. The diagram above also demonstrates the relationships between the forum and the users.

The tailored quiz requires the use of an Adaptive Testing feature which aims to provide tailored content to suit the user's ability, explained in a later section. Overall, there is a large similarity to previously mentioned features in terms of the interaction with the addition of the Adaptive Testing feature. Below is the Sequence Diagram in completing a quiz.

Fig 11. Interactions of Components for a Quiz submission

In addition to tailored content, Educators can also create their own Question for their own Class. The ER Diagram below zooms in on the relationships used in the creation of quizzes by an Educator.

Fig 12. Relationships of Educators and Quizzes

In creating a Quiz, and its questions, the interactions can be shown in the following Sequence Diagram.

{Create Quiz Sequence}
Fig 13. Interactions of Components for a Quiz Creation

When attempting a quiz created by an educator, it is different from the general quiz mentioned in the earlier Section 3.2.1. In this case, there is no adaptive testing, so the questions are given as they were added by the educator. The User Guide (Educator) demonstrates the creation of such a quiz, and the User Guide (Student) showcases attempting the quiz. To the Student, both quizzes are similar in front-end design. The only difference is the back-end implementation of retrieving the next question.

Separate to quizzes created by an Educator, the platform also supports the following feature which allows tailored content in the quizzes. Computerized Adaptive Testing (CAT) is a form of test that adapts to the user's ability. Item Response Theory (IRT) provides a means to do so, and this project has decided on the use of the CatSim Python package. More information can be found on their main documentation.

Under IRT, an examinee's proficiency is measured. In this web application, this corresponds to the students' proficiencies. Each item administered - MCQ Math questions in this case - will have 4 main parameters used, detailed below:

• discimination - how well an item discriminates individuals who answer correctly and wrongly
• difficulty - same scale as proficiency, and determines which proficiency level the item would be more informative
• pseudo-guessing - probability low proficiency gets question correct
• upper asymptote - probability high proficiency gets question incorrect

More information on the parameters can be found on CatSim's documentation.

Use of CatSim can be found in the files:

└── quiz
    ├── cat.py
    └── questions.py

DISCLAIMER: The proficiency and parameters used in Knewbie's current implementation have no research behind them. Due to the limited resources of the development team, the CatSim provided function catsim.cat.generate_item_bank was used to create simulated parameters for the questions, and catsim.initialization.RandomInitializer().initialize() was used to generate simulated proficiencies for each user. In the future, post-Orbital, it may be possible to obtain a much larger dataset with more accurate parameters.

The general idea used when administering questions can be seen in the following flowchart. This algorithm is used in the general quizzes that will be taken by a student. Educator-created quizzes do not use this feature and are detailed in the earlier section.

Fig 14. Flowchart of general adaptive testing algorithm used

The Diagrams in this Guide were created and defined with PlantUML. The source code can be found in the diagrams folder.

The Class and Sequence Diagrams used have their own notation and can be explained with the help of the CS2103 Software Engineering website.

Class Diagrams include:

• Class Names
• Attributes
• Methods

Fig 15. Class Diagram Notation

Sequence Diagrams show the sequence of events as time events and include, for a specific operation:

• Entities
• Operations
• Activation Bars
• Lifelines
• returned values

Fig 16. Sequence Diagram Notation

The Entity Relationship Diagrams used to describe databases include:

• Entities - represented by rectangles, properties can be found listed right after the primary key property
• Relationships - represented by diamonds
• Cardinality - using the Information Engineering Style for its notation

Fig 17. Entity Relationship Diagram Notation

For this section, the team also obtained information from CS2103 SE Book Adapated to aid us in understanding the different types of Testing involved, which may also prove useful to the reader.

With the constant updates to the code, there is a need to conduct Unit Testing to ensure that sections of the code continue to work. This project uses the unittest module provided by Python to carry out the tests. As an example of testing, using the following command, we will be able to see our test results from the command line.

nose2 -v

Fig 18. Unit Testing Knewbie

Codecov is a tool that goes hand in hand with Unit Testing, and will check for the test coverage of the codebase, based on the Unit Tests. This allows the developers to understand which areas of the code may need more attention and possibly rigorous testing.

Along with the Unit Tests, the project also Travis CI, which allows Integration Tests to be done when merging code while using version control. Together with the protection of the master branch, Travis then ensures that bugs that affects the building of projects to be caught.

Priorities: High (must have) - * * *, Medium (good to have) - * *, Low (not significant) - *