Runfile List Design

Document Type: Domain Design (Tier 2) Domain: RUNFILE Domain Character: Thin orchestration SRS Reference: runfile-list.md Status: Draft Last Updated: 2026-01-25

---

1. Overview

1.1 Purpose

The Runfile List subsystem provides the primary navigation interface for processed run files. It displays a paginated, filterable, sortable list of runs with metadata and status information, enabling users to locate and open specific run files for detailed analysis.

This is a thin orchestration domain. It coordinates data retrieval and presentation but delegates substantive logic to other domains:

• FILEIMPORT: Run creation via file upload
• RUNRPT: Run details, well data, analysis operations
• NOTIF: Notification badge aggregation
• FILTERS: Filter criteria application
• TABLES: Sorting and pagination

1.2 Requirements Covered

REQ ID	Title	Priority
REQ-RUNFILE-001	Display Runfile List	Must
REQ-RUNFILE-002	Expand Runfile to View Mix Details	Must
REQ-RUNFILE-003	Search Runfiles	Must
REQ-RUNFILE-004	Filter Runfile List	Must
REQ-RUNFILE-005	Sort Runfile List	Must
REQ-RUNFILE-006	Navigate to Run Report	Must
REQ-RUNFILE-007	Configure Visible Columns	Should
REQ-RUNFILE-008	Display Run Status	Must
REQ-RUNFILE-009	Support Multi-Site Operation	Must
REQ-RUNFILE-010	Manage Run Tags	Should
REQ-RUNFILE-011	Organize Runfiles into Categorized Views	Should
NFR-RUNFILE-001	Performance	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	FILEIMPORT	Run creation (delegates file processing)
	FILTERS	Filter criteria application
	TABLES	Sorting and pagination
	NOTIF	Notification badge data
	Site Model	Multi-site filtering
	Tag Model	Run tagging and categorization
Provides to	RUNRPT	Navigation target (run details)
	Frontend	Paginated run list data

---

2. Component Architecture

2.1 Component Diagram

2.2 Component Responsibilities

Component	Layer	Responsibility	REQ Trace
Run	Backend Model	Stores run metadata, relationships, status constants	REQ-RUNFILE-001, 008
Site	Backend Model	Multi-site association	REQ-RUNFILE-009
Tag	Backend Model	Run tagging for organization	REQ-RUNFILE-010, 011
ListRunsAction	Backend Action	Paginated list with filters, sorting	REQ-RUNFILE-001, 003, 004, 005
DeleteRunsAction	Backend Action	Dispatches run deletion job	REQ-RUNFILE-009
CreateRunAction	Backend Action	Delegates to FILEIMPORT	REQ-RUNFILE-001
RunsController	Backend Controller	API endpoint orchestration	All REQ-RUNFILE-*
RunFilters	Backend Filter	Filter criteria implementation	REQ-RUNFILE-004
Runs.vue	Frontend View	List container, view orchestration	REQ-RUNFILE-001, 011
RunFilesTable.vue	Frontend Component	Table display, row expansion	REQ-RUNFILE-001, 002
Tags.vue	Frontend Component	Tag management interface	REQ-RUNFILE-010

---

3. Data Design

3.1 Entities

This domain owns the Run entity and coordinates access to related entities.

Entity	Owner	Usage in RUNFILE
runs	RUNFILE	Primary entity for run metadata
run_tag	RUNFILE	Many-to-many run-tag associations
tags	RUNFILE	Tag definitions
sites	SITE	Multi-site filtering
users	USERMGMT	Uploader reference
run_mixes	RUNRPT	Mix details for expansion

See Database Reference for full schema.

3.2 Data Structures

Run Status 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,
];

List Response Structure

interface RunListItem {
  id: string;
  run_name: string;
  uploaded_user: { username: string };
  runfile_created_at: datetime;
  created_at: datetime;
  updated_at: datetime;
  run_status: RunStatus;
  resolution_status: string;
  site: { name: string } | null;
  tags: Tag[];
  run_mixes: RunMix[];
  notifications: NotificationCounts;
}

interface RunListResponse {
  data: RunListItem[];
  meta: {
    current_page: number;
    per_page: number;
    total: number;
    last_page: number;
  };
}

3.3 State Transitions

This domain is primarily stateless for list operations. Run state transitions (creation, deletion) are managed by other domains:

• Creation: Delegated to FILEIMPORT domain
• Deletion: Dispatches RunDeleteJob asynchronously

---

4. Interface Design

4.1 APIs Provided

Endpoint	Method	Purpose	REQ Trace
/api/runs	GET	List runs with pagination, filters, sorting	REQ-RUNFILE-001, 003, 004, 005
/api/runs	POST	Create run (delegates to FILEIMPORT)	REQ-RUNFILE-001
/api/runs	DELETE	Delete runs for site	REQ-RUNFILE-009
/api/runs/:id	GET	Single run details (delegates to RUNRPT)	REQ-RUNFILE-006

See API Reference for full specification.

4.2 APIs Consumed

Endpoint	Method	Purpose
FILEIMPORT services	Internal	File processing and run creation
NOTIF aggregation	Internal	Notification counts

4.3 Events

