Expertiza_Wiki - Recent changes [en]

CSC/ECE 517 Spring 2026 - E2617. Testing Questionnaire and Course Models

Zobrook2 — Mon, 04 May 2026 19:42:08 GMT

CSC/ECE 517 Spring 2026 - E2605. Specialized Rubrics for Different Topic Types

Vagarwa3 — Sun, 03 May 2026 01:40:01 GMT

Links

← Older revision		Revision as of 01:40, 3 May 2026
Line 737:		Line 737:

	Demo Video:		Demo Video:
	* ~~Add demo video link here~~		* https://youtu.be/TRxBHXo7GQQ

	== References ==		== References ==

Report Generation Framework (WIP)

Asreeku — Sat, 02 May 2026 21:51:39 GMT

Created page with "= Report Generation = == Design and Implementation Documentation == === Expertiza Reimplementation Back-End === ---- == Overview == The reporting subsystem was ported from the original Expertiza codebase (referred to as '''Repo X''') into the reimplemented Rails API back-end (referred to as '''Repo Y''') and redesigned in the process. Repo X used a Rails helper module (<code>ReportFormatterHelper</code>) that assigned instance variables, such as <code>@reviewers</cod..."

New page

= Report Generation =
== Design and Implementation Documentation ==
=== Expertiza Reimplementation Back-End ===

----

== Overview ==

The reporting subsystem was ported from the original Expertiza codebase
(referred to as '''Repo X''') into the reimplemented Rails API back-end
(referred to as '''Repo Y''') and redesigned in the process.

Repo X used a Rails helper module (<code>ReportFormatterHelper</code>) that
assigned instance variables, such as <code>@reviewers</code> and
<code>@review_scores</code>, for ERB views.

Since Repo Y is a JSON API with no views, instance variables are not applicable.
The architecture was therefore redesigned around a '''streaming reduce pipeline'''
that returns plain Ruby hashes rendered as JSON.

=== Design Goals ===

* Avoid loading entire result sets into memory at once.
* Keep domain-specific computation out of the base class.
* Make each report type independently composable and testable.
* Fix N+1 query patterns present in Repo X.

----

== Anti-Patterns Addressed ==

The design directly addresses two anti-patterns identified during architectural
review of Repo X.

=== The <code>fetch_responses</code> Anti-Pattern ===

Repo X loaded all response records into an unnamed, ad-hoc array before
processing:

<syntaxhighlight lang="ruby">
# WRONG
responses = fetch_responses # full memory load
grouped = group(responses)
metrics = compute_metrics(grouped)
</syntaxhighlight>

This forces the entire result set into Ruby memory, prevents streaming, and
makes the intermediate structure implicit.

The fix is to '''never materialise all rows at once'''. Instead, use
<code>find_each</code> to stream records in batches, so memory usage scales
with the number of '''groups''', not the number of raw rows.

=== Default Metrics in the Base Class ===

Repo X placed domain-specific math directly in the base class:

<syntaxhighlight lang="ruby">
# WRONG — in BaseReport
def compute_metrics(grouped)
grouped.transform_values do |responses|
{
count: responses.size,
avg_score: responses.map(&:score).sum / responses.size.to_f
}
end
end
</syntaxhighlight>

This ties every subclass to one particular shape of computation. The fix is
to move all domain math into per-report accumulator logic. The base class
contains '''zero''' domain math.

==== What "Domain Math" Means ====

'''Domain math''' refers to the business-logic calculations specific to a
particular report type — the actual formulas and aggregations that answer what
the report is trying to show.

It is called "domain" math because it belongs to the problem domain
(peer assessment), not to the generic pipeline machinery.

Each report type has its own domain math:

{| class="wikitable"
! Report !! Its domain math
|-
| Review scores
| <code>(raw_score / max_score) * 100</code> — percentage score per reviewer per round
|-
| Avg/ranges
| <code>max</code>, <code>min</code>, <code>sum / size</code> — score aggregates across a team's reviewers
|-
| Feedback
| Bucket response IDs into <code>round_1</code>, <code>round_2</code>, <code>round_3</code> arrays
|-
| Bookmark rating
| Collect distinct bookmark IDs into a <code>Set</code>
|}

Notice that these are completely different in shape: one computes a percentage,
another computes min/max/avg, and another just collects IDs.

If <code>avg_score</code> lived in <code>BaseReport</code>, every subclass
would either inherit math it does not need — for example, a bookmark report has
no scores — or be forced to override the method just to suppress it.

The rule is therefore:

> <code>BaseReport</code> only defines '''how to run the pipeline''' — stream, group, fold, finalize.
> The '''what to compute''' belongs entirely inside each report's own <code>accumulate</code> and <code>finalize</code> methods.

----

== System Diagrams [To be updated] ==

=== Overall Request Flow ===

The diagram below shows how an incoming HTTP request travels through the
system from the controller down to the pipeline and back out as JSON.

Since MediaWiki does not render TikZ directly, this diagram is represented
as a text-based flow.

<syntaxhighlight lang="text">
HTTP Client (Front-end)
|
| GET /reports/response_report?assignment_id=&type=
v
ReportsController#response_report
|
| params[:type]
v
REPORT_CLASSES[type]
look up concrete class
|
| .new(assignment).run
v
Concrete Report
for example, FeedbackReport
|
| inherits run
v
BaseReport#run
inherited find_each streaming loop
|
| calls subclass methods
v
source -> grouper -> accumulate -> finalize
|
| output hash
v
render json: { ... }
|
| JSON response
v
HTTP Client (Front-end)
</syntaxhighlight>

''Figure: End-to-end request flow for report generation''

=== Pipeline Internals ===

This diagram shows the four stages inside <code>BaseReport#run</code>.
The stages are defined by each concrete subclass; the pipeline loop itself
never changes.

<syntaxhighlight lang="text">
+------------------+ +------------------+
| 1. Source | rows | 2. Grouper |
| AR relation | -----> | lambda: row->key |
| streamed via | | e.g. reviewer_id |
| find_each | +------------------+
+------------------+ |
| key, row
v
+------------------+ +------------------+
| 4. Finalize | state | 3. Accumulate |
| shape state into | <----- | fold row into |
| output hash | | state |
+------------------+ | domain math here |
| +------------------+
|
v
Hash -> JSON
</syntaxhighlight>

Additional notes:

* <code>source</code> uses <code>includes(...)</code> where needed to avoid N+1 queries.
* <code>accumulate</code> handles scores, deduplication, bucketing, and counting depending on the report type.

''Figure: The four stages every report passes through inside BaseReport#run''

=== Class Hierarchy ===

This diagram shows how concrete report classes relate to <code>BaseReport</code>.

Solid inheritance from <code>BaseReport</code> is represented by indentation.
Composition from <code>ReviewReport</code> to its inner pipelines is represented
under the coordinator.

<syntaxhighlight lang="text">
BaseReport
|
|-- ReviewReport (coordinator)
| |
| |-- ReviewersPipeline
| |-- ScoresPipeline
| |-- AvgRangesPipeline
|
|-- FeedbackReport
|-- TeammateReviewReport
|-- BookmarkRatingReport
|-- BasicReport
</syntaxhighlight>

Legend:

* Direct child under <code>BaseReport</code> = inherits <code>BaseReport</code>
* Pipelines under <code>ReviewReport</code> = coordinator runs inner pipeline
* The inner pipelines also inherit <code>BaseReport</code>

''Figure: Class hierarchy for the report generation subsystem''

----

== Architecture: The Streaming Pipeline ==

=== Pipeline Shape ===

All reports are built on a single pipeline template defined in
<code>Reports::BaseReport</code>:

<syntaxhighlight lang="ruby">
def run
state = initial_state
source.find_each(batch_size: 500) do |row|
accumulate(state, grouper.call(row), row)
end
finalize(state)
end
</syntaxhighlight>

The pipeline consists of four concerns:

{| class="wikitable"
! Concern !! Responsibility
|-
| '''Source'''
| ActiveRecord relation streamed via <code>find_each</code>. Subclasses use <code>includes(...)</code> to eagerly load associations and prevent N+1 queries.
|-
| '''Grouper'''
| A lambda <code>(row) -> key</code> that determines how rows are bucketed in the accumulator state.
|-
| '''Accumulate'''
| Folds one row into the state in place. Contains all domain-specific math for that report.
|-
| '''Finalize'''
| Post-processes the finished state into the output hash. Default implementation returns state unchanged.
|}

=== Memory Model ===

State grows proportional to the number of '''groups''', such as the number of
distinct reviewers, not the number of raw rows.

For example, a dataset with 10,000 responses across 20 reviewers keeps only
20 entries in the accumulator state at any point.

=== Base Class Definition ===

<syntaxhighlight lang="ruby">
module Reports
class BaseReport
def initialize(assignment)
@assignment = assignment
end

def run
state = initial_state
source.find_each(batch_size: 500) do |row|
accumulate(state, grouper.call(row), row)
end
finalize(state)
end

private

def source = raise NotImplementedError
def grouper = raise NotImplementedError
def initial_state = raise NotImplementedError

