Configuration Reference

Document Type: Reference (Tier 3) Status: Draft Last Updated: 2026-01-25

---

1. Purpose

This document catalogs all configuration options available in the PCR Analysis System. It covers:

• Client Configurations: Database-stored settings managed per site
• Environment Variables: Server-level settings defined in .env files
• Laravel Config Files: Application framework settings

Use this document to:

• Find configuration key names and their purpose
• Understand default values and data types
• Identify which settings are site-level vs system-level
• Understand configuration precedence

---

2. Client Configuration Options

Client configurations are stored in the client_configurations database table and can be managed through the UI by Super Users. Each configuration is site-scoped.

2.1 Configuration Types

Type ID	Type Name	Description
1	BOOLEAN	Toggle switch (true/false)
2	TEXT	Free-form text input
3	OPTIONS	Single selection dropdown
4	MULTISELECT	Multiple selection dropdown

2.2 Configuration Groups

Group Name	Order	Description
Login/User Management Options	1	Authentication and user access settings
Import/Data Options	2	Data import and processing settings
Export Options	3	Data export format and destination settings
Display Options	4	UI display preferences
Edit/Manage Results Options	5	Result editing and resolution settings
Westgard Options	6	QC/Westgard analysis parameters

2.3 Login/User Management Options

Key Name	Type	Default	Description
require_cognito_group	BOOLEAN	false	Require users to belong to a Cognito group
block_unauthorized_ip	BOOLEAN	false	Block access from IP addresses not in whitelist
idle_timeout	TEXT	(env)	Session idle timeout in minutes

2.4 Import/Data Options

Key Name	Type	Default	Description
use_sample_type	BOOLEAN	false	Enable sample type classification
use_passive_dye	BOOLEAN	false	Enable passive dye processing
use_extraction_instruments	BOOLEAN	false	Enable extraction instrument tracking
thermocycler_json_field	OPTIONS	(varies)	Thermocycler data source field
well_properties_import_approach	OPTIONS	(varies)	Well property import method
inherit_run_date_if_extraction_date_missing	BOOLEAN	false	Use run date when extraction date is missing
map_passive_observation_roles	BOOLEAN	false	Map passive targets to observation roles
use_fallback_shared_controls	BOOLEAN	false	Enable fallback to shared controls
include_passive_targets_in_targets_count	BOOLEAN	false	Include passive targets in target counts
allowed_characters_in_accessions	MULTISELECT	[]	Allowed characters for accession numbers
prevent_file_import_from_browser	BOOLEAN	false	When enabled, prevents users from uploading run files directly via the browser interface

2.5 Export Options

Key Name	Type	Default	Description
run_result_export_format	OPTIONS	(varies)	Export format (Quest, Viracor, Nottingham, Sherwood, Chantilly, Merck, Eurofins)
run_result_export_strategy	OPTIONS	(varies)	Export strategy (on-demand, automatic)
require_run_result_export_confirmation	BOOLEAN	false	Require confirmation before export
allow_to_re_export_run_results	BOOLEAN	false	Allow re-exporting previously exported results
include_ic_targets_in_run_export	BOOLEAN	false	Include internal control targets in export
include_control_wells_in_lims_export	BOOLEAN	false	Include control wells in LIMS export
lims_export_file_with_timestamp	BOOLEAN	false	Append timestamp to LIMS export filename
separate_quantitative_csv_results	BOOLEAN	false	Export quantitative results to separate CSV
show_comments_in_outcome_export	BOOLEAN	false	Include well comments in outcome export

2.6 Display Options

Key Name	Type	Default	Description
show_patient_well_extraction_information	BOOLEAN	false	Show extraction info for patient wells
truncate_ct_values_to_two_decimal_places_on_graphs	BOOLEAN	false	Limit CT decimal places on graphs
decimal_places_of_ct	TEXT	(varies)	Number of decimal places for CT values
show_accession_history	BOOLEAN	false	Show accession history link
show_evaluation_warning	BOOLEAN	false	Show evaluation warning indicators
display_outcomes_as_hyperlinks	BOOLEAN	false	Render outcomes as clickable links
test_timezone	OPTIONS	(varies)	Timezone for test dates
default_date_format	OPTIONS	(varies)	Date display format
default_time_format	OPTIONS	(varies)	Time display format
count_system_generated_comments	BOOLEAN	false	Include system-generated comments in comment counts

2.7 Edit/Manage Results Options

Key Name	Type	Default	Description
manage_result_workflow	BOOLEAN	false	Enable result management workflow
allow_edit_extraction_information	BOOLEAN	false	Allow editing extraction information
allow_separate_observation_resolution	BOOLEAN	false	Allow observation-level resolution
use_role_type_priority_for_resolution	BOOLEAN	false	Use role type priority for resolution
only_fail_associated_positive_wells	BOOLEAN	false	Only fail wells associated with positive controls

