Draft Graphs

[zachberry]

Here's a place to keep track of some of our ideas / plans with introducing module maps to Obojobo.

Note on terminology: The term "Draft" is the internal term Obojobo uses to describe a "Module".

Draft Graph

This would allow modules in Obojobo to be connected to one another.

Specification

My first thoughts on a data-structure is this:

const graph = [
	{
		id: 'm1',
		requirement: null,
		destinations: ['m2'],
	},
	{
		id: 'm2',
		requirement: { type: 'score', value: 100 },
		destinations: ['m3', 'm4'],
	},
	{
		id: 'm3',
		requirement: { type: 'visited' },
		destinations: [],
	},
	{
		id: 'm4',
		requirement: null,
		destinations: [],
	},
]

This example defines a graph of 4 modules m1, m2, m3, and m4 (these would be draft_ids). Then each node of the graph specifies 0 or more destinations. Additionally each node can define a requirement that would need to be met to allow travel to that node (or in other words, would unlock the node). My current thought is that these are on the destinations themselves rather than on the path between the nodes, but this may need to change.

The requirements initially would only be of two types:

1. "score": In the example above, all paths to the m2 node would have to provide a score of 100% before travel would be allowed.
2. "visited": This means that all incoming nodes would need to have been at least viewed once.

If the requirement is null then that node can be visited freely at any time.

Later we could extend this by providing other types of requirements. Additionally, I assume this specification would change as we feel out what is needed.

These graphs, referred to internally as Draft Graphs would be stored as JSON.

Care would need to be taken not to allow cyclical graphs.

Database

I'm envisioning two new tables:

This structure mirrors drafts and drafts_content

1. draft_graphs: Represents a draft graph and the user who created it
2. draft_graphs_content: Keeps track of different versions or saves of a draft graph

Specifically:

draft_graphs:

id	user_id	created_at	deleted
UUID	The user who created the draft graph	Time of creation	Boolean

draft_graphs_content:

id	draft_graph_id	user_id	created_at	content
UUID	ID of the draft_graph	The user who saved this version of the draft graph	Time of creation	jsonb (Using the specification above)

API

API methods would be added to get, create, update and delete draft graphs. Likely these would mirror the existing API for drafts.

• GET /api/draft-graphs/:draftGraphId (Fetch a graph)
• POST /api/draft-graphs/new (Create a graph)
• POST /api/draft-graphs/:draftGraphId (Update a graph)
• DELETE /api/draft-graphs/:draftGraphId (Delete a graph)

Server Model

A new model would be created, likely mirroring the existing model for Drafts.

Limitations

This first phase of development would not allow sharing or collaboration of draft graphs. They also do not work with the current collections specification.

We could implement that by adding comparable "draft_graph" version of the tables that power sharing and collections, or modify these tables to allow for them to reference either draft graphs or drafts.

Instructor Draft Graph UI

We need a place for instructors to create, edit and delete draft graphs.

Listing, Creating, Opening and Deleting Graphs

The Dashboard would be the place to list graphs and allow instructors to create new ones, edit existing ones or delete them. For this first phase of development this may be rough, as long as there is UI in place to allow for these functions.

Editing a Graph Page

The page to build and edit a draft graph can use an off-the-shelf node graph library. It would need to allow for the following:

1. Modules (represented by nodes) can be added to the graph. Instructors will need to be able to search through their modules to add them to the graph.
2. Nodes should be able to be connected, ensuring that cyclical connections are not allowed
3. Nodes should be able to be clicked on to define requirements (currently this would only be a score requirement for this first phase of development)
4. Connections between nodes should be able to be changed or deleted
5. Ideally, the node graph should be restricted to a left-to-right (or maybe top-to-bottom) layout where the spacing of nodes is equal. Perhaps this is achieved by a 'clean up' button which organizes the nodes from a free-form layout to a calculated one.

This page would then have a button to save the newest version of the graph, or, to cancel and not save changes.

Limitations

• Since this will be an MVP product, we will not have the time/resources to perfect the UI to blend with the existing UX of the Dashboard page. Therefore we may want to hide this feature behind a feature flag: perhaps experimental.draftGraphs
• Version History / recovery (like with modules) likely won't be implemented in this phase of the project

LTI and Score Changes

Currently Obojobo is designed so that students click on an assignment or module item from an external LMS which launches them into a singular Obojobo module. This will need to be updated so that a launch from an LMS will put a student either into a single Obojobo module or a new draft graph page. There will likely be significant changes necessary to accommodate for this change! These are briefly described here but likely much more will be involved.

This new draft graph launch takes a student to the node graph of modules. The average score of every assessment (where assessments exist) is what would get sent back to the LMS gradebook as a singular value. For example, with a node graph of two nodes, each with assessment, the score sent back to the LMS gradebook would be:

(Assessment_Score_of_Module_1 + Assessment_Score_of_Module_2) / 200

In this example if one module is attempted (with a score of 50%), the score sent back to the gradebook will be (50 + 0) / 200 or 25%. It will be important in the student UI to communicate that any scores sent to the gradebook are in progress and will be updated as the student progresses. It will be easy for a student to get concerned when looking at grades that they have only a 25% (or failing) grade in that assignment.

Each module in the module graph will essentially be a unique resource link ID. It may make the most sense to implement each module in the graph as an LTI connection.

Student progress could be synthesized instead of stored based on the assessment scores of any completed modules. However we may need to store student progress either out of convenience or if it becomes necessary based on the addition of other types of requirements (in other words, other ways to unlock nodes).

Likely we will need to add to the API to provide the data we need for this interface and new way of student interaction.

Note on LTI Advantage / LTI 1.3

Recent updates to LTI allow for deep linking of LTI content as well as creating multiple gradebook columns. We likely won't have the development time to implement these, but I mention it here in case it's useful. Perhaps moving to these standards would make more sense then what's proposed above.

Student Draft Graph UI

While the first version of this can be very basic, it would need to communicate the following:

1. A clear orderly graph of connected modules
2. Which modules have been completed, which are not completed, which are locked and which have requirements that have not been satisfactory met yet.
3. Their overall progress (Potentially a progress bar, number, or percentage)
4. Their current total grade (It's important to communicate that this grade will start at 0% and only increase. The shock of a low grade will be concerning unless a student realizes that the calculation of that grade is including 0% scores for unvisited modules. Perhaps this could be offset by a total score that only accounts for modules where one or more assessments were completed)
5. Students can click on modules, which is how they jump into a module. Students then need to be able to leave the module and return to the node graph in a clear way.
6. The UI should be keyboard accessible and understood using a screen reader, using aria standards and section 508 compliance.

Miscellaneous

• Should the modules in the node graph be the latest version of that module or a specific targeted version?