def accumulate(_state, _key, _row)
raise NotImplementedError
end

def finalize(state) = state
end
end
</syntaxhighlight>

----

== Controller ==

=== Dispatch Mechanism ===

The controller uses a constant hash to map type strings to report classes,
replacing the <code>send(type)</code> meta-programming pattern used in Repo X.

<syntaxhighlight lang="ruby">
REPORT_CLASSES = {
'review_response_map' => Reports::ReviewReport,
'feedback_response_map' => Reports::FeedbackReport,
'teammate_review_response_map' => Reports::TeammateReviewReport,
'bookmark_rating_response_map' => Reports::BookmarkRatingReport,
'basic' => Reports::BasicReport
}.freeze

def response_report
type = params.dig(:report, :type) || params[:type] || 'basic'
report_class = REPORT_CLASSES[type]

unless report_class
return render json: { error: "Unknown report type: #{type}" },
status: :unprocessable_entity
end

assignment = Assignment.find(params[:assignment_id] || params[:id])
data = report_class.new(assignment).run
render json: { type: type, assignment_id: assignment.id }.merge(data)
end
</syntaxhighlight>

=== Route ===

<syntaxhighlight lang="text">
GET /reports/response_report?assignment_id=<id>&type=<type>
POST /reports/response_report
</syntaxhighlight>

----

== Report Implementations ==

=== Review Report (<code>review_response_map</code>) ===

The review report is the most complex. It is implemented as a coordinator
class (<code>ReviewReport</code>) that runs three independent inner pipelines
and merges their results.

{| class="wikitable"
! Pipeline !! Source !! Groups by !! Produces
|-
| <code>ReviewersPipeline</code>
| <code>ReviewResponseMap</code>
| <code>reviewer_id</code>
| Sorted reviewer list
|-
| <code>ScoresPipeline</code>
| <code>Response</code> JOIN map
| <code>reviewer_id</code>
| Score percentage per round/reviewee
|-
| <code>AvgRangesPipeline</code>
| <code>Response</code> JOIN map
| <code>[reviewee_id, round]</code>
| Max/min/avg per team/round
|}

==== N+1 Fix: Precomputed Max Question Score ====

Repo X called <code>response.maximum_score</code> inside the accumulation loop.

This method internally calls:

<syntaxhighlight lang="ruby">
response_assignment.assignment_questionnaires
.find_by(used_in_round: round)
.questionnaire
</syntaxhighlight>

This resulted in one query per response.

In Repo Y, both score pipelines precompute a
<code>round -> max_question_score</code> map with a single query before the
pipeline runs:

<syntaxhighlight lang="ruby">
def precompute_max_q_scores
AssignmentQuestionnaire
.joins(:questionnaire)
.where(assignment_id: @assignment.id)
.pluck(:used_in_round, 'questionnaires.max_question_score')
.to_h
end
</syntaxhighlight>

The result, for example <code>{nil => 10, 1 => 10, 2 => 5}</code>, is stored in
<code>@max_q_score</code> and used as a lookup inside <code>accumulate</code>:

<syntaxhighlight lang="ruby">
max_score = total_wt * (@max_q_score[round] || @max_q_score[nil] || 1)
</syntaxhighlight>

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "review_response_map",
"assignment_id": 1,
"reviewers": [
{ "id": 5, "user_id": 2, "name": "alice",
"full_name": "Alice Smith", "handle": "alice" }
],
"review_scores": { "5": { "1": { "3": 87.5 } } },
"avg_and_ranges": { "3": { "1": { "max": 92.0,
"min": 75.0,
"avg": 83.5 } } }
}
</syntaxhighlight>

----

=== Feedback Report (<code>feedback_response_map</code>) ===

Produces the list of authors and the IDs of review responses that received
author feedback, bucketed by round for varying-rubric assignments.

<syntaxhighlight lang="ruby">
def source
Response
.joins(:response_map)
.where(
response_maps: { type: 'ReviewResponseMap',
reviewed_object_id: @assignment.id }
)
.order(created_at: :desc)
end

def grouper = ->(r) { [r.map_id, r.round] }
def initial_state = { seen: Set.new, round_1: [],
round_2: [], round_3: [], all: [] }

def accumulate(state, key, response)
return if state[:seen].include?(key)
state[:seen].add(key)
if @assignment.varying_rubrics_by_round?
case response.round
when 1 then state[:round_1] << response.id
when 2 then state[:round_2] << response.id
when 3 then state[:round_3] << response.id
end
else
state[:all] << response.id
end
end
</syntaxhighlight>

Deduplication uses a <code>Set</code>, which gives O(1) lookup, rather than the
array-based <code>seen_map_round_keys.include?</code> from Repo X, which gives
O(n) lookup.

Authors are fetched once in <code>finalize</code>, not inside the stream.

==== End-to-End Execution Flow ====

The <code>run</code> method is '''inherited from <code>BaseReport</code>'''.
<code>FeedbackReport</code> never defines it.

Calling <code>FeedbackReport.new(assignment).run</code> triggers the following
sequence:

<syntaxhighlight lang="text">
ReportsController
REPORT_CLASSES['feedback_response_map'].new(assignment).run
|
| (inherited from BaseReport)
v
BaseReport#run
|
|-- Step 1: state = initial_state
| => { seen: Set.new,
| round_1: [], round_2: [], round_3: [], all: [] }
|
|-- Step 2: source.find_each(batch_size: 500)
| => Response.joins(:response_map)
| .where(type: 'ReviewResponseMap',
| reviewed_object_id: assignment.id)
| .order(created_at: :desc)
| streams Response records newest-first, in batches
|
|-- Step 3: for each Response row:
| key = grouper.call(row)
| => [row.map_id, row.round] e.g. [42, 1]
|
| accumulate(state, key, row)
| => skip if state[:seen] already has [map_id, round]
| (keeps only the latest response per map per round
| because source is ordered newest-first)
| => otherwise: add key to :seen, then bucket row.id:
| round == 1 => state[:round_1] << row.id
| round == 2 => state[:round_2] << row.id
| round == 3 => state[:round_3] << row.id
| (or state[:all] if single-rubric assignment)
|
|-- Step 4: finalize(state)
=> fetch_authors (one query: teams -> users -> participants)
=> if varying_rubrics_by_round?
return { authors: [...],
review_response_ids: {
round_1: [...], round_2: [...], round_3: [...] } }
else
return { authors: [...],
review_response_ids: [...] }
</syntaxhighlight>

The key point is that <code>FeedbackReport</code> only defines the four pieces
the pipeline needs:

* <code>source</code>
* <code>grouper</code>
* <code>initial_state</code>
* <code>accumulate</code>
* <code>finalize</code>

Ruby's inheritance mechanism means calling <code>.run</code> on a
<code>FeedbackReport</code> instance automatically executes
<code>BaseReport#run</code>, which calls back into <code>FeedbackReport</code>'s
implementations of those methods.

==== Sample Response (varying rubrics) ====

<syntaxhighlight lang="json">
{
"type": "feedback_response_map",
"authors": [{ "id": 7, "name": "bob", "full_name": "Bob Jones" }],
"review_response_ids": {
"round_1": [12, 15], "round_2": [18], "round_3": []
}
}
</syntaxhighlight>

----

=== Teammate Review Report (<code>teammate_review_response_map</code>) ===

Streams <code>TeammateReviewResponseMap</code> records grouped by
<code>reviewer_id</code>.

The first occurrence per reviewer is kept using deduplication via early return
if the key already exists in state. Reviewer associations are eagerly loaded.

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "teammate_review_response_map",
"reviewers": [
{ "reviewer_id": 5, "user_id": 2,
"name": "alice", "full_name": "Alice Smith" }
]
}
</syntaxhighlight>

----

=== Bookmark Rating Report (<code>bookmark_rating_response_map</code>) ===

Streams <code>BookmarkRatingResponseMap</code> records, accumulating distinct
bookmark IDs into a <code>Set</code>.

Project topics are fetched once in <code>finalize</code>.

==== Bug Fixed During Port ====

The model's <code>bookmark_response_report</code> in Repo Y was incorrectly
calling:

<syntaxhighlight lang="ruby">
.pluck(:reviewed_object_id)
</syntaxhighlight>

This returns assignment IDs, since <code>reviewed_object_id</code> is the
foreign key to <code>Assignment</code>.

Bookmark IDs are stored in <code>reviewee_id</code>. Therefore, this was fixed
to:

<syntaxhighlight lang="ruby">
.pluck(:reviewee_id)
</syntaxhighlight>

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "bookmark_rating_response_map",
"bookmark_ids": [10, 14, 22],
"topics": [{ "id": 3, "topic_name": "Machine Learning" }]
}
</syntaxhighlight>

----

=== Basic Report (<code>basic</code>) ===

Returns minimal assignment metadata.

No streaming is required since all data comes from the already-loaded
<code>Assignment</code> object.

This report is used as the default when no type parameter is provided.

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "basic",
"assignment_id": 1,
"assignment": {
"id": 1, "name": "Project 1",
"num_review_rounds": 2,
"varying_rubrics_by_round": true
}
}
</syntaxhighlight>

