Site Management
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Creating, configuring, and managing sites with S3 storage provisioning Domain: SITE
Statement
The system shall provide capabilities for creating, configuring, and managing organizational sites with automatic cloud storage provisioning.
When a site is created, the system provisions the required S3 folder structure for LIMS exports and run files. Administrators can customize S3 folder naming, and Super Admins can control whether the first site uses root-level or site-specific folder structures. The system enforces multi-site mode restrictions, preventing site management operations when multi-site mode is disabled.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Site | A logical organizational unit representing a physical location or operational division within the system |
| LIMS Export | Laboratory Information Management System export files generated from run analysis |
| S3 Folder | A storage path within Amazon S3 bucket used for organizing site-specific data |
| Multi-site Mode | System configuration allowing multiple sites to be created and managed independently |
| First Site | The initial site created in an environment, which may use root-level folder structure |
| Preserve S3 Structure | Option to maintain root-level folder structure for the first site rather than site-specific folders |
Functional Requirements
Site Creation (REQ-SITE-001)
FR-SITE-001 Provision Storage on Site Creation
The system shall automatically create the required storage folder structure when a new site is created.
Acceptance Criteria:
Storage Provisioning:
- The system shall create a LIMS_Reports folder at the configured storage path for the new site
- The folder creation shall complete as part of the site creation process
- The system shall create the LIMS_Reports folder at path
storage/app/<site_name>/LIMS_Reports
Access Control:
- The system shall restrict site creation to users with Admin role or higher
Error Handling:
- Storage path inaccessible: The system shall fail site creation and display storage access error
- Folder already exists: The system shall use existing folder without error
Trace: Source: 3.0.0-Site Creation (Row 1) | Jira: BT-3996 | Epic: BT-3991 | Tests: BT-3999
S3 Folder Configuration (REQ-SITE-002, REQ-SITE-003, REQ-SITE-004)
FR-SITE-002 Configure S3 Structure Preservation
The system shall allow Super Admins to toggle whether the first site uses root-level or site-specific S3 folder structure.
Acceptance Criteria:
Configuration:
- The system shall provide a toggle to control S3 structure preservation for the first site
- The system shall restrict access to this toggle to Super Admin users
Folder Structure:
- When preservation is enabled, the first site shall use root-level folders (
<env>/LIMS_Export,<env>/Runs) - When preservation is disabled, the first site shall use site-specific folders (
<env>/<site_name>/LIMS_Export,<env>/<site_name>/Runs)
Migration Behavior:
- Changing the toggle shall not migrate existing files to the new folder structure
- New files shall be created in the folder structure corresponding to the current toggle state
Assumptions:
- This setting only affects the first site; subsequent sites always use site-specific folders
Trace: Source: 3.0.0-Sites S3/folder (Rows 1, 2, 5) | Jira: BT-4733 | Epic: BT-4732 | Tests: BT-4735
FR-SITE-003 Specify Custom S3 Folder Name
The system shall allow administrators to specify a custom S3 folder name when creating a site.
Acceptance Criteria:
Folder Naming:
- The system shall accept an optional custom folder name during site creation
- When custom folder name is blank, the system shall use the site name as the folder name
- When custom folder name is provided, the system shall use it instead of the site name
Storage Paths:
- Storage folders shall be created at the specified folder path
- The system shall create S3 storage folder structure at path
Amazon S3/Buckets/<env>/<folder_name>/LIMS_Export - The system shall create S3 completed files storage at path
Amazon S3/Buckets/<env>/<folder_name>/Runs/Completed_files
First Site Dependency:
- For the first site, custom folder name availability shall depend on S3 structure preservation setting (REQ-SITE-002)
Trace: Source: 3.0.0-Sites S3/folder (Row 3) | Jira: BT-4733 | Epic: BT-4732 | Tests: BT-4735 | Related: REQ-SITE-002
FR-SITE-004 Modify Custom S3 Folder Name
The system shall allow administrators to modify the custom S3 folder name for an existing site.
Acceptance Criteria:
Modification:
- The system shall allow editing the custom folder name for existing sites
- Changing the folder name shall create new storage directories at the new path
Data Preservation:
- Existing storage directories shall remain unchanged
- New imports and exports shall use the new folder location
- Files created before the change shall remain in the original folder
Open Questions:
| ID | Question | Owner | Status | Resolution |
|---|---|---|---|---|
| OQ-01 | What data retention policy applies to orphaned folders after folder name changes? | - | Resolved | No change to data retention policy due to orphaning; standard retention policies apply |
Trace: Source: 3.0.0-Sites S3/folder (Row 4) | Jira: BT-4733 | Epic: BT-4732 | Tests: BT-4735
Multi-site Mode (REQ-SITE-005)
FR-SITE-005 Enforce Multi-site Mode Restrictions
The system shall restrict site management features and enforce the default folder structure when multi-site mode is disabled.
Acceptance Criteria:
Feature Restrictions:
- When multi-site mode is disabled, the system shall prevent site creation
- When multi-site mode is disabled, the system shall prevent site editing
- When multi-site mode is disabled, the system shall prevent toggling site enabled status
- When multi-site mode is disabled, the system shall prevent modifying S3 structure preservation
Folder Structure:
- When multi-site mode is disabled, the system shall use the default root-level folder structure
- When multi-site mode is disabled, custom S3 folder name settings shall be ignored
- When multi-site mode is disabled, the system shall use default folder structure paths:
Amazon S3/Buckets/<env>/LIMS_ExportandAmazon S3/Buckets/<env>/Runs/Completed_files
Re-enabling:
- Re-enabling multi-site mode shall restore access to all site management features
Trace: Source: 3.0.0-Disable action buttons (Row 1), 3.0.0-Always enable preserve s3 options (Row 1) | Jira: BT-3035, BT-4733 | Epic: BT-3034, BT-4732 | Tests: BT-4773, BT-4735
Non-Functional Requirements (NFR-SITE-001)
NFR-SITE-001 Storage Operation Reliability
The system shall ensure storage operations maintain data integrity during site creation and configuration changes.
Acceptance Criteria:
- Storage folder creation shall complete atomically (complete or fail, no partial state)
- Concurrent folder operation requests shall be handled safely
- Existing data shall not be modified or deleted when folder settings change
Trace: Source: Derived from behavioral requirements | Tests: [Pending]
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
use_multiple_sites | false | Enables multi-site mode allowing multiple sites | REQ-SITE-005 |
preserve_s3_structure_first_site | true | Preserves root-level folder structure for first site | REQ-SITE-002, REQ-SITE-003 |
Assumptions
- Users performing site creation and editing have Admin role or higher
- Super Admin role is required for S3 structure preservation toggle
- Cloud storage (S3) is configured and accessible
- At least one site exists in all deployment environments
[REVIEW REQUIRED: Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME.]
UI Notes (Illustrative)
FR-SITE-002 UI Specifications
- Toggle button positioned in top right area of Sites page
- Label text: "Preserve S3 Structure for First Site"
- Standard on/off toggle switch component
FR-SITE-003 UI Specifications
- Field label: "Custom S3 Folder Name"
- Displayed in Add New Site modal
- Empty field placeholder indicates site name will be used
FR-SITE-004 UI Specifications
- Field label: "Custom S3 Folder Name"
- Displayed in Edit Site modal
- Current custom folder name pre-populated
FR-SITE-005 UI Specifications
- Disabled controls display grayed-out styling
- Tooltip on disabled controls: "Not allowed when not using multiple sites"
- Affected controls:
- Create Site button
- Site edit buttons
- Site enabled toggle buttons
- Preserve S3 Structure for First Site toggle
Implementation (Illustrative)
| Component | Type | Location | Requirements |
|---|---|---|---|
| Site | Model | code/app/Site.php | REQ-SITE-001, REQ-SITE-002, REQ-SITE-003, REQ-SITE-004, REQ-SITE-005 |
| SitesController | Controller | code/app/Http/Controllers/ | REQ-SITE-001, REQ-SITE-003, REQ-SITE-004 |
| SitesEnableController | Controller | code/app/Http/Controllers/ | REQ-SITE-005 |
| SitesDisableController | Controller | code/app/Http/Controllers/ | REQ-SITE-005 |
| PreserveS3StructureForFirstSiteController | Controller | code/app/Http/Controllers/ | REQ-SITE-002, REQ-SITE-005 |
| UseMultipleSitesFeatureController | Controller | code/app/Http/Controllers/ | REQ-SITE-005 |
| ChangeLoggedInSiteController | Controller | code/app/Http/Controllers/ | REQ-SITE-005 |
| VisibleSitesController | Controller | code/app/Http/Controllers/ | REQ-SITE-005 |
| StoreSiteAction | Action | code/app/Actions/ | REQ-SITE-001, REQ-SITE-003 |
| UpdateSiteAction | Action | code/app/Actions/ | REQ-SITE-004 |
| CreateStorageForSiteAction | Action | code/app/Actions/ | REQ-SITE-001, REQ-SITE-003, REQ-SITE-004 |
| UpdatePreserveS3StructureForFirstSiteAction | Action | code/app/Actions/ | REQ-SITE-002 |
| ToggleUseMultipleSitesFeatureAction | Action | code/app/Actions/ | REQ-SITE-005 |
| EnableSiteAction | Action | code/app/Actions/ | REQ-SITE-005 |
| DisableSiteAction | Action | code/app/Actions/ | REQ-SITE-005 |
| ListVisibleSitesAction | Action | code/app/Actions/ | REQ-SITE-005 |
| UpdateAuthUserLoggedInSiteAction | Action | code/app/Actions/ | REQ-SITE-005 |
Frontend:
| Component Type | Location |
|---|---|
| View | views/Sites.vue |
| Components | components/sites/ |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-SITE-001 | Provision Storage on Site Creation | Test | Site, SitesController, StoreSiteAction, CreateStorageForSiteAction | BT-3999 | Traced |
| REQ-SITE-002 | Configure S3 Structure Preservation | Test | Site, PreserveS3StructureForFirstSiteController, UpdatePreserveS3StructureForFirstSiteAction | BT-4735 | Traced |
| REQ-SITE-003 | Specify Custom S3 Folder Name | Test | Site, SitesController, StoreSiteAction, CreateStorageForSiteAction | BT-4735 | Traced |
| REQ-SITE-004 | Modify Custom S3 Folder Name | Test | Site, SitesController, UpdateSiteAction, CreateStorageForSiteAction | BT-4735 | Traced |
| REQ-SITE-005 | Enforce Multi-site Mode Restrictions | Test | Site, SitesEnableController, SitesDisableController, UseMultipleSitesFeatureController, ToggleUseMultipleSitesFeatureAction, EnableSiteAction, DisableSiteAction, ChangeLoggedInSiteController, VisibleSitesController, ListVisibleSitesAction, UpdateAuthUserLoggedInSiteAction | BT-4773, BT-4735 | Traced |
| NFR-SITE-001 | Storage Operation Reliability | Test | StoreSiteAction (DB transaction), CreateStorageForSiteAction | [Pending] | Traced |
Notes
- Part of the QUEST Separate LIMS exports by Site feature
- Storage location used for LIMS exports when export location is set to cloud
- Custom folder name applies to cloud storage (S3) only
- Gradual migration to new folder structures is supported through folder name changes
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME. | Assumptions | @SME-TBD | TBD |
Acceptance Tests
Test: REQ-SITE-001
Test: Verify folder creation on site creation
Given: User is logged in as Admin
When: User creates new site with name "test_site"
Then: The system shall create storage folder at storage/app/test_site/LIMS_Reports
Test: REQ-SITE-002
Test: Verify toggle access control
Given: User is logged in as Super Admin
When: User navigates to Sites page
Then: The system shall display Preserve S3 Structure for First Site toggle
Test: Verify custom folder field disabled when preserve enabled
Given: Environment has one or more sites
And: Preserve S3 Structure for First Site is enabled
When: User opens Edit modal for first site
Then: Custom S3 Folder Name field shall be disabled
Test: Verify custom folder field enabled when preserve disabled
Given: Environment has one or more sites
And: Preserve S3 Structure for First Site is disabled
When: User opens Edit modal for first site
Then: Custom S3 Folder Name field shall be enabled
Test: Verify folder migration behavior
Given: First site named "Azkaban" exists
And: Preserve S3 Structure for First Site is enabled
And: Existing folders exist at root level
And: Importable file "sample.sds" exists
When: User disables Preserve S3 Structure for First Site
And: User imports sample.sds
And: User exports run
Then: The system shall create new storage directories at site-specific path
And: The system shall preserve previously created root-level storage
Test: REQ-SITE-003
Test: Verify default folder name uses site name
Given: Importable file "sample.sds" exists
And: LIMS export location is set to cloud
When: User creates new site with name "Azkaban"
And: Custom S3 Folder Name is left blank
Then: The system shall create storage using site name as folder name
Test: Verify custom folder name is used
Given: Importable file "sample.sds" exists
And: LIMS export location is set to cloud
When: User creates new site with name "Azkaban"
And: Custom S3 Folder Name is set to "cell_one"
Then: The system shall create storage using "cell_one" as folder name
Test: REQ-SITE-004
Test: Verify folder change creates new directories
Given: Site "Azkaban" exists with custom folder name "cell_one"
And: Importable files exist
And: LIMS export location is set to cloud
And: Files have been imported and exported to cell_one folder
When: User changes custom S3 folder name to "nurburgring"
And: User imports new file
And: User exports new run
Then: The system shall preserve existing storage at cell_one path
And: The system shall create new storage at nurburgring path
Test: REQ-SITE-005
Test: Verify controls disabled when multi-site disabled
Given: Two sites exist (Lab 1, Lab 2)
And: User is logged in as Super Admin
When: User disables Use Multiple Sites
And: User navigates to Sites page
Then: The system shall disable Preserve S3 Structure for First Site toggle
And: The system shall disable Create Site button
And: The system shall disable site edit buttons
And: The system shall disable site enabled toggle buttons
Test: Verify default folder structure when multi-site disabled
Given: Site "Azkaban" exists
And: Importable file exists
And: LIMS export location is set to cloud
And: Preserve S3 Structure is disabled
And: Use Multiple Sites is disabled
When: User imports file
And: User exports run
Then: The system shall create files in root-level folder structure
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Architecture | Amazon S3 storage configuration, S3 folder structure for LIMS_Reports and Runs |
| SDD Deployment Operations | AWS credentials in Vapor enabling S3 storage operations, cloud infrastructure provisioning |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Path-level details folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
Conversion Notes
This domain was converted with minimal consolidation as the requirements represent distinct capabilities:
| Source Requirement | Capability | Disposition |
|---|---|---|
| REQ-SITE-001 | Storage provisioning (distinct lifecycle event) | Preserved as FR-SITE-001 |
| REQ-SITE-002 | S3 structure configuration (Super Admin configuration capability) | Preserved as FR-SITE-002 |
| REQ-SITE-003 | Folder naming at creation (site creation parameter) | Preserved as FR-SITE-003 |
| REQ-SITE-004 | Folder naming at edit (site modification capability) | Preserved as FR-SITE-004 |
| REQ-SITE-005 | Multi-site mode enforcement (system mode behavior) | Preserved as FR-SITE-005 |
| NFR-SITE-001 | Storage operation reliability | Preserved as NFR-SITE-001 |
REQ-SITE-003 and REQ-SITE-004 were evaluated for consolidation but kept separate as they apply to different lifecycle operations (create vs edit) with distinct behaviors.
UI Detail Extraction
UI-specific content was moved to Illustrative section:
- Toggle positioning and labeling
- Modal field layouts
- Disabled state styling and tooltip text
Reversibility: To restore original structure, reference:
- Source:
output/srs/site.md - Git history for original format