Architecture Vision Document

Summary

As we discussed on our initial call, US Privacy laws are very strict around student information handling. As a result, I think the safest path forward for our initial development is to work on an account-free system. I’m open to suggestions here, but here is my initial idea:

Proposed Model

For our initial prototype, I propose our system should utilize randomly generated resource URLs as a method to persist completed work on the system. For each saved entity, two links can be generated: a read-only link that allows anyone to view the work at the time the link is generated, and an edit link which allows anyone with the link to resume editing their work.

A platform like etherpad is an example of a system that uses randomly generated URLs for permissioning. I assume our system would want to create our randomly generated URLs using something like a SHA256 hash, but I’m open to whatever works (it just should not be easily guessed).

Approach

The first priority for the backend will be the ‘student’ view. This view starts as an essentially blank workbook for only a single math problem. The use case is as follows:

• A student gets a math problem assignment from their teacher. This problem can come in any form: on paper worksheet, from a textbook, sent over a digital medium, written on the chalkboard, etc.

• The student visits the student endpoint of the MathShare platform.

• When the endpoint loads, the ‘edit’ permission link is displayed somewhere on the page accompanied with a note such as ‘retain this link to edit your work in the future’.

• As the student adds steps, these values are automatically added to the database and are associated with the edit URL

• The student may visit the edit link at any time to resume editing their work

• At any point, the student is afforded a ‘share problem’ button. This returns a different randomly generated URL that (when visited) presents a read-only version of the problem at the time the button was clicked.

• Subsequent clicks of the share button would generate an additional, different URL that reflects any changes that may have been made.

In a later stage, we likely will need to build the ‘teacher’ endpoint for the platform and allow for sets of problems. This workflow will revolve around allowing for the creation of sets of problems, and the ability to share these problem sets with their students. The workflow might look as so:

• A teacher visits the ‘create problem set’ endpoint on MathShare. On this view of the platform, a teacher is presented with a blank problem set.

• When the view loads, the ‘edit’ permission link is displayed somewhere on the page accompanied by a note such as ‘retain this link to edit this problem set in the future’

• The teacher may visit the edit link at any time to resume editing the problem set

• A teacher can add multiple problems to a problem set. A problem is (at this point) defined as simply a text field which may include some math symbols/markup.

• Once a teacher has added all their questions, they can hit the ‘Share Problem Set’ button that will generate a unique URL for the state of the problem set at the point the button was hit.

• Subsequent clicks of the share button would generate an additional, different URL that reflects any changes that may have been made.

The ‘share’ link for a problem set is not read-only, but rather is ‘answerable’. When a student clicks the shared problem set link, it should generate a new unique URL for the student to allow the student to begin answering the problem set. Similar to the original ‘student’ view, the problem set should have an ‘edit’ link associated with it that allows a student to resume their work. As before, the student should be able to click a ‘share’ button to generate a read-only version of their answered problem set at the time the share button was clicked.

Justification

This set-up should allow for initial classroom testing to proceed on the platform. The links can adequately serve as integration into most classrooms’ existing systems. Teachers can digitally send their problem set URLs to their students on their existing LMS system. Student response URLs can be submitted back to the teacher via the LMS, or we can work on a print-out/download function to offer more options for submission.

By recording all steps created in the system under edit links, we also satisfy the majority of our requirement around analytics for an initial version.

If in the future we decide we need to build out API endpoints for MathShare, I believe these randomly generated hashes could easily serve as an ID for GET/POST requests, and more than likely should be a relatively small change to build out API endpoints.

If we decide at some point to add user accounts to the system (for either students, teachers, or both), it should be relatively easy to add a User->Random Hash join table that allows for easy retrieval of work associated with an account. We could also prohibit edit access on hashes that appear in the join table without authentication. This could even work retroactively allowing authenticated users to ‘claim’ existing edit links and associate them with their account.