----

== File Structure ==

<syntaxhighlight lang="text">
app/
controllers/
reports_controller.rb Entry point, REPORT_CLASSES dispatch
helpers/
report_formatter_helper.rb Empty namespace (logic moved to services)
services/
reports/
base_report.rb Abstract pipeline template
review_report.rb 3-pipeline coordinator
feedback_report.rb Single pipeline, round bucketing
teammate_review_report.rb Single pipeline
bookmark_rating_report.rb Single pipeline
basic_report.rb Simple struct
models/
review_response_map.rb
.review_response_report class method
feedback_response_map.rb
.feedback_response_report class method
teammate_review_response_map.rb
.teammate_response_report class method
bookmark_rating_response_map.rb
.bookmark_response_report (bug fixed)
</syntaxhighlight>

----

== Blocked Report Types ==

The following report types exist in Repo X but cannot yet be implemented in
Repo Y due to missing database tables or models.

Each is ready to be added once its dependency is ported.

{| class="wikitable"
! Report Type !! Missing Dependency !! Repo X Location
|-
| <code>calibration</code>
| <code>calibrate_to</code> column on <code>response_maps</code>
| <code>report_formatter_helper.rb</code>
|-
| <code>self_review</code>
| <code>SelfReviewResponseMap</code> model
| <code>self_review_response_map.rb</code>
|-
| <code>survey</code>
| <code>survey_deployments</code> table
| <code>survey_response_map.rb</code>
|-
| <code>quiz</code>
| <code>quiz_responses</code> table
| <code>quiz_response_map.rb</code>
|-
| <code>answer_tagging</code>
| <code>tag_prompt_deployments</code>, <code>answer_tags</code> tables
| <code>tag_prompt_deployment.rb</code>
|}

To add a blocked report once its dependencies are available:

# Create <code>app/services/reports/<name>_report.rb</code> inheriting <code>BaseReport</code>.
# Define <code>source</code>, <code>grouper</code>, <code>initial_state</code>, <code>accumulate</code>, and <code>finalize</code>.
# Add an entry to <code>ReportsController::REPORT_CLASSES</code>.

----

== Comparison with Repo X ==

{| class="wikitable"
! Concern !! Repo X !! Repo Y
|-
| Output format
| ERB instance variables, such as <code>@reviewers</code> and <code>@review_scores</code>
| JSON hash from <code>report.run</code>
|-
| Loading strategy
| All records loaded into arrays at once
| <code>find_each</code> batched streaming
|-
| Metrics location
| <code>compute_metrics</code> in helper base
| Each report owns <code>accumulate</code> and <code>finalize</code>
|-
| Dispatch
| <code>send(@type.underscore, params, session)</code>
| <code>REPORT_CLASSES[type].new(assignment).run</code>
|-
| N+1 on scores
| <code>response.maximum_score</code> per row — questionnaire lookup each time
| Precomputed <code>round->max_score</code> map, one query before pipeline
|-
| Deduplication
| <code>Array#include?</code> — O(n) per check
| <code>Set#include?</code> — O(1) per check
|-
| Additional features
| LLM evaluation, CSV export, calibration, self-review, survey, quiz, answer tagging
| Not yet ported; blocked on schema
|}

----
== Author ==

{| class="wikitable"
! Name !! Role
|-
| '''Aanand Sreekumaran Nair Jayakumari'''
| Project contributor / developer
|}

Main Page

Asreeku — Sat, 02 May 2026 21:49:59 GMT

← Older revision		Revision as of 21:49, 2 May 2026
Line 41:		Line 41:
	* [[ReactJs Frontend]]		* [[ReactJs Frontend]]
	* [[Front-End/Back-End]]		* [[Front-End/Back-End]]
	* [[Report ~~generation framework~~(WIP)]]		* [[Report Generation Framework (WIP)]]

	==Application Behavior==		==Application Behavior==

Report generation framework(WIP)

Asreeku — Sat, 02 May 2026 21:49:32 GMT

New page

= Report Generation =
== Design and Implementation Documentation ==
=== Expertiza Reimplementation Back-End ===

----

== Overview ==

The reporting subsystem was ported from the original Expertiza codebase
(referred to as '''Repo X''') into the reimplemented Rails API back-end
(referred to as '''Repo Y''') and redesigned in the process.

Repo X used a Rails helper module (<code>ReportFormatterHelper</code>) that
assigned instance variables, such as <code>@reviewers</code> and
<code>@review_scores</code>, for ERB views.

Since Repo Y is a JSON API with no views, instance variables are not applicable.
The architecture was therefore redesigned around a '''streaming reduce pipeline'''
that returns plain Ruby hashes rendered as JSON.

=== Design Goals ===

* Avoid loading entire result sets into memory at once.
* Keep domain-specific computation out of the base class.
* Make each report type independently composable and testable.
* Fix N+1 query patterns present in Repo X.

----

== Anti-Patterns Addressed ==

The design directly addresses two anti-patterns identified during architectural
review of Repo X.

=== The <code>fetch_responses</code> Anti-Pattern ===

Repo X loaded all response records into an unnamed, ad-hoc array before
processing:

<syntaxhighlight lang="ruby">
# WRONG
responses = fetch_responses # full memory load
grouped = group(responses)
metrics = compute_metrics(grouped)
</syntaxhighlight>

This forces the entire result set into Ruby memory, prevents streaming, and
makes the intermediate structure implicit.

The fix is to '''never materialise all rows at once'''. Instead, use
<code>find_each</code> to stream records in batches, so memory usage scales
with the number of '''groups''', not the number of raw rows.

=== Default Metrics in the Base Class ===

Repo X placed domain-specific math directly in the base class:

<syntaxhighlight lang="ruby">
# WRONG — in BaseReport
def compute_metrics(grouped)
grouped.transform_values do |responses|
{
count: responses.size,
avg_score: responses.map(&:score).sum / responses.size.to_f
}
end
end
</syntaxhighlight>

This ties every subclass to one particular shape of computation. The fix is
to move all domain math into per-report accumulator logic. The base class
contains '''zero''' domain math.

==== What "Domain Math" Means ====

'''Domain math''' refers to the business-logic calculations specific to a
particular report type — the actual formulas and aggregations that answer what
the report is trying to show.

It is called "domain" math because it belongs to the problem domain
(peer assessment), not to the generic pipeline machinery.

Each report type has its own domain math:

{| class="wikitable"
! Report !! Its domain math
|-
| Review scores
| <code>(raw_score / max_score) * 100</code> — percentage score per reviewer per round
|-
| Avg/ranges
| <code>max</code>, <code>min</code>, <code>sum / size</code> — score aggregates across a team's reviewers
|-
| Feedback
| Bucket response IDs into <code>round_1</code>, <code>round_2</code>, <code>round_3</code> arrays
|-
| Bookmark rating
| Collect distinct bookmark IDs into a <code>Set</code>
|}

Notice that these are completely different in shape: one computes a percentage,
another computes min/max/avg, and another just collects IDs.

If <code>avg_score</code> lived in <code>BaseReport</code>, every subclass
would either inherit math it does not need — for example, a bookmark report has
no scores — or be forced to override the method just to suppress it.

The rule is therefore:

> <code>BaseReport</code> only defines '''how to run the pipeline''' — stream, group, fold, finalize.
> The '''what to compute''' belongs entirely inside each report's own <code>accumulate</code> and <code>finalize</code> methods.

----

== System Diagrams [To be updated] ==

=== Overall Request Flow ===

The diagram below shows how an incoming HTTP request travels through the
system from the controller down to the pipeline and back out as JSON.

Since MediaWiki does not render TikZ directly, this diagram is represented
as a text-based flow.

<syntaxhighlight lang="text">
HTTP Client (Front-end)
|
| GET /reports/response_report?assignment_id=&type=
v
ReportsController#response_report
|
| params[:type]
v
REPORT_CLASSES[type]
look up concrete class
|
| .new(assignment).run
v
Concrete Report
for example, FeedbackReport
|
| inherits run
v
BaseReport#run
inherited find_each streaming loop
|
| calls subclass methods
v
source -> grouper -> accumulate -> finalize
|
| output hash
v
render json: { ... }
|
| JSON response
v
HTTP Client (Front-end)
</syntaxhighlight>

''Figure: End-to-end request flow for report generation''

=== Pipeline Internals ===

This diagram shows the four stages inside <code>BaseReport#run</code>.
The stages are defined by each concrete subclass; the pipeline loop itself
never changes.

<syntaxhighlight lang="text">
+------------------+ +------------------+
| 1. Source | rows | 2. Grouper |
| AR relation | -----> | lambda: row->key |
| streamed via | | e.g. reviewer_id |
| find_each | +------------------+
+------------------+ |
| key, row
v
+------------------+ +------------------+
| 4. Finalize | state | 3. Accumulate |
| shape state into | <----- | fold row into |
| output hash | | state |
+------------------+ | domain math here |
| +------------------+
|
v
Hash -> JSON
</syntaxhighlight>