2.8 Westgard Options

Key Name	Type	Default	Description
show_wg_resolved_wells_by_default	BOOLEAN	false	Show resolved wells in Westgard view by default
include_resolved_controls_when_evaluating_westgard	BOOLEAN	false	Include resolved controls in Westgard calculations
round_ninth_reporting_group	BOOLEAN	false	Apply rounding to ninth reporting group
second_priority_of_ordering_wg	OPTIONS	(varies)	Secondary sort priority for Westgard ordering
exclude_higher_ranges_for_sd_comparison	BOOLEAN	false	Exclude higher ranges from SD comparison

---

3. Configuration Dependencies

Some configurations have interdependencies that automatically update related settings.

3.1 Dependency Rules

Parent Configuration	Trigger Value	Affected Configuration	Forced Value
inherit_run_date_if_extraction_date_missing	true	second_priority_of_ordering_wg	'Run created date'
use_extraction_instruments	false	inherit_run_date_if_extraction_date_missing	true
use_extraction_instruments	false	allow_edit_extraction_information	false
use_extraction_instruments	false	show_patient_well_extraction_information	false

Implementation: See code/app/ClientConfigurations/AffectedClientConfigurations.php

---

4. Environment Variables

Environment variables are defined in .env files and loaded at application startup. They cannot be changed at runtime.

4.1 Application Core

Variable	Default	Description	Config File
APP_NAME	Pcr.ai	Application name	app.php
APP_VERSION	1.0.0	Application version	app.php
APP_ORGANIZATION	ArcticHare	Organization name	app.php
APP_ENV	production	Environment (local, staging, production)	app.php
APP_DEBUG	false	Enable debug mode	app.php
APP_URL	http://localhost	Application base URL	app.php
APP_KEY	(required)	Encryption key (32 characters)	app.php

4.2 Database

Variable	Default	Description	Config File
DB_CONNECTION	mysql	Database driver	database.php
DB_HOST	127.0.0.1	Database host	database.php
DB_PORT	3306	Database port	database.php
DB_DATABASE	vapor	Database name	database.php
DB_USERNAME	vapor	Database username	database.php
DB_PASSWORD	(required)	Database password	database.php
DB_AUDIT_CONNECTION	mysql_audit	Audit database connection	database.php
DB_AUDIT_HOST	127.0.0.1	Audit database host	database.php
DB_AUDIT_DATABASE	vapor_audit	Audit database name	database.php

4.3 AWS / S3 Storage

Variable	Default	Description	Config File
FILESYSTEM_DRIVER	local	Default filesystem driver	filesystems.php
FILESYSTEM_CLOUD	s3	Cloud filesystem driver	filesystems.php
AWS_ACCESS_KEY_ID	(required)	AWS access key	filesystems.php
AWS_SECRET_ACCESS_KEY	(required)	AWS secret key	filesystems.php
AWS_DEFAULT_REGION	us-east-1	AWS region	filesystems.php
AWS_BUCKET	(required)	S3 bucket name	filesystems.php

4.4 AWS Cognito Authentication

Variable	Default	Description	Config File
AWS_COGNITO_CLIENT_ID	(required)	Cognito client ID	aws-cognito.php
AWS_COGNITO_CLIENT_SECRET	(required)	Cognito client secret	aws-cognito.php
AWS_USER_POOL_ID	(required)	Cognito user pool ID	aws-cognito.php
AWS_COGNITO_USER_POOL_DOMAIN_NAME	(required)	Cognito user pool domain	aws-cognito.php
AWS_COGNITO_CALLBACK_URL	(required)	OAuth callback URL	aws-cognito.php
AWS_COGNITO_REGION	us-east-1	Cognito region	aws-cognito.php

4.5 Session and Security

Variable	Default	Description	Config File
SESSION_DRIVER	file	Session storage driver	session.php
SESSION_LIFETIME	120	Session lifetime (minutes)	session.php
SESSION_SECURE_COOKIE	true	HTTPS-only cookies	session.php
SESSION_DOMAIN	null	Cookie domain	session.php

4.6 Queue and Jobs

Variable	Default	Description	Config File
QUEUE_CONNECTION	sync	Queue driver	queue.php
SQS_PREFIX	(required for SQS)	SQS queue URL prefix	queue.php
SQS_QUEUE	(required for SQS)	SQS queue name	queue.php

4.7 Mail

Variable	Default	Description	Config File
MAIL_MAILER	sendgrid	Mail driver	mail.php
MAIL_FROM_ADDRESS	hello@ivd.ai	Default from address	mail.php
MAIL_FROM_NAME	Pcr.ai	Default from name	mail.php
SENDGRID_API_KEY	(required for SendGrid)	SendGrid API key	services.php

4.8 External Services

