Run Report Domain Design

Document Type: Domain Design (Tier 2) Domain: RUNRPT Domain Character: Stateful SRS Reference: runfile-report.md, comments.md Status: Draft Last Updated: 2026-01-25

---

1. Overview

1.1 Purpose

The Run Report domain provides the primary interface for viewing, analyzing, and managing individual run file contents. It orchestrates well data display, quality control analysis, result resolution workflows, and export operations.

This is a stateful domain because it manages:

• Run entity lifecycle (upload, analysis, resolution, export)
• Well entity state transitions (error, resolved, exported)
• Resolution workflow state (proposed, approved, rejected)
• Widget configuration state (open/closed, pinned, position)

The domain coordinates heavily with NOTIF for status notifications, COMMENTS for user annotations, and the rules engine for outcome determination.

1.2 Requirements Covered

REQ ID	Title	Priority
REQ-RUNRPT-001	Display Run File Contents	Must
REQ-RUNRPT-002	Access Analytical Widgets	Must
REQ-RUNRPT-003	Re-analyze Run File	Must
REQ-RUNRPT-004	Print Run File Report	Must
REQ-RUNRPT-005	View Run Information	Must
REQ-RUNRPT-006	Edit Well Information	Must
REQ-RUNRPT-007	Manage Well Results	Must
REQ-RUNRPT-008	Export Run Results to LIMS	Must
REQ-RUNRPT-009	Sort Well Table	Should
REQ-RUNRPT-010	Filter Well Table	Should
REQ-RUNRPT-011	Display Amplification Curves	Should
REQ-RUNRPT-012	Provide Well Action Menu	Should
REQ-RUNRPT-013	Select Wells	Should
REQ-RUNRPT-014	Display Run File Notifications	Must
REQ-RUNRPT-015	Configure Composite Assay Outcomes	Should
REQ-RUNRPT-016	Display Accession History	Should
REQ-RUNRPT-017	Support Multi-Site Operation	Should
REQ-RUNRPT-018	Display Westgard Quality Control Analysis	Must
REQ-RUNRPT-019	Display Assay Summary	Should
REQ-RUNRPT-020	Display Outcome Summary	Should
REQ-RUNRPT-021	Display Plate Map	Should
REQ-RUNRPT-022	Display Quantification Analysis	Should
REQ-RUNRPT-023	Bulk Edit Wells	Should
REQ-RUNRPT-024	Bulk Manage Results	Should
REQ-RUNRPT-025	Display System Flags	Should
REQ-RUNRPT-026	Warn Before Losing Unsaved Changes	Should
REQ-RUNRPT-027	Persist Widget State	Should
REQ-RUNRPT-028	Validate Well Data	Must
REQ-COMMENTS-001	Tag Internal Users in Comments	Must
REQ-COMMENTS-002	Tag External Users by Email	Should
REQ-COMMENTS-003	Send Email Notifications for Tags	Must
REQ-COMMENTS-004	Configure Notification Preferences	Should
REQ-COMMENTS-005	Display Notification Indicator	Must
REQ-COMMENTS-006	Display Notifications List	Must
REQ-COMMENTS-007	Manage Notification Read Status	Should
REQ-COMMENTS-008	Mark All Notifications as Read	Should
REQ-COMMENTS-009	Navigate to Tagged Comments	Must
REQ-COMMENTS-010	Filter Mentionable Users by Role	Must

1.3 Constraints

Tier 2 Constraint: This document describes ownership, patterns, and design rationale. It links to reference docs for full schemas and API specifications.

1.4 Dependencies

Direction	Domain/Component	Purpose
Consumes	Kit Configuration	Mix/target definitions, display order
	Analyzer/Rules Engine	Well outcome determination
	Client Configuration	Widget availability, export formats
	Notification Subsystem	Status indicators, counts
Provides to	RUNFILE List	Run status, metadata
	LIMS Integration	Export files
	Print System	Formatted reports

---

2. Component Architecture

2.1 Component Diagram

2.2 Component Responsibilities