Additional notes:

* <code>source</code> uses <code>includes(...)</code> where needed to avoid N+1 queries.
* <code>accumulate</code> handles scores, deduplication, bucketing, and counting depending on the report type.

''Figure: The four stages every report passes through inside BaseReport#run''

=== Class Hierarchy ===

This diagram shows how concrete report classes relate to <code>BaseReport</code>.

Solid inheritance from <code>BaseReport</code> is represented by indentation.
Composition from <code>ReviewReport</code> to its inner pipelines is represented
under the coordinator.

<syntaxhighlight lang="text">
BaseReport
|
|-- ReviewReport (coordinator)
| |
| |-- ReviewersPipeline
| |-- ScoresPipeline
| |-- AvgRangesPipeline
|
|-- FeedbackReport
|-- TeammateReviewReport
|-- BookmarkRatingReport
|-- BasicReport
</syntaxhighlight>

Legend:

* Direct child under <code>BaseReport</code> = inherits <code>BaseReport</code>
* Pipelines under <code>ReviewReport</code> = coordinator runs inner pipeline
* The inner pipelines also inherit <code>BaseReport</code>

''Figure: Class hierarchy for the report generation subsystem''

----

== Architecture: The Streaming Pipeline ==

=== Pipeline Shape ===

All reports are built on a single pipeline template defined in
<code>Reports::BaseReport</code>:

<syntaxhighlight lang="ruby">
def run
state = initial_state
source.find_each(batch_size: 500) do |row|
accumulate(state, grouper.call(row), row)
end
finalize(state)
end
</syntaxhighlight>

The pipeline consists of four concerns:

{| class="wikitable"
! Concern !! Responsibility
|-
| '''Source'''
| ActiveRecord relation streamed via <code>find_each</code>. Subclasses use <code>includes(...)</code> to eagerly load associations and prevent N+1 queries.
|-
| '''Grouper'''
| A lambda <code>(row) -> key</code> that determines how rows are bucketed in the accumulator state.
|-
| '''Accumulate'''
| Folds one row into the state in place. Contains all domain-specific math for that report.
|-
| '''Finalize'''
| Post-processes the finished state into the output hash. Default implementation returns state unchanged.
|}

=== Memory Model ===

State grows proportional to the number of '''groups''', such as the number of
distinct reviewers, not the number of raw rows.

For example, a dataset with 10,000 responses across 20 reviewers keeps only
20 entries in the accumulator state at any point.

=== Base Class Definition ===

<syntaxhighlight lang="ruby">
module Reports
class BaseReport
def initialize(assignment)
@assignment = assignment
end

def run
state = initial_state
source.find_each(batch_size: 500) do |row|
accumulate(state, grouper.call(row), row)
end
finalize(state)
end

private

def source = raise NotImplementedError
def grouper = raise NotImplementedError
def initial_state = raise NotImplementedError

def accumulate(_state, _key, _row)
raise NotImplementedError
end

def finalize(state) = state
end
end
</syntaxhighlight>

----

== Controller ==

=== Dispatch Mechanism ===

The controller uses a constant hash to map type strings to report classes,
replacing the <code>send(type)</code> meta-programming pattern used in Repo X.

<syntaxhighlight lang="ruby">
REPORT_CLASSES = {
'review_response_map' => Reports::ReviewReport,
'feedback_response_map' => Reports::FeedbackReport,
'teammate_review_response_map' => Reports::TeammateReviewReport,
'bookmark_rating_response_map' => Reports::BookmarkRatingReport,
'basic' => Reports::BasicReport
}.freeze

def response_report
type = params.dig(:report, :type) || params[:type] || 'basic'
report_class = REPORT_CLASSES[type]

unless report_class
return render json: { error: "Unknown report type: #{type}" },
status: :unprocessable_entity
end

assignment = Assignment.find(params[:assignment_id] || params[:id])
data = report_class.new(assignment).run
render json: { type: type, assignment_id: assignment.id }.merge(data)
end
</syntaxhighlight>

=== Route ===

<syntaxhighlight lang="text">
GET /reports/response_report?assignment_id=<id>&type=<type>
POST /reports/response_report
</syntaxhighlight>

----

== Report Implementations ==

=== Review Report (<code>review_response_map</code>) ===

The review report is the most complex. It is implemented as a coordinator
class (<code>ReviewReport</code>) that runs three independent inner pipelines
and merges their results.

{| class="wikitable"
! Pipeline !! Source !! Groups by !! Produces
|-
| <code>ReviewersPipeline</code>
| <code>ReviewResponseMap</code>
| <code>reviewer_id</code>
| Sorted reviewer list
|-
| <code>ScoresPipeline</code>
| <code>Response</code> JOIN map
| <code>reviewer_id</code>
| Score percentage per round/reviewee
|-
| <code>AvgRangesPipeline</code>
| <code>Response</code> JOIN map
| <code>[reviewee_id, round]</code>
| Max/min/avg per team/round
|}

==== N+1 Fix: Precomputed Max Question Score ====

Repo X called <code>response.maximum_score</code> inside the accumulation loop.

This method internally calls:

<syntaxhighlight lang="ruby">
response_assignment.assignment_questionnaires
.find_by(used_in_round: round)
.questionnaire
</syntaxhighlight>

This resulted in one query per response.

In Repo Y, both score pipelines precompute a
<code>round -> max_question_score</code> map with a single query before the
pipeline runs:

<syntaxhighlight lang="ruby">
def precompute_max_q_scores
AssignmentQuestionnaire
.joins(:questionnaire)
.where(assignment_id: @assignment.id)
.pluck(:used_in_round, 'questionnaires.max_question_score')
.to_h
end
</syntaxhighlight>

The result, for example <code>{nil => 10, 1 => 10, 2 => 5}</code>, is stored in
<code>@max_q_score</code> and used as a lookup inside <code>accumulate</code>:

<syntaxhighlight lang="ruby">
max_score = total_wt * (@max_q_score[round] || @max_q_score[nil] || 1)
</syntaxhighlight>

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "review_response_map",
"assignment_id": 1,
"reviewers": [
{ "id": 5, "user_id": 2, "name": "alice",
"full_name": "Alice Smith", "handle": "alice" }
],
"review_scores": { "5": { "1": { "3": 87.5 } } },
"avg_and_ranges": { "3": { "1": { "max": 92.0,
"min": 75.0,
"avg": 83.5 } } }
}
</syntaxhighlight>

----

=== Feedback Report (<code>feedback_response_map</code>) ===

Produces the list of authors and the IDs of review responses that received
author feedback, bucketed by round for varying-rubric assignments.

<syntaxhighlight lang="ruby">
def source
Response
.joins(:response_map)
.where(
response_maps: { type: 'ReviewResponseMap',
reviewed_object_id: @assignment.id }
)
.order(created_at: :desc)
end

def grouper = ->(r) { [r.map_id, r.round] }
def initial_state = { seen: Set.new, round_1: [],
round_2: [], round_3: [], all: [] }

def accumulate(state, key, response)
return if state[:seen].include?(key)
state[:seen].add(key)
if @assignment.varying_rubrics_by_round?
case response.round
when 1 then state[:round_1] << response.id
when 2 then state[:round_2] << response.id
when 3 then state[:round_3] << response.id
end
else
state[:all] << response.id
end
end
</syntaxhighlight>

Deduplication uses a <code>Set</code>, which gives O(1) lookup, rather than the
array-based <code>seen_map_round_keys.include?</code> from Repo X, which gives
O(n) lookup.

Authors are fetched once in <code>finalize</code>, not inside the stream.

==== End-to-End Execution Flow ====

The <code>run</code> method is '''inherited from <code>BaseReport</code>'''.
<code>FeedbackReport</code> never defines it.

Calling <code>FeedbackReport.new(assignment).run</code> triggers the following
sequence:

<syntaxhighlight lang="text">
ReportsController
REPORT_CLASSES['feedback_response_map'].new(assignment).run
|
| (inherited from BaseReport)
v
BaseReport#run
|
|-- Step 1: state = initial_state
| => { seen: Set.new,
| round_1: [], round_2: [], round_3: [], all: [] }
|
|-- Step 2: source.find_each(batch_size: 500)
| => Response.joins(:response_map)
| .where(type: 'ReviewResponseMap',
| reviewed_object_id: assignment.id)
| .order(created_at: :desc)
| streams Response records newest-first, in batches
|
|-- Step 3: for each Response row:
| key = grouper.call(row)
| => [row.map_id, row.round] e.g. [42, 1]
|
| accumulate(state, key, row)
| => skip if state[:seen] already has [map_id, round]
| (keeps only the latest response per map per round
| because source is ordered newest-first)
| => otherwise: add key to :seen, then bucket row.id:
| round == 1 => state[:round_1] << row.id
| round == 2 => state[:round_2] << row.id
| round == 3 => state[:round_3] << row.id
| (or state[:all] if single-rubric assignment)
|
|-- Step 4: finalize(state)
=> fetch_authors (one query: teams -> users -> participants)
=> if varying_rubrics_by_round?
return { authors: [...],
review_response_ids: {
round_1: [...], round_2: [...], round_3: [...] } }
else
return { authors: [...],
review_response_ids: [...] }
</syntaxhighlight>