Variable	Default	Description	Config File
PARSER_URL	(required)	Run file parser service URL	parser.php
PARSER_VERSION	(varies)	Parser API version	parser.php
PARSER_API_KEY	(required)	Parser API authentication key	parser.php
SENTRY_DSN	(optional)	Sentry error tracking DSN	sentry.php
SENTRY_ENVIRONMENT	(optional)	Sentry environment name	sentry.php

4.9 IP Restrictions

Variable	Default	Description	Config File
BLOCK_UNAUTHORIZED_IP	false	Enable IP whitelist enforcement	ip.php
IP_WHITELIST	*	Comma-separated allowed IPs	ip.php

4.10 Rate Limiting

Variable	Default	Description	Config File
RATE_LIMIT_MAX_ATTEMPTS	5	Maximum login attempts	rate_limit.php

4.11 Analyzer

Variable	Default	Description	Config File
ANALYZER_MAX_EXECUTION_TIME	90	Analyzer timeout (seconds)	analyzer.php

---

5. Deployment Environment Variables

This section documents environment variables specific to Vapor deployments, including security classifications and platform constraints.

5.1 Security Classifications

Level	Description	Examples
Standard	Non-sensitive config	APP_NAME, APP_ENV
Restricted	Credentials, moderate sensitivity	PUSHER_APP_KEY, DB_HOST
Highly Restricted	Secrets requiring secure storage	API keys, passwords

5.2 Vapor Constraints

Resource	Limit	Notes
Environment variable value	2000 chars	Use secrets for longer values
Secret value	4096 chars	AWS Parameter Store limit
Deployment	Immutable	Changes require redeployment

5.3 Authentication Variables

Variable	Security	Purpose
PREVENT_NATIVE_LOGIN	Standard	Disable native auth when SAML required
AWS_CLIENT_COGNITO_CLIENT_ID	Restricted	Client-specific Cognito app ID
AWS_CLIENT_COGNITO_CLIENT_SECRET	Highly Restricted	Client-specific Cognito secret
AWS_SUPER_ADMIN_ACCESS_KEY_ID	Highly Restricted	Super admin AWS access
AWS_SUPER_ADMIN_SECRET_ACCESS_KEY	Highly Restricted	Super admin AWS secret
AWS_SUPER_ADMIN_DEFAULT_REGION	Standard	AWS region for super admin

5.4 External Service Variables

Variable	Security	Purpose
DXAI_CALIBRATOR_API_URL	Standard	DXAI calibration service endpoint
DXAI_CALIBRATOR_API_KEY	Highly Restricted	DXAI API authentication
DXAI_CALIBRATOR_API_VERSION	Standard	DXAI API version (default: 1)

5.5 Monitoring Variables

Variable	Security	Default	Purpose
VUE_APP_SENTRY_REPLAY_SESSION_SAMPLE_RATE	Standard	0.1	Session replay sampling
VUE_APP_SENTRY_REPLAY_ON_ERROR_SAMPLE_RATE	Standard	1.0	Error replay sampling

5.6 Security Variables

Variable	Security	Purpose
CORS_ALLOWED_ORIGINS	Standard	Whitelist of allowed CORS origins

---

6. Site-Level vs Client-Level Settings

The system distinguishes between two scopes of configuration.

6.1 Scope Definitions

Scope	Storage	Managed By	Example
Site-Level	client_configurations table with site_id	Super User via UI	Export format, display options
System-Level	.env file	System Administrator	Database credentials, AWS keys

6.2 Site-Level Settings

All client configurations in Section 2 are site-scoped. When multi-site mode is enabled:

• Each site has its own copy of all client configurations
• Changes to one site do not affect other sites
• New sites inherit default values

6.3 System-Level Settings

Environment variables apply to the entire application instance:

• Shared across all sites
• Require application restart to take effect
• Managed through deployment configuration

---

7. Configuration Precedence

When multiple configuration sources exist, the following precedence applies:

7.1 Precedence Order (Highest to Lowest)

1. Environment Variables - Override all other sources
2. Client Configuration (Site-Specific) - Database-stored per site
3. Default Values - Hardcoded in migrations or config files

7.2 Feature Toggle Precedence

Feature toggles (managed separately from client configurations):

1. Site-level feature toggle in features table
2. Default value in feature seeder

---

8. Related Documents

Document	Purpose
SRS: Client Configuration	Requirements for configuration management
SRS: Site Management	Site-level configuration requirements
SDS: Cross-Cutting Concerns	Configuration loading patterns
SDS: Security Architecture	Authentication configuration
Database Reference	Schema for client_configurations table

---

9. Code References

Component	Location	Purpose
ClientConfiguration Model	code/app/ClientConfiguration.php	ORM model with type casting
AffectedClientConfigurations	code/app/ClientConfigurations/AffectedClientConfigurations.php	Dependency rules
Config Files	code/config/*.php	Laravel configuration loaders