Component	Layer	Responsibility	REQ Trace
Run	Backend Model	Core run entity with metadata, relationships, status	REQ-RUNRPT-001, 005, 014
Well	Backend Model	Well entity with results, errors, resolution state	REQ-RUNRPT-001, 006, 007, 008
Comment	Backend Model	Polymorphic comments on runs and wells	REQ-COMMENTS-001 through 009
Notification	Backend Model	User notification entities with read status	REQ-COMMENTS-005 through 008
GetRunStatus	Backend Service	Aggregate run status calculation	REQ-RUNRPT-001
RunsController	Backend Controller	Run CRUD and query operations	REQ-RUNRPT-001, 003, 005
WellsController	Backend Controller	Well editing and resolution operations	REQ-RUNRPT-006, 007
CommentsController	Backend Controller	Comment CRUD with mention handling	REQ-COMMENTS-001, 002
NotificationsController	Backend Controller	Notification read status management	REQ-COMMENTS-007, 008
RunResultExportJob	Backend Job	Asynchronous LIMS export generation	REQ-RUNRPT-008
RunView	Frontend View	Main run report page orchestration	REQ-RUNRPT-001, 002
WellsTable	Frontend Component	Well data table with selection	REQ-RUNRPT-001, 009, 010, 013
WidgetSystem	Frontend Component	Analytical widget container/state	REQ-RUNRPT-002, 027
EditWellWidget	Frontend Component	Well property editing	REQ-RUNRPT-006, 023
ManageResultsWidget	Frontend Component	Resolution workflow UI	REQ-RUNRPT-007, 024
CommentSystem	Frontend Component	Comment display and mention handling	REQ-COMMENTS-001, 009, 010

---

3. Data Design

3.1 Entities

This domain owns the following entities:

Entity	Table	Purpose
Run	runs	Core run file entity with metadata
Well	wells	Individual well results and state
Comment	comments	Polymorphic comments (runs, wells)
Notification	notifications	User-targeted notifications

See Database Reference for full schema.

3.2 Entity Relationships

3.3 Run Status Calculation

The GetRunStatus service computes aggregate run status based on well states:

Algorithm: Calculate Run Status

Inputs:
- wells: Collection<Well> - All patient wells in the run

Outputs:
- status: string - One of the run status values

Steps:
1. Partition wells into categories:
   a. notExportedWells: wells where export_date is null
   b. errorWells: wells with Error, Label Error, or Associate Control Error
   c. limsStatusWells: wells with a lims_status set

2. Determine status:
   a. If notExportedWells is empty:
      Return 'ALL_WELLS_EXPORTED'
   b. If errorWells is empty:
      Return 'ALL_WELLS_READY_FOR_EXPORT'
   c. If limsStatusWells is empty:
      Return 'NO_EXPORT_ERRORS_TO_RESOLVE'
   d. Otherwise:
      Return 'SOME_WELLS_READY_FOR_EXPORT_WITH_ERRORS_TO_RESOLVE'

Notes:
- Only patient wells are considered (controls excluded)
- The presence of limsStatusWells indicates resolvable errors

3.4 Data Structures

Run Constants

const RUN_STATUS = [
    'ALL_WELLS_EXPORTED' => 1,
    'ALL_WELLS_READY_FOR_EXPORT' => 2,
    'NO_EXPORT_ERRORS_TO_RESOLVE' => 3,
    'SOME_WELLS_READY_FOR_EXPORT_WITH_ERRORS_TO_RESOLVE' => 4,
];

const CALIBRATION_STATUS = [
    'NOT_CALIBRATED' => 0,
    'CALIBRATING' => 1,
    'CALIBRATED' => 2,
];

Well Outcome Type Mapping

const OUTCOME_TYPE_TO_BACKGROUND_COLOR = [
    'Passed Control' => 'BLUE',
    'Information' => 'GREEN',
    'Warning' => 'YELLOW',
    'Error' => 'RED',
    'Label Error' => 'RED',
    'Exclude' => 'GRAY',
    'Associate Control Error' => 'RED',
];