The key point is that <code>FeedbackReport</code> only defines the four pieces
the pipeline needs:

* <code>source</code>
* <code>grouper</code>
* <code>initial_state</code>
* <code>accumulate</code>
* <code>finalize</code>

Ruby's inheritance mechanism means calling <code>.run</code> on a
<code>FeedbackReport</code> instance automatically executes
<code>BaseReport#run</code>, which calls back into <code>FeedbackReport</code>'s
implementations of those methods.

==== Sample Response (varying rubrics) ====

<syntaxhighlight lang="json">
{
"type": "feedback_response_map",
"authors": [{ "id": 7, "name": "bob", "full_name": "Bob Jones" }],
"review_response_ids": {
"round_1": [12, 15], "round_2": [18], "round_3": []
}
}
</syntaxhighlight>

----

=== Teammate Review Report (<code>teammate_review_response_map</code>) ===

Streams <code>TeammateReviewResponseMap</code> records grouped by
<code>reviewer_id</code>.

The first occurrence per reviewer is kept using deduplication via early return
if the key already exists in state. Reviewer associations are eagerly loaded.

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "teammate_review_response_map",
"reviewers": [
{ "reviewer_id": 5, "user_id": 2,
"name": "alice", "full_name": "Alice Smith" }
]
}
</syntaxhighlight>

----

=== Bookmark Rating Report (<code>bookmark_rating_response_map</code>) ===

Streams <code>BookmarkRatingResponseMap</code> records, accumulating distinct
bookmark IDs into a <code>Set</code>.

Project topics are fetched once in <code>finalize</code>.

==== Bug Fixed During Port ====

The model's <code>bookmark_response_report</code> in Repo Y was incorrectly
calling:

<syntaxhighlight lang="ruby">
.pluck(:reviewed_object_id)
</syntaxhighlight>

This returns assignment IDs, since <code>reviewed_object_id</code> is the
foreign key to <code>Assignment</code>.

Bookmark IDs are stored in <code>reviewee_id</code>. Therefore, this was fixed
to:

<syntaxhighlight lang="ruby">
.pluck(:reviewee_id)
</syntaxhighlight>

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "bookmark_rating_response_map",
"bookmark_ids": [10, 14, 22],
"topics": [{ "id": 3, "topic_name": "Machine Learning" }]
}
</syntaxhighlight>

----

=== Basic Report (<code>basic</code>) ===

Returns minimal assignment metadata.

No streaming is required since all data comes from the already-loaded
<code>Assignment</code> object.

This report is used as the default when no type parameter is provided.

==== Sample Response ====

<syntaxhighlight lang="json">
{
"type": "basic",
"assignment_id": 1,
"assignment": {
"id": 1, "name": "Project 1",
"num_review_rounds": 2,
"varying_rubrics_by_round": true
}
}
</syntaxhighlight>

----

== File Structure ==

<syntaxhighlight lang="text">
app/
controllers/
reports_controller.rb Entry point, REPORT_CLASSES dispatch
helpers/
report_formatter_helper.rb Empty namespace (logic moved to services)
services/
reports/
base_report.rb Abstract pipeline template
review_report.rb 3-pipeline coordinator
feedback_report.rb Single pipeline, round bucketing
teammate_review_report.rb Single pipeline
bookmark_rating_report.rb Single pipeline
basic_report.rb Simple struct
models/
review_response_map.rb
.review_response_report class method
feedback_response_map.rb
.feedback_response_report class method
teammate_review_response_map.rb
.teammate_response_report class method
bookmark_rating_response_map.rb
.bookmark_response_report (bug fixed)
</syntaxhighlight>

----

== Blocked Report Types ==

The following report types exist in Repo X but cannot yet be implemented in
Repo Y due to missing database tables or models.

Each is ready to be added once its dependency is ported.

{| class="wikitable"
! Report Type !! Missing Dependency !! Repo X Location
|-
| <code>calibration</code>
| <code>calibrate_to</code> column on <code>response_maps</code>
| <code>report_formatter_helper.rb</code>
|-
| <code>self_review</code>
| <code>SelfReviewResponseMap</code> model
| <code>self_review_response_map.rb</code>
|-
| <code>survey</code>
| <code>survey_deployments</code> table
| <code>survey_response_map.rb</code>
|-
| <code>quiz</code>
| <code>quiz_responses</code> table
| <code>quiz_response_map.rb</code>
|-
| <code>answer_tagging</code>
| <code>tag_prompt_deployments</code>, <code>answer_tags</code> tables
| <code>tag_prompt_deployment.rb</code>
|}

To add a blocked report once its dependencies are available:

# Create <code>app/services/reports/<name>_report.rb</code> inheriting <code>BaseReport</code>.
# Define <code>source</code>, <code>grouper</code>, <code>initial_state</code>, <code>accumulate</code>, and <code>finalize</code>.
# Add an entry to <code>ReportsController::REPORT_CLASSES</code>.

----

== Comparison with Repo X ==

{| class="wikitable"
! Concern !! Repo X !! Repo Y
|-
| Output format
| ERB instance variables, such as <code>@reviewers</code> and <code>@review_scores</code>
| JSON hash from <code>report.run</code>
|-
| Loading strategy
| All records loaded into arrays at once
| <code>find_each</code> batched streaming
|-
| Metrics location
| <code>compute_metrics</code> in helper base
| Each report owns <code>accumulate</code> and <code>finalize</code>
|-
| Dispatch
| <code>send(@type.underscore, params, session)</code>
| <code>REPORT_CLASSES[type].new(assignment).run</code>
|-
| N+1 on scores
| <code>response.maximum_score</code> per row — questionnaire lookup each time
| Precomputed <code>round->max_score</code> map, one query before pipeline
|-
| Deduplication
| <code>Array#include?</code> — O(n) per check
| <code>Set#include?</code> — O(1) per check
|-
| Additional features
| LLM evaluation, CSV export, calibration, self-review, survey, quiz, answer tagging
| Not yet ported; blocked on schema
|}

----

== Author ==

{| class="wikitable"
! Name !! Role
|-
| '''Aanand Sreekumaran Nair Jayakumari'''
| Project contributor / developer
|}

Main Page

Asreeku — Sat, 02 May 2026 21:43:54 GMT

← Older revision		Revision as of 21:43, 2 May 2026
Line 41:		Line 41:
	* [[ReactJs Frontend]]		* [[ReactJs Frontend]]
	* [[Front-End/Back-End]]		* [[Front-End/Back-End]]
	* [[Report generation framework]]		* [[Report generation framework(WIP)]]

	==Application Behavior==		==Application Behavior==

Report generation framework

Asreeku — Sat, 02 May 2026 21:43:05 GMT

Created page with "# Report Generation"

New page

# Report Generation

CSC/ECE 517 Spring 2026 - E2612. Course-based reports

Rsgopara — Sat, 02 May 2026 21:34:13 GMT

8. Reuse Decisions

← Older revision		Revision as of 21:34, 2 May 2026
Line 298:		Line 298:
	\| Legacy Rails report views \|\| Not reused \|\| Clean reimplementation only		\| Legacy Rails report views \|\| Not reused \|\| Clean reimplementation only
	\|}		\|}

			The project was designed to be minimally intrusive by reusing existing, well-tested code whenever possible instead of rebuilding functionality from scratch. The biggest reuse decision was the shared Table.tsx component, whose TanStack Table foundation already supported grouped headers, sorting, and column visibility, covering most of the report’s interactive needs with only a small addition: disablePaginationRowModel. We also followed the existing patterns in gradesService.ts and Course.tsx for the service and routing layers, keeping the new code consistent and easy to understand within the existing codebase.

	== 9. Tests ==		== 9. Tests ==

Main Page

Asreeku — Sat, 02 May 2026 21:30:20 GMT

← Older revision		Revision as of 21:30, 2 May 2026
Line 41:		Line 41:
	* [[ReactJs Frontend]]		* [[ReactJs Frontend]]
	* [[Front-End/Back-End]]		* [[Front-End/Back-End]]
			* [[Report generation framework]]

	==Application Behavior==		==Application Behavior==

CSC/ECE 517 Spring 2026 - E2612. Course-based reports

Rsgopara — Sat, 02 May 2026 21:28:12 GMT

6.2 Response Shape

← Older revision		Revision as of 21:28, 2 May 2026
(5 intermediate revisions by the same user not shown)
Line 25:		Line 25:

	This project consolidates both into a single unified table, accessible from the Courses list page. The table displays every enrolled student alongside their grades, topics, teammate scores, and author feedback scores for every assignment in the course, with instructor-controlled column visibility to keep the view manageable. The implementation targets Expertiza's reimplemented React/TypeScript frontend. The legacy Rails views serve only as a reference for the underlying data model; no legacy code was reused.		This project consolidates both into a single unified table, accessible from the Courses list page. The table displays every enrolled student alongside their grades, topics, teammate scores, and author feedback scores for every assignment in the course, with instructor-controlled column visibility to keep the view manageable. The implementation targets Expertiza's reimplemented React/TypeScript frontend. The legacy Rails views serve only as a reference for the underlying data model; no legacy code was reused.

			[[File:E2612-FinalFrontend1.png\|1100px]]

	== 2. Requirements ==		== 2. Requirements ==
