chore: ADRs

muselesscreator · muselesscreator · commit 5a61aa2edbee · 2024-01-02T18:46:33.000Z
diff --git a/docs/decisions/0001-run-environment-decisions.md b/docs/decisions/0001-run-environment-decisions.md
@@ -0,0 +1,24 @@
+1. Run Environment Decisions
+-----------------------------
+
+Status
+------
+Accepted
+
+Context
+--------
+We would like a historical record of decisions about the run environment for the app as it evolves over time.
+
+Decision
+---------
+This app is designed to be run within the context of the Learning MFE (@edx/frontend-app-learning) as an embedded view for Open Response Assessment (ORA) xblocks.  It consists of a base (`xblock`) view rendered in an iframe **within the Learning MFE’s unit display iframe**
+
+This view (the **xblock** view) provides high-level configuration and progress information about the ORA, and allows the user to jump to the current active step (or certain previous steps that may be re-visit-able) in a “distraction-free” modal experience.
+
+The modal is launched **by the Learning MFE**, triggered by a message sent from the **xblock** view (using JS `postMessage` interface to communicate across iframe boundaries).
+
+The modal view allows the learner to work their way through the assessment process for a submission and review their grades when available.
+
+Consequences
+------------
+Environments that run this MFE **outside of the learning MFE** will not be able to approprately render this navigation scheme without creating some kind of listener for the `plugin.modal` message sent over `postMessage` to open the "modal" views from the **xblock** view.
diff --git a/docs/decisions/0002-app-specific-terms.md b/docs/decisions/0002-app-specific-terms.md
@@ -0,0 +1,24 @@
+2. App-Specific Terms
+---------------------
+
+Status
+------
+Accepted
+
+Context
+--------
+We would like to keep a record of app-specific terms that may otherwise be overloaded in technical contexts.
+
+Decision
+--------
+In the context of this app, we will use the following terms in the associated ways:
+
+**Assessment** refers to the interactive form for filling out an assessment.  These can be either editable or read-only.
+* Assessment views will load the top-level `Assessment` component from `src/components/Assessment` and it will determine the appropriate
+* The `Graded` view specifically renders a set of read-only assessments directly from `src/components/Assessment/ReadonlyAssessment`.
+
+**Response** refers to a learner/team’s response to the ORA prompt (that which is graded in assessments).  
+* In Assessment views, the loaded `response` is the one being graded.
+
+**Rubric** refers to the definition data for assessments.  this includes all of the metadata for criteria and options.
+* the `Rubric` component from `src/components/Rubric` is used for the Submission view, where we want to display the assessment metadata without providing interactive fields for filling out an actual assessment.
diff --git a/docs/decisions/0003-tech-stack-decisions.md b/docs/decisions/0003-tech-stack-decisions.md
@@ -0,0 +1,40 @@
+3. Tech Stack Decisions
+------------------------
+
+Status
+------
+Accepted
+
+Context
+-------
+We would like to keep a historical record of decisions about the tech stack for this app as it evolves over time.
+
+Decision
+--------
+We will use the following technologies in this app:
+**redux**
+We use redux in this app to track top/app-level data.  This includes submitted assessments, submission status, validation status, and active form fields.  Our redux implementation has a single `app` reducer, with a small set of actions and selectors, which are loaded through hooks before access in components.  These hooks are then forwarded through app-level hooks under `src/hooks` in a hook file based on the the areas they touch.
+
+**@reduxjs-toolkit**
+We use a simple utility library wrapped around the basic redux functionality to provide cleaner action definition and memoized selector creation, following with edX frontend engineering practices.
+
+**@tanstack/react-query**
+We use Tanstack’s react-query library in this app to manage and track upstream api data.  This allows us to manage static upstream data in a distinct data environment from the app-level data, and provides built-in memoization and tracking of network event status.
+
+**jest-when**
+We use jest-when in this app to manage mock behavior in tests, especially in Typescript tests, where inspecting mock method usage is diffucult otherwise.
+
+**@edx/react-unit-test-utils**
+We use a small testing utils library to provide:
+* mocks and mock utils for messaging and various hooks/libraries
+* `StrictDict` utility for keystores that complain when called with invalid keys (reduces/simplifies bugs)
+* Snapshot/validation library for components, similar to enzyme, but based on still-supported technology.
+
+**@edx/frontend-platform/i18n**
+We use the edX `frontend-platform`'s internationalization (i18n) library to manage message translation.  All user-facing strings in the app should be wrapped in `formatMessage` calls, provided by the `useIntl` method in the above library (forwarded from `react-intl`).
+
+**@edx/frontend-platform/auth**
+We use the edX `frontend-platform`'s authentication library to manage authenticated communication with edX backend services.
+
+**@edx/frontend-platform/react**
+We use the edX `frontend-platform`'s `React` library to provide app-level setup code, wrapping the app in top-level componentry that allows the app to respond to the state of its connection the the devstack.
diff --git a/docs/decisions/0004-architecture-decisions.md b/docs/decisions/0004-architecture-decisions.md
@@ -0,0 +1,73 @@
+4. Architecture Decisions
+-------------------------
+
+Status
+------
+Accepted
+
+Context
+-------
+We would like to keep a historical record on the architectural decisions we make with this app as
+it evolves over time.
+
+Decision
+--------
+# `constants/` directory
+* `src/constants`
+  * `stepNames` is a keystore of names for discrete steps within the ORA lifecycle
+  * `stepRoutes` and `routeSteps` are objects that map `stepName`s to `route` strings and back
+    * these route strings are the base of the uri for the different views
+  * `stepStates` is a keystore of available states for a step to be in.
+    * This includes 2 ui-only states: `submitted` and `trainingValidation` which are used locally on consumption to override the value passed from upstream API based on local state.
+  * `MutationStatus` is a keystore of available values for tanstack mutation statuses
+  * `feedbackRequirement` is a keystore of available values for feedback requirement fields.
+  * `closedReasons` is keystore of available values for `closed_reason` data for an ORA step
+  * `queryKeys` is a keyStore that provides root query Keys for tanstack fetch queries.
+* src/constants/mockData
+
+# `views/` and `components/` directories
+* The `views` folder specifically holds top-level views for the app.  The goal of this folder is to provide a location where engineers can look for the top-level access-points of the app (minus the actual arch/data setup from the `App.jsx` component.
+  * Components that are ONLY used within the confines of a single view may be defined as children of that view’s code directory
+* The components directory holds all re-useable components that are accessed/used across views.
+  * These components may have children
+    * (`Assessment/ReadonlyAssessment/AssessmentCriterion.jsx`, etc)
+  * They may also be interdependent
+    * `Rubric` and `Assessment` both use/leverage the `CriterionContainer` component for different uses.
+
+# `data/` directory
+This directory houses the various data models for the app.
+
+`data/redux` houses the redux app reducer and selectors, used to track assessment, form, and submissions tate.
+
+`data/services/lms` houses the LMS service code, which has its own section in this doc.
+
+# `hooks/` directory
+Provides a top-level set of hooks for non-component-specific behaviors and data access.
+
+## `assessment` hooks
+This is a set of hooks specifically targeted towards data and behavior necessary for the running and displaying of assessment steps in the UI.
+
+It provides hooks that communicate between the redux data storing assessment form data and just-submitted assessments and the lms service shooks to manage tasks like:
+* Providing arguments for form field components
+* Providing `isInvalid` check for the assessment
+* Submitting assessments
+
+## `actions` hooks
+Provides the props for paragon `Button` components for “simple” (instant) actions and props for `StatefulButton` components for asynchronous tasks.
+
+Provides local message configuration and internationalization.
+
+These hooks are used in various components and are written to try and provide their relevant functionality dependent on the current app state.
+
+Actions (buttons) include: Finish Later, Exit, Start next step, Load next response in current step.
+
+## `app` hooks
+This module forwards app-level selectors and action hooks from lms service and redux for app-level data.
+
+This is the core place for components that can be run from anywhere in the app to be able to draw app state.
+
+## `modal` hooks
+This module provides a pair of hooks to open the modal (from xblock view) to a given view, or to close said modal (from within the modal view).
+
+## `routing` hooks
+This module provides hooks to fetch the active view and associated step
diff --git a/docs/decisions/0005-data-conceits.md b/docs/decisions/0005-data-conceits.md
@@ -0,0 +1,31 @@
+5. Data Conceits
+------------------
+
+Status
+-------
+Accepted
+
+Context
+-------
+We would like to keep a historical record of data conceits for the app as it evolves over time.
+
+Decision
+--------
+# Active Step
+The Active Step is the current workflow step of the ORA, independent of the UI.
+* Values from `stepNames` in `src/constants`
+* access from hooks with:
+  * `useActiveStepName()` from `src/hooks/app` if you only need the name
+  * `useGlobalState().activeStepName` from `src/hooks/app` if you need other global state info as well
+
+# Active View Step
+The Active View Step is the step that is being currently viewed  in the UI (or `xblock` for the base XBlock view)
+* values from `stepNames` in `src/constants`
+* Access from hooks with `useViewStep()` from `src/hooks/routing`
+
+# “Has submitted”
+`hasSubmitted` (in redux app state) refers explicitly to whether the associate form/action for a given step has been submitted.
+* For `submission` step, this means that the response has just been submitted.
+* For assessment steps, this means that a given assessment has been submitted
+  * This does not necessarily mean that the full assessment step is done, in the case of peer and self assessment steps.
+* Access from hook with `useHasSubmitted()` from `src/hooks/app` or `src/hooks/assessment`
diff --git a/docs/decisions/0006-lms-service.md b/docs/decisions/0006-lms-service.md
@@ -0,0 +1,36 @@
+6. LMS Service decisions
+------------------------
+
+Status
+------
+Accepted
+
+Context
+-------
+We would like to keep a historical record of our LMS service code decisions for the app as it
+evolves over time.
+
+Decision
+---------
+The data for this app is coming from the edX Learning Management System (LMS).  We have defined a fine-tuned Backend for the app that provides a small set of API endpoints to load the configuration information for an ORA, load the learner data/progress, and all of the actions a learner would need to take upon their response or assessments.
+
+File structure:
+* `api.js` for isolated api definitions
+* `urls.js` for url generators, based on existing url
+* `hooks/data.js` for loading data models (`oraConfig` and `pageData`)
+  * `pageData` is queried optionally with a page argument for modal views not in the `hasSubmitted` state
+* `hooks/selectors` is a collection of selector hooks that access the data from the data queries.  Some notable top-level examples are:
+  * `useIsPageDataLoaded` and `useIsOraConfigLoaded` from `src/hooks/app` allow the app to determine if these values are loaded before attempting to render components that require them.
+  * `useStepState({ step })` draws on the ora config and progress state to return a string state value (from `stepStates`)
+  * `useGlobalState({ step })` draws together a number of other selectors to provide one top-level state (with optional view-step passed).
+    * `activeStepName` - current workflow step name (from `stepNames`)
+    * `activeStepState` - state of current workflow step. (from `stepStates`)
+    * `cancellationInfo`
+    * `effectiveGrade` - the assessment(s) of the type specified as the `effective_assessment_type` in the api.
+      * `null` if has not received final grade
+      * includes one or more assessment objects for the learner’s response.
+      * includes a `stepScore` object (points earned / total)
+    * `hasReceivedFinalGrade` - boolean value for if the learner has received a final grade
+    * `lastStep` - returns the stepName for the final step in the step order (or submission if no assessment types are provided)
+    * `stepState` - returns the `stepState` of the **passed** step, which may or may not be equal to the activeStepName
+* `hooks/actions` is a collection of action hooks that send commands to the upstream api endpoints, including submitting responses or assessments, saving drafts, and refreshing page data.
diff --git a/docs/decisions/0007-app-state-components.md b/docs/decisions/0007-app-state-components.md
@@ -0,0 +1,25 @@
+7. App-State Components
+------------------------
+
+Status
+------
+Accepted
+
+Context
+--------
+We would like to keep a historical record of decisions for top-level componentry patterns for the
+app as it evolves over time
+
+Decision
+---------
+Because of the complexity of trying to share functionality/behaviors across views in ways that did not require an excessive amount of configuration per-use, we opted for this app to write a set of top-level app-state-aware components (`ModalActions`, `StatusAlerts`, and `StepProgressIndicator`) in the `components/` directory.  These components interrogate the global state (mostly through use of the `useGlobalState` hook), and provide the appropriate experience based on the current state.
+
+**`ModalActions`** component provides the `ActionRow` for the bottom of the Modal view.
+**`StatusAlerts`** component provides the top-level `StatusAlert`s for the top of both the XBlock and Modal views
+**`StepProgressIndicator`** component provides the component that lives in the header for Modal components, providing in-step progress as well as next-step actions when available.
+
+This provides the benefit of being able to map/configure **all** of the variants/behaviors of these components in a single location, and provides a clean place to make modifications to that workflow based on global app state, rather than just based on which view is hosting them.
+
+Consequences
+-------------
+Because of the consolidated nature of this behavior, there will not be nearly as many per-view variants of app-state components, grouped with the views.  Thus for people wishing to inspect the behavior of a view, they will need to know the states in which that view can be displayed, and then inspect the top-level componentry areas they want to examine in those states.