const LIMS_STATUS_TO_OUTCOME_TYPE = [
    'EXCLUDE' => 'Error',
    'RPT' => 'Warning',
    'RXT' => 'Warning',
];

---

4. Interface Design

4.1 APIs Provided

Endpoint	Method	Purpose	Response
/api/runs/:id	GET	Get run details with wells	Run with nested wells, notifications
/api/runs/:id/wells	GET	Get wells for run	Paginated wells with relationships
/api/wells/:id	PATCH	Update well properties	Updated well
/api/wells/:id/resolve	POST	Apply resolution to well	Updated well with resolution
/api/runs/:id/export	POST	Trigger LIMS export	Job status
/api/runs/:id/comments	GET/POST	Run-level comments	Comment list/new comment
/api/wells/:id/comments	GET/POST	Well-level comments	Comment list/new comment

4.2 APIs Consumed

Endpoint	Method	Purpose
/api/mixes	GET	Mix definitions for display order
/api/client-configuration	GET	Widget availability, export formats
/api/notifications	GET	User notification counts

4.3 Events

Event	Direction	Payload	Purpose
RunUpdated	Backend -> Frontend	{ run_id, status, wells_updated }	Real-time status updates
WellUpdated	Backend -> Frontend	{ well_id, changes }	Well state change notification
NotificationRead	Backend	{ notification_id, user_id }	Update read status
CommentCreated	Backend	{ comment_id, mentions }	Trigger mention notifications

---

5. Behavioral Design

5.1 Run State Machine

Runs progress through analysis and export states:

5.2 Well State Machine

Individual wells have their own state progression:

5.3 Resolution Workflow

Algorithm: Apply Resolution to Well

Inputs:
- well_id: UUID - Well to resolve
- resolution_code_id: UUID - Resolution to apply
- user_id: UUID - User performing resolution
- message: string (optional) - Resolution reason

Outputs:
- well: Well - Updated well entity

Assumptions:
- User has permission to resolve wells
- Resolution code is valid for the error type

Steps:
1. Load well with error code relationship
2. Validate resolution code is applicable:
   a. Check error type matches resolution's allowed types
   b. Check role priority if applicable
3. Update well:
   a. Set resolution_codes to resolution_code.resolution_code
   b. Set lims_status to resolution_code.limsStatusWhenResolving()
   c. Clear proposed_resolution_code_id if approved
4. If resolution affects other wells (contains 'ALL'):
   a. Find affected wells (same run, same criteria)
   b. Apply resolution to all affected wells
5. Fire WellUpdated event
6. Recalculate run status
7. Return updated well

Notes:
- Some resolutions require manager approval
- Resolution can be rejected, returning well to error state
- Bulk resolutions apply to all selected wells

5.4 Comment Mention Processing

Algorithm: Process Comment Mentions

Inputs:
- comment: Comment - Newly created comment
- mentions: array - Extracted @mentions from text
- commenter: User - User who created the comment

Outputs:
- notifications: Collection<Notification> - Created notifications

Steps:
1. For each mention in mentions:
   a. If mention is email format:
      - Send external email invitation
      - Skip notification creation
   b. Else:
      - Look up user by display name
      - Check mentionable based on commenter's role (REQ-COMMENTS-010)
      - Create Notification for mentioned user

2. For each created notification:
   a. Check user's notification preference
   b. If preference includes 'in-app':
      - Save notification to database
   c. If preference includes 'email':
      - Queue UserHasNotifiedMail job

3. Return created notifications

Notes:
- External email invitations always send email regardless of preference
- Role filtering: JUNIOR/SENIOR/MANAGER can mention JUNIOR/SENIOR/MANAGER
- CLIENT_ADMIN cannot mention anyone
- SUPER_ADMIN can mention all roles

---

6. Error Handling

Condition	Detection	Response	User Impact
Invalid accession characters	Validation rule	Reject input, show validation error	Cannot save until corrected
Control label wildcard error	Validation rule	Reject input, show validation error	Cannot save until corrected
Well label contains "null"	Validation rule	Reject label	Cannot save until corrected
Export location unavailable	File system check	Log error, show user message	Export fails, retry available
No exportable wells	Pre-export validation	Prevent export, show message	Cannot export until wells resolved
Resolution code invalid for error	Business rule	Reject resolution	Must select valid resolution
Concurrent edit conflict	Optimistic locking	Show conflict warning	Must refresh and retry