Line 143:		Line 145:
	=== 6.2 Response Shape ===		=== 6.2 Response Shape ===

	<~~pre~~>		<syntaxhighlight lang="ruby">
	{		{
	"course_id": 44,		"course_id": 44,
Line 183:		Line 185:
	]		]
	}		}
	</~~pre~~>		</syntaxhighlight>

	Assignments are sorted by their final review deadline before building the report. The <code>topic</code> field is present only when <code>has_topics</code> is true for that assignment.		Assignments are sorted by their final review deadline before building the report. The <code>topic</code> field is present only when <code>has_topics</code> is true for that assignment.
Line 236:		Line 238:
	\|}		\|}

	=== 7.3 ~~Report Page Screenshot~~ ===		=== 7.3 Frontend Type Definitions ===

	~~[[File:E2612-FinalFrontend1.png\|800px]]~~		<syntaxhighlight lang="ruby">

	=== ~~7.4 Frontend Type Definitions ===~~

	~~<pre~~>
	interface AssignmentMetadata {		interface AssignmentMetadata {
	assignment_id: number;		assignment_id: number;
Line 278:		Line 276:
	avgAuthorFeedbackScore: boolean;		avgAuthorFeedbackScore: boolean;
	};		};
	</~~pre~~>		</syntaxhighlight>

	== 8. Reuse Decisions ==		== 8. Reuse Decisions ==

CSC/ECE 517 Spring 2026 - E2612. Course-based reports

Mskamat — Sat, 02 May 2026 19:19:07 GMT

@@ Line 301: / Line 301: @@
 |}
-== 9. Out of Scope ==
+== 9. Tests ==
 The following are not part of this implementation:

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

Atmai — Thu, 30 Apr 2026 22:45:45 GMT

← Older revision		Revision as of 22:45, 30 April 2026
Line 149:		Line 149:

	=== Take Quiz Button (Assigned Reviews) ===		=== Take Quiz Button (Assigned Reviews) ===
	[[File:take_quiz_button.png]]		[[File:take_quiz_button.png\| 500px]]

	=== Questionnaire Editor – Correct Answer Fields ===		=== Questionnaire Editor – Correct Answer Fields ===
	[[File:correct_answer_fields.png]]		[[File:correct_answer_fields.png\| 500px]]

	=== Quiz Submission and Score Display ===		=== Quiz Submission and Score Display ===
	[[File:quiz_score_display.png]]		[[File:quiz_score_display.png\| 500px]]

	== Changes Implemented ==		== Changes Implemented ==
Line 585:		Line 585:
	=== Github Pull Request ===		=== Github Pull Request ===

	* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/~~179~~		* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/181
	* Backend: https://github.com/expertiza/reimplementation-back-end/pull/~~345~~		* Backend: https://github.com/expertiza/reimplementation-back-end/pull/349
	=== Video ===		=== Video ===

File:Quiz score display.png

Tdesai — Wed, 29 Apr 2026 03:11:17 GMT

Tdesai uploaded File:Quiz score display.png

New page

File:Correct answer fields.png

Tdesai — Wed, 29 Apr 2026 03:09:45 GMT

Tdesai uploaded File:Correct answer fields.png

New page

File:Take quiz button.png

Tdesai — Wed, 29 Apr 2026 03:08:13 GMT

Tdesai uploaded File:Take quiz button.png

New page

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

Tdesai — Wed, 29 Apr 2026 03:03:09 GMT

Screenshots

← Older revision		Revision as of 03:03, 29 April 2026
Line 146:		Line 146:
	</pre>		</pre>

	=== ~~Screenshots~~ ===		== Screenshots ==
	[[File:~~e2619_take_quiz_button~~.png~~\|Take Quiz button in AssignedReviews~~]]
	[[File:~~e2619_correct_answer_fields~~.png~~\|Correct answer fields in Questionnaire Editor~~]]		=== Take Quiz Button (Assigned Reviews) ===
	[[File:~~e2619_quiz_score~~.png~~\|Quiz score display after submission~~]]		[[File:take_quiz_button.png]]

			=== Questionnaire Editor – Correct Answer Fields ===
			[[File:correct_answer_fields.png]]

			=== Quiz Submission and Score Display ===
			[[File:quiz_score_display.png]]

	== Changes Implemented ==		== Changes Implemented ==

CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes

Amejari — Wed, 29 Apr 2026 02:33:46 GMT

← Older revision		Revision as of 02:33, 29 April 2026
(One intermediate revision by the same user not shown)
Line 402:		Line 402:
	=== Phase 4 — Update Tests and Documentation ===		=== Phase 4 — Update Tests and Documentation ===

	Write the new request specs and the <code>student_tasks_controller_task_items_spec.rb</code> unit spec as described in the [[#Planned Test Suite After Refactor\|Planned Test Suite]] section. ~~Update <code>docs/POSTMAN_STUDENT_TASKS.md</code> if any wording references <code>TaskOrdering</code>.~~ Update this wiki page to move the "Planned Refactor" content into the past tense once the work is complete.		Write the new request specs and the <code>student_tasks_controller_task_items_spec.rb</code> unit spec as described in the [[#Planned Test Suite After Refactor\|Planned Test Suite]] section. Update this wiki page to move the "Planned Refactor" content into the past tense once the work is complete.

	=== Definition of Done ===		=== Definition of Done ===
Line 413:		Line 413:
	== Demo Video ==		== Demo Video ==

	'''Demo Video:''' https://youtu.be/Zg-fQmIUCSc		'''Demo Video for Old Implementation:''' https://youtu.be/Zg-fQmIUCSc
			'''Demo Video for Refactor:''' https://youtu.be/fhK0roDhT7k

	The demo walks through the current (pre-refactor) implementation:		The demo walks through the current (pre-refactor) implementation:

File:E2605 rubric reset sequence.png

Vagarwa3 — Wed, 29 Apr 2026 02:00:06 GMT

Vagarwa3 uploaded File:E2605 rubric reset sequence.png

New page

File:E2605 rubric lookup sequence.png

Vagarwa3 — Wed, 29 Apr 2026 01:59:42 GMT

Vagarwa3 uploaded File:E2605 rubric lookup sequence.png

New page

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

Psubram3 — Wed, 29 Apr 2026 01:58:21 GMT

← Older revision		Revision as of 01:58, 29 April 2026
Line 142:		Line 142:
	Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.		Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

	The Rubrics tab is a ~~pure~~ consumer of ~~this~~ configuration. ~~It reads~~ the ~~list of assigned duties from~~ the ~~assignment state~~ and ~~generates one teammate review row per~~ role~~, named~~ <code>Teammate Review for {RoleName}</code>~~. If~~ role-based ~~mode~~ is ~~off or no duties are~~ assigned~~, no role rows appear. The Rubrics tab has no role management widgets of its own~~. This ~~separation~~ means an instructor ~~cannot accidentally configure roles in two places, and~~ rubric rows ~~always reflect what was actually saved~~.		The Rubrics tab is a consumer of role configuration, but it owns its own rubric variation settings. The <code>review_rubric_varies_by_role</code> checkbox lives in the Rubrics tab alongside the existing round- and topic-variation checkboxes, because it controls rubric structure rather than role assignment. Role rows (<code>Teammate Review for {RoleName}</code>) appear only when both <code>Is role based?</code> is enabled in Review Strategy and <code>review_rubric_varies_by_role</code> is enabled in Rubrics, and at least one duty is assigned. This two-gate design means an instructor explicitly opts into role-specific rubric rows and does not get them as an automatic side-effect of enabling role-based mode.

	===SOLID Principles Applied===		===SOLID Principles Applied===
Line 180:		Line 180:
	* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).		* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
	* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.		* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
	* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
	* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
	* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
	* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

	===Frontend files changed===		===Frontend files changed===
	* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy ~~for~~ enabling role mode, ~~attaching existing~~ duties, inline duty creation, per-role limit ~~updates~~, and ~~syncing~~ assignment ~~duties~~ state.		* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls across two tabs: (1) Review Strategy tab owns role assignment — enabling role mode (<code>Is role based?</code>), selecting duties from a dropdown, adding/removing duties (optimistically), inline duty creation via DutyEditor modal, and editing per-role member limits via an inline number input in the assigned roles table that fires <code>PATCH .../limit</code> on blur; (2) Rubrics tab owns <code>review_rubric_varies_by_role</code> checkbox alongside the existing round- and topic-variation checkboxes, and dynamically renders one teammate review row per assigned role when both that checkbox and role mode are active. Duplicate duty state declarations introduced by an upstream merge were removed; the entire role assignment flow was consolidated into a single consistent state path.
	* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.		* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.
			* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Added Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
			* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Added API integration method for duty updates and refreshes team state after role change.
			* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extended team member payload typing to include role/duty metadata required by the student UI.


Line 206:		Line 206:
	====5) Rubric rows generated from assignment role data====		====5) Rubric rows generated from assignment role data====
	Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.		Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

			====6) Optimistic add/remove for role assignment====
			When an instructor adds or removes a duty from an assignment, the UI updates immediately without waiting for the API response. If the request fails, the change is rolled back and the previous state is restored. This keeps the editor responsive for operations that are expected to succeed in the common case.

	==Testing Plan==		==Testing Plan==