Event	Direction	Payload	Purpose
RunUpdated	Backend broadcast	{ run_id }	Real-time list refresh
RunsDeleted	Backend broadcast	{ site_id }	Notify deletion completion
RunAnalyzeStarted	Backend broadcast	{ run_id }	Progress indicator
RunAnalyseProgressUpdated	Backend broadcast	{ run_id, progress }	Progress update

---

5. Behavioral Design

Behavior is straightforward CRUD/delegation. See component responsibilities in section 2.2.

5.1 List Retrieval

Algorithm: List Runs

Inputs:
- filters: RunFilters - Applied filter criteria
- per_page: integer - Pagination size
- sort_by: string | null - Sort column and direction
- patient_id: string | null - Patient search filter

Outputs:
- paginated_runs: LengthAwarePaginator - Paginated run list

Steps:
1. Build base query joining runs with users
2. Eager load relationships: uploadedUser, runTargets, runMixes, site, tags
3. If patient_id provided: filter to runs containing patient
4. If multi-site disabled: filter to default site
5. If sort_by provided: apply sorting via Sortable trait
6. Apply filter criteria via Filterable trait
7. Return paginated results

5.2 Run Status Determination

Run status is computed from well states. See SDS: RUNRPT for well state details.

Status	Condition
ALL_WELLS_EXPORTED	All patient wells have been exported
ALL_WELLS_READY_FOR_EXPORT	All patient wells have no errors
NO_EXPORT_ERRORS_TO_RESOLVE	At least one error, none exportable
SOME_WELLS_READY_FOR_EXPORT_WITH_ERRORS_TO_RESOLVE	Some errors, some exportable

5.3 View Categorization

Runs are categorized into views based on tags and export state:

View	Filter Condition
Active	No archive tags AND not fully exported
Exported	No archive tags AND fully exported
Archived	Has archive tag(s)

---

6. Error Handling

Condition	Detection	Response	User Impact
No runs exist	Empty result set	Return empty paginated response	Empty state message
Filter returns no results	Empty result set	Return empty paginated response	"No matching runs" message
API timeout	Network error	Frontend retry logic	Loading indicator persists
Invalid filter values	Validation layer	422 response	Filter validation error shown

---

7. Configuration

Setting	Location	Default	Effect
use_multiple_sites	features table	false	Enable/disable multi-site filtering
archive_mode_enabled	client_configurations	false	Enable archive view and toggle
default_per_page	Application config	20	Default pagination size

See Configuration Reference for details.

---

8. Implementation Mapping

8.1 Code Locations

Component	Type	Path
Run	Model	code/app/Run.php
Tag	Model	code/app/Tag.php
Site	Model	code/app/Site.php
RunsController	Controller	code/app/Http/Controllers/RunsController.php
ListRunsAction	Action	code/app/Actions/Runs/ListRunsAction.php
DeleteRunsAction	Action	code/app/Actions/Runs/DeleteRunsAction.php
CreateRunAction	Action	code/app/Actions/Runs/CreateRunAction.php
RunFilters	Filter	code/app/Filters/RunFilters.php
RunDeleteJob	Job	code/app/Jobs/RunDeleteJob.php
RunsList	Resource	code/app/Http/Resources/RunsList.php
Runs.vue	View	code/views/Runs.vue
RunFilesTable.vue	View	code/views/RunFilesTable.vue

8.2 Requirement Traceability

REQ ID	Design Section	Code Location
REQ-RUNFILE-001	Section 5.1	ListRunsAction.php, RunsController@index
REQ-RUNFILE-002	Section 2.2	RunFilesTable.vue (frontend expansion)
REQ-RUNFILE-003	Section 5.1	ListRunsAction.php (patient_id filter)
REQ-RUNFILE-004	Section 5.1	RunFilters.php, ListRunsAction.php
REQ-RUNFILE-005	Section 5.1	ListRunsAction.php (Sortable trait)
REQ-RUNFILE-006	Section 2.2	RunsController@show, frontend routing
REQ-RUNFILE-007	Section 2.2	Frontend column configuration
REQ-RUNFILE-008	Section 5.2	Run.php (RUN_STATUS constants)
REQ-RUNFILE-009	Section 5.1	ListRunsAction.php (site filtering)
REQ-RUNFILE-010	Section 2.2	Run.php (tags relation), Tags.vue
REQ-RUNFILE-011	Section 5.3	Frontend view filtering
NFR-RUNFILE-001	Section 5.1	Pagination, eager loading optimizations

---

9. Design Decisions

Decision	Rationale	Alternatives Considered
Thin orchestration pattern	List display has minimal owned logic; complexity is in RUNRPT and FILEIMPORT	Monolithic domain (rejected: poor separation)
Action classes for operations	Testable, single-responsibility units	Controller-only logic (rejected: harder to test)
Eager loading relationships	Prevent N+1 queries on list display	Lazy loading (rejected: performance issues)
Async deletion via job	Long-running operation, non-blocking	Synchronous delete (rejected: timeout risk)
Status as computed constant	Avoid stale cached values	Persisted status field (rejected: sync complexity)

---

10. Related Documents

Document	Relevant Sections
SRS: runfile-list.md	Requirements source
SDS: RUNRPT Domain	Run details, well operations
SDS: FILEIMPORT Domain	Run creation process
SDS: NOTIF Domain	Notification badge data
SDS: Architecture	System architecture context
Database Reference	Schema details
API Reference	Endpoint specifications