---

7. Configuration

Setting	Location	Default	Effect
accession_history_enabled	client_configurations	per-client	Enables accession history feature
available_widgets	client_configurations	per-client	Controls widget visibility
available_print_options	client_configurations	per-client	Controls print option visibility
lims_export_formats	client_configurations	per-client	Available export format list
lims_reports_folder	client_configurations	LIMS_Reports	Export destination folder
multi_site_enabled	client_configurations	per-client	Enables multi-site features
default_pinned_widgets	client_configurations	per-client	Widgets pinned by default
count_system_generated_comments	client_configurations	true	Include system comments in counts
default_notification_preference	N/A	Both	Default for new users

See Configuration Reference for details.

---

8. Implementation Mapping

8.1 Code Locations

Component	Type	Path
Run	Model	code/app/Run.php
Well	Model	code/app/Well.php
Comment	Model	code/app/Comment.php
Notification	Model	code/app/Notification.php
GetRunStatus	Service	code/app/GetRunStatus.php
RunsController	Controller	code/app/Http/Controllers/RunsController.php
WellsController	Controller	code/app/Http/Controllers/WellsController.php
CommentsController	Controller	code/app/Http/Controllers/CommentsController.php
RunCommentsController	Controller	code/app/Http/Controllers/RunCommentsController.php
WellCommentsController	Controller	code/app/Http/Controllers/WellCommentsController.php
NotificationsController	Controller	code/app/Http/Controllers/NotificationsController.php
RunResultExportJob	Job	code/app/Jobs/RunResultExportJob.php
RunView	Vue	views/run/RunView.vue

8.2 Requirement Traceability

REQ ID	Design Section	Code Location
REQ-RUNRPT-001	§3.1 Entities, §5.1 Run State	Run.php, Well.php, RunView.vue
REQ-RUNRPT-003	§5.1 Run State	RunAnalyseJob.php
REQ-RUNRPT-006	§5.2 Well State	WellsController.php, EditWellWidget.vue
REQ-RUNRPT-007	§5.3 Resolution Workflow	WellsController.php, ResolutionCode.php
REQ-RUNRPT-008	§4.1 APIs Provided	RunResultExportJob.php
REQ-RUNRPT-014	§1.4 Dependencies (NOTIF)	SDS: NOTIF
REQ-RUNRPT-028	§6 Error Handling	Well.php (validation)
REQ-COMMENTS-001	§5.4 Mention Processing	CommentsController.php, NotifyMentionedUsers.php
REQ-COMMENTS-005	§2.2 Component Responsibilities	Notification.php, NotificationsController.php
REQ-COMMENTS-009	§4.1 APIs Provided	UserHasNotified.php (URL generation)
REQ-COMMENTS-010	§5.4 Mention Processing	Frontend role filtering

---

9. Design Decisions

Decision	Rationale	Alternatives Considered
Run status computed on-demand	Status reflects current well states; caching risks staleness	Persisted status column (rejected: sync complexity)
Polymorphic comments	Enables consistent comment handling for runs and wells	Separate run_comments/well_comments tables (rejected: duplication)
Resolution workflow with approval	Manager oversight for critical decisions	Auto-apply all resolutions (rejected: audit risk)
Widget state in user preferences	Per-user customization without affecting others	Global widget state (rejected: conflicts)
NOTIF integration for notifications	Reuses existing notification infrastructure	Custom notification system (rejected: duplication)
Export as background job	Long-running exports don't block UI	Synchronous export (rejected: timeout risk)

---

10. Related Documents

Document	Relevant Sections
SRS: runfile-report.md	Requirements source
SRS: comments.md	Comment/mention requirements
SDS: NOTIF Domain	Notification indicators
SDS: Architecture	System context
SDS: Data Architecture	Entity relationships
Database Reference	Full schema
Configuration Reference	Client settings