Line 236:		Line 239:
	# Go to Review Strategy.		# Go to Review Strategy.
	# Enable <code>Is role based?</code>.		# Enable <code>Is role based?</code>.
	# Assign one or more existing roles.		# Assign one or more existing roles from the dropdown — they appear immediately in the table (optimistic update).
	# Click <code>Create a new role</code> if needed, ~~add~~ role name, then ~~create it~~.		# Click <code>Create a new role</code> if needed, fill in the role name, then confirm.
	# ~~Set~~ <code>Max members</code> ~~for~~ assigned roles.		# Edit the <code>Max members</code> value inline in the assigned roles table; click away to save.
	# Navigate to Rubrics.		# Navigate to Rubrics.
	# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.		# Enable <code>review_rubric_varies_by_role</code>.
	# ~~Disable~~ role-based ~~mode~~ and verify role controls~~/rows~~ are hidden.		# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered for each assigned role.
			# Uncheck <code>review_rubric_varies_by_role</code> and verify role rows disappear.
			# Return to Review Strategy, disable <code>Is role based?</code>, and verify role controls are hidden.


	==Future Work==		==Future Work==
	* Student-facing role selection UX in team pages.
	* Team-level role-capacity enforcement UX feedback.		* Team-level role-capacity enforcement UX feedback.
	* Additional integrated end-to-end tests across instructor and student workflows.		* Additional integrated end-to-end tests across instructor and student workflows.

File:E2605 class diagram.png

Vagarwa3 — Wed, 29 Apr 2026 01:57:41 GMT

Vagarwa3 uploaded File:E2605 class diagram.png

New page

CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes

Amejari — Wed, 29 Apr 2026 01:57:25 GMT

← Older revision		Revision as of 01:57, 29 April 2026
Line 55:		Line 55:
	* What is the next task the student should work on? (<code>next_incomplete_task</code>)		* What is the next task the student should work on? (<code>next_incomplete_task</code>)

	==== What ~~Will Change~~ ====		==== What Changed ====

			The <code>TaskOrdering</code> namespace was removed from the application code. Its orchestration responsibilities now live on <code>StudentTask</code> as shared class methods used by both <code>StudentTasksController</code> and <code>ResponsesController</code>.

	~~The five~~ <code>~~TaskOrdering~~</code> ~~files will be deleted~~. ~~Their responsibilities will be redistributed~~ as ~~follows~~:		<code>BaseTask</code> was replaced by <code>StudentTask::BaseTaskItem</code>. <code>QuizTask</code> and <code>ReviewTask</code> were replaced by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>, implemented as model classes that inherit from <code>StudentTask::BaseTaskItem</code>.

	* <code>BaseTask</code>, <code>ReviewTask</code>, and <code>QuizTask</code> will be replaced by <code>BaseTaskItem</code>, <code>ReviewTaskItem</code>, and <code>QuizTaskItem</code> — defined as '''inner classes inside <code>StudentTasksController</code>''', with no separate files or namespace.		<code>TaskFactory</code> and <code>TaskQueue</code> were eliminated. Their former responsibilities are now handled by <code>StudentTask.build_tasks</code>, <code>StudentTask.find_task_for_map</code>, <code>StudentTask.prior_tasks_complete?</code>, and <code>StudentTask.ensure_response_objects!</code>.
	* <code>TaskFactory</code> will be eliminated entirely. Instead of a factory object, <code>build_tasks</code> — a private controller method — will directly instantiate <code>QuizTaskItem</code> or <code>ReviewTaskItem</code> based on what response maps and ~~questionnaires exist for the participant.~~
	* <code>TaskQueue</code> ~~will be~~ eliminated ~~entirely~~. ~~Its three query methods (~~<code>~~map_in_queue?~~</code>, <code>~~prior_tasks_complete_for?</code>, <code>next_incomplete_task</code>) will be replaced by equivalent private controller methods: <code>~~find_task_for_map</code>, <code>prior_tasks_complete?</code>, and ~~a direct~~ <code>~~tasks~~.~~find</code> call in the <code>next_task~~</code> ~~action~~.

	The inner classes will share the following interface via <code>BaseTaskItem</code>:		The inner classes will share the following interface via <code>BaseTaskItem</code>:
Line 129:		Line 129:
	! Method !! Role		! Method !! Role
	\|-		\|-
	\| <code>resolve_context_for_assignment(assignment_id)</code> \|\| Finds ~~<code>AssignmentParticipant</code> by~~ current user and assignment, ~~finds <code>TeamsParticipant</code>,~~ resolves duty ~~via <code>team_participant.duty_id</code> with fallback to <code>participant.duty_id</code>~~		\| <code>StudentTask.resolve_context_for_assignment(user, assignment_id)</code> \|\| Finds the participant for the current user and assignment, then resolves the team participant and duty
	\|-		\|-
	\| <code>resolve_context_for_participant(participant)</code> \|\| ~~Same~~ context ~~resolution~~ starting from a known participant ~~rather than an assignment id~~		\| <code>StudentTask.resolve_context_for_participant(participant)</code> \|\| Builds the same task context starting from a known participant
	\|-		\|-
	\| <code>build_tasks(context)</code> \|\| ~~Queries <code>ReviewResponseMap</code>,~~ quiz ~~questionnaire, and existing <code>QuizResponseMap<~~/~~code> records; instantiates <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> in the correct order based on duty permissions~~		\| <code>StudentTask.build_tasks(context)</code> \|\| Builds the ordered quiz/review task list
	\|-		\|-
	\| <code>ensure_response_objects!(tasks)</code> \|\| ~~Calls <code>ensure_response_map!</code>~~ and ~~<code>ensure_response!</code> on every task~~		\| <code>StudentTask.ensure_response_objects!(tasks)</code> \|\| Ensures response maps and response records exist
	\|-		\|-
	\| <code>find_task_for_map(tasks, map_id)</code> \|\| ~~Returns~~ the task ~~whose <code>response_map.id</code> matches the given~~ map id		\| <code>StudentTask.find_task_for_map(tasks, map_id)</code> \|\| Finds the task associated with a response map
	\|-		\|-
	\| <code>prior_tasks_complete?(tasks, ~~target_task~~)</code> \|\| ~~Returns false if any task appearing before the target in the list has <code>completed? == false</code>~~		\| <code>StudentTask.prior_tasks_complete?(tasks, current_task)</code> \|\| Checks whether all earlier tasks are submitted
	\|}		\|}

Line 163:		Line 163:
	# '''Queue order check''' — <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created		# '''Queue order check''' — <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

	==== What ~~Will Change~~ ====		==== What Changed ====

	The <code>GET</code> and <code>PATCH</code> endpoints are unaffected. For <code>POST /responses</code>, the <code>enforce_task_order!</code> method currently calls <code>TaskOrdering::TaskQueue</code> directly. After the refactor, it will instead reuse the same <code>build_tasks</code> and <code>prior_tasks_complete?</code> private methods that <code>StudentTasksController</code> uses — either by extracting them into a shared concern or by duplicating the minimal logic in <code>ResponsesController</code>. Either way, the status codes (403 when order is violated, 201 on success) and the ownership check behavior will remain exactly the same.

			The <code>GET</code> endpoint is unaffected. The <code>POST</code> and <code>PATCH</code> endpoints now both call <code>enforce_task_order!</code>, which reuses the shared <code>StudentTask</code> task-building and prerequisite-checking methods.
	== Technical Deep Dive ==		== Technical Deep Dive ==

Line 408:		Line 407:

	* <code>StudentTasksController</code> and <code>ResponsesController</code> no longer reference <code>TaskOrdering</code>.		* <code>StudentTasksController</code> and <code>ResponsesController</code> no longer reference <code>TaskOrdering</code>.
	* Sequencing and gating logic lives in ~~private controller~~ methods ~~with no extra namespace~~.		* Sequencing and gating logic lives in shared <code>StudentTask</code> class methods.
	* Quiz/review differences are encapsulated by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> ~~inner classes~~.		* Quiz/review differences are encapsulated by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>.
	* ~~All legacy~~ <code>task_ordering</code> source ~~and spec~~ files ~~are deleted.~~		* Legacy <code>app/models/task_ordering</code> source files have been removed.
	* All specs pass with no API contract regression.

	== Demo Video ==		== Demo Video ==
Line 444:		Line 442:
	* Akhil Kumar		* Akhil Kumar
	* Dev Patel		* Dev Patel
	* Arnav ~~Merjeri~~		* Arnav Mejari

	'''Mentor:'''		'''Mentor:'''

CSC/ECE 517 Spring 2026 - E2605. Specialized Rubrics for Different Topic Types

Vagarwa3 — Wed, 29 Apr 2026 01:56:08 GMT

Show changes

CSC/ECE 517 Spring 2026 - E2612. Course-based reports

Rsgopara — Wed, 29 Apr 2026 01:16:50 GMT

Updated wiki with implementation plan/details and a screenshot of the frontend.

Show changes

File:E2612-FinalFrontend1.png

Rsgopara — Tue, 28 Apr 2026 23:43:00 GMT

Rsgopara uploaded File:E2612-FinalFrontend1.png E2612 frontend for course based reports

New page

== Summary ==
E2612 frontend for course based reports

CSC/ECE 517 Spring 2026 - E2609. Review calibration

Xmi — Tue, 28 Apr 2026 23:25:04 GMT

← Older revision		Revision as of 23:25, 28 April 2026
Line 299:		Line 299:
	* [https://wiki.expertiza.ncsu.edu/index.php?title=Main_Page Expertiza wiki main page]		* [https://wiki.expertiza.ncsu.edu/index.php?title=Main_Page Expertiza wiki main page]
	* Response maps wiki — structure of <code>ResponseMap</code> [https://wiki.expertiza.ncsu.edu/index.php?title=Response_maps Response Maps Wiki]		* Response maps wiki — structure of <code>ResponseMap</code> [https://wiki.expertiza.ncsu.edu/index.php?title=Response_maps Response Maps Wiki]
	* Front-end pull request: [https://github.com/expertiza/reimplementation-front-end/pull/177 ~~Backend PR~~]		* Front-end pull request: [https://github.com/expertiza/reimplementation-front-end/pull/177 expertiza/reimplementation-front-end#177]
	* Back-end pull request: [https://github.com/expertiza/reimplementation-back-end/pull/341 ~~Frontend PR~~]		* Back-end pull request: [https://github.com/expertiza/reimplementation-back-end/pull/341 expertiza/reimplementation-back-end#341]

	== Team ==		== Team ==

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

Awainga — Tue, 28 Apr 2026 23:09:14 GMT

← Older revision		Revision as of 23:09, 28 April 2026
Line 24:		Line 24:
	\|}		\|}

	~~== Demo Video Link ==~~

	* Demo video: INSERT_DEMO_VIDEO_LINK_HERE

	== Why This Project Matters ==		== Why This Project Matters ==
Line 355:		Line 352:
	</syntaxhighlight>		</syntaxhighlight>

			== Demo Video Link ==

			* Demo video: https://youtu.be/lwW9BuSOeUk

	== Definition of Done Status ==		== Definition of Done Status ==

CSC/ECE 517 Spring 2026 - E2617. Testing Questionnaire and Course Models

Zobrook2 — Tue, 28 Apr 2026 22:30:20 GMT

Running Tests

← Older revision		Revision as of 22:30, 28 April 2026
Line 860:		Line 860:
	ENV['COVERAGE_STARTED'] = 'true'		ENV['COVERAGE_STARTED'] = 'true'
	end		end
			</syntaxhighlight>

			Then, run the test suite using the following:

			<syntaxhighlight lang="ruby">
			bundle exec rspec spec/models/questionnaire_spec.rb spec/models/course_spec.rb spec/models/question_advice_spec.rb
	</syntaxhighlight>		</syntaxhighlight>

CSC/ECE 517 Spring 2026 - E2617. Testing Questionnaire and Course Models

Mmnguye5 — Tue, 28 Apr 2026 22:27:52 GMT

QuestionAdvice

← Older revision		Revision as of 22:27, 28 April 2026
Line 342:		Line 342:
	==== QuestionAdvice ====		==== QuestionAdvice ====

	For QuestionAdvice use ~~fixtures~~ to load data into database to test that it is being saved and exported properly. As it stands, there isn't that much logical complexity with the data inside QuestionAdvice itself as it is more concerned with exporting data into csv or json files for storage. The fixtures are stored in question_advice.yml under the fixtures folder.		For QuestionAdvice use factories to load data into database to test that it is being saved and exported properly.

	<pre>		<pre>
	#question_advice.~~yml~~		# spec/factories/question_advice.rb
			FactoryBot.define do
	~~question_advice_1~~:		factory :question_advice do
	~~id: 1~~		score {5}
	~~question_id: 1~~		association :item
	score: 5		advice {'default advice'}
	~~advice~~: ~~"This is some advice for question 1."~~		end
			end</pre>
	~~question_advice_2:~~
	~~id: 2~~
	~~question_id: 2~~
	~~score: 3~~
	advice~~: "This is some~~ advice ~~for question 2."~~
	</pre>

	== Test Methods Overview ==		== Test Methods Overview ==

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

Jweisz — Tue, 28 Apr 2026 22:26:20 GMT

Tests (74 total)

Show changes

CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller

Awainga — Tue, 28 Apr 2026 17:09:28 GMT

Show changes

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

Psubram3 — Tue, 28 Apr 2026 16:26:22 GMT

Previous Issues

CSC/ECE 517 Spring 2026 - E2609. Review calibration

Rspalimk — Tue, 28 Apr 2026 15:34:02 GMT

← Older revision		Revision as of 15:34, 28 April 2026
Line 268:		Line 268:

	<div style="text-align:center; margin-top:0.2em;">'''Figure 3.''' Rubric detail tab: select a student reviewer from the dropdown to see their score versus the instructor's score for each rubric item, along with both text comments and a mini class-distribution chart.</div>		<div style="text-align:center; margin-top:0.2em;">'''Figure 3.''' Rubric detail tab: select a student reviewer from the dropdown to see their score versus the instructor's score for each rubric item, along with both text comments and a mini class-distribution chart.</div>


			=== Demo and temporary code ===

			Because the full instructor review form is out of scope, a <code>POST …/:map_id/mock_instructor_response</code> route (tagged <code>DEMO_INSTRUCTOR_RESPONSE</code>) seeds a submitted instructor <code>Response</code> via <code>Demo::CalibrationInstructorSeeder</code>, and a rake task (<code>lib/tasks/calibration_demo.rake</code>) populates a local dataset so the report UI can be demonstrated end-to-end. Both the route and the service file live in gitignored paths and should be deleted once the real review form is integrated.

	== Testing ==		== Testing ==

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

Atmai — Tue, 28 Apr 2026 14:55:26 GMT

← Older revision		Revision as of 14:55, 28 April 2026
(One intermediate revision by the same user not shown)
Line 579:		Line 579:
	=== Github Pull Request ===		=== Github Pull Request ===

	https://github.com		* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/179
			* Backend: https://github.com/expertiza/reimplementation-back-end/pull/345
	=== Video ===		=== Video ===

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

Psubram3 — Tue, 28 Apr 2026 06:50:35 GMT

Sequence Diagram

← Older revision		Revision as of 06:50, 28 April 2026
(4 intermediate revisions by the same user not shown)
Line 163:		Line 163:
	==ER Diagram==		==ER Diagram==

	[[File:2614_er.png\|thumb\|~~500px~~\|left\|ER Diagram]]		[[File:2614_er.png\|thumb\|1000px\|left\|ER Diagram]]
	<br clear="all" />		<br clear="all" />

	==Sequence Diagram==		==Sequence Diagram==
	[[File:2614_seq.png\|thumb\|left\|~~500px~~\|Sequence Diagram]]		[[File:2614_seq.png\|thumb\|left\|1000px\|Sequence Diagram]]
	<br clear="all" />		<br clear="all" />

File:2614 er.png

Psubram3 — Tue, 28 Apr 2026 06:46:39 GMT

Psubram3 uploaded a new version of File:2614 er.png

New page

← Older revision		Revision as of 16:26, 28 April 2026
(One intermediate revision by the same user not shown)
Line 14:		Line 14:
	The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.		The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

	===Assignment-Scoped Role Configuration===		====Assignment-Scoped Role Configuration====
	A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.		A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

	===Complete Assignment-Duty API Lifecycle===		====Complete Assignment-Duty API Lifecycle====
	The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.		The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

	===Assignment Payload Role Context===		====Assignment Payload Role Context====
	For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.		For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

	===Instructor Workflow in Assignment Editor===		====Instructor Workflow in Assignment Editor====
	Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.		Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

	===Role-Driven Rubric Behavior===		====Role-Driven Rubric Behavior====
	When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.		When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

	===Student Role Validation by Assignment Scope===		====Student Role Validation by Assignment Scope====
	When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.		When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

	===Validation and Regression Coverage===		====Validation and Regression Coverage====
	Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.		Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

Line 38:		Line 38:
	Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.		Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

	===Data Model Mismatch===		====Data Model Mismatch====
	The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.		The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

	===Missing Assignment-Duty Lifecycle API===		====Missing Assignment-Duty Lifecycle API====
	The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.		The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

	===Disconnected Role Configuration and Rubric Rendering===		====Disconnected Role Configuration and Rubric Rendering====
	Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.		Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

	===Missing Role Data in Assignment Serializer===		====Missing Role Data in Assignment Serializer====
	The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.		The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.