Software Design Specification: Cross-Cutting Concerns

Document Type: System-Level (Tier 1) Status: Draft Last Updated: 2026-01-25

---

1. Purpose

This document describes infrastructure concerns that span all domains in the PCR Analysis System. Cross-cutting concerns are shared services and patterns used throughout the application but not owned by any single domain.

Scope:

• Logging architecture
• Error handling patterns
• Configuration loading
• Caching strategy
• Job queue architecture
• Database connectivity patterns

Constraint: This document does not satisfy requirements directly. It provides context for how domains implement their functionality.

---

2. Logging Architecture

2.1 Overview

The system uses Laravel's logging abstraction backed by Monolog. Logs are centralized through a configurable channel stack.

2.2 Log Channels

Channel	Driver	Purpose	Default Level
stack	stack	Primary channel; aggregates others	debug
single	single	Single file output	debug
daily	daily	Rotating daily logs (14-day retention)	debug
slack	slack	Critical alerts to Slack webhook	critical
stderr	monolog	Container/Lambda stderr output	debug
syslog	syslog	System logging integration	debug
null	monolog	Disabled logging (testing)	-

Configuration: config/logging.php

2.3 Log Levels

Standard PSR-3 log levels apply:

Level	Usage
emergency	System unusable
critical	Critical conditions (triggers Slack)
error	Runtime errors
warning	Exceptional occurrences that are not errors
info	Interesting events (login, file import)
debug	Detailed debug information

2.4 What Gets Logged

Category	Log Level	Examples
Authentication events	info	Login success/failure, session termination
Job failures	error	Queue job exceptions
Database errors	error	Connection failures, query errors
API errors	error/warning	Validation failures, authorization denials
Sentry integration	varies	All errors forwarded to Sentry with breadcrumbs

2.5 External Error Tracking (Sentry)

Sentry captures exceptions with contextual breadcrumbs.

Breadcrumb Categories:

• Laravel logs
• SQL queries (with bindings)
• Queue job information
• Artisan command information

Configuration: config/sentry.php

Privacy: send_default_pii is disabled; no personally identifiable information is transmitted.

---

3. Error Handling

3.1 Exception Hierarchy

3.2 Application Exceptions

Exception	Purpose	User-Facing
ApplicationDatabaseNotReadyException	Aurora Serverless cold start; database waking	Yes (retry prompt)
AuditDatabaseNotReadyException	Audit database unavailable	Yes (retry prompt)
DuplicateRunImportException	Run file already imported	Yes (error message)
ThermocyclerFieldMissingException	Required thermocycler data missing from run file	Yes (validation error)

3.3 Global Exception Handler

Location: app/Exceptions/Handler.php

Handling Rules:

Exception Type	Web Response	API Response
TokenMismatchException	Redirect to login with session timeout message	-
AuthorizationException	Redirect to unauthorized page	403 JSON {"message": "unauthorized"}
All others	Laravel default (error page or debug)	Laravel default (JSON error)

3.4 Sensitive Input Protection

The following inputs are never flashed to session on validation errors:

• password
• password_confirmation

---

4. Configuration Loading

4.1 Configuration Hierarchy

4.2 Environment Variables

Primary configuration source. All sensitive values (credentials, API keys) are stored in environment variables.

Key Environment Variables:

Variable	Purpose
APP_ENV	Environment (production, staging, local)
APP_DEBUG	Debug mode toggle
APP_KEY	Encryption key
DB_*	Database connection
DB_AUDIT_*	Audit database connection
REDIS_*	Redis/ElastiCache connection
AWS_*	AWS credentials and region
SENTRY_DSN	Sentry error tracking

4.3 Laravel Configuration Files

Location: config/*.php

Key Files:

File	Purpose
app.php	Application name, version, timezone, encryption
database.php	Database connections (application + audit)
cache.php	Cache driver and store configuration
queue.php	Queue connections and failed job handling
logging.php	Log channels and levels
sentry.php	Error tracking configuration

4.4 Database Configuration (client_configurations)

Runtime-configurable settings stored in client_configurations table as key-value pairs.

Pattern:

• Name: Configuration key
• Value: Configuration value

Usage: Domain-specific settings that vary per client/site without code deployment.

See SDS: Reference - Configuration for full configuration reference.

---

5. Caching Strategy

5.1 Cache Architecture

5.2 Cache Stores

Store	Driver	Use Case
redis	redis	Production caching (ElastiCache)
file	file	Local development
array	array	Testing (no persistence)
database	database	Alternative persistent cache
dynamodb	dynamodb	AWS-native caching option

Default: file (overridden by CACHE_DRIVER environment variable)

Configuration: config/cache.php

5.3 Cache Key Prefix

All cache keys are prefixed with {APP_NAME}_cache to prevent collisions when sharing cache infrastructure.

5.4 What Gets Cached

Data Type	Cache Location	TTL
Session data	DynamoDB (Vapor default)	Session lifetime
Computation results	Redis	Request-scoped
Configuration lookups	Redis	Varies by domain

Note: Authoritative data lives in Aurora MySQL. Cache contains derived data that can be regenerated.

---

6. Job Queue Architecture

6.1 Overview

The system uses Laravel's queue abstraction for asynchronous processing. Jobs are dispatched to queues and processed by workers (Lambda in production, sync in development).

6.2 Queue Connections

Connection	Driver	Use Case
sync	sync	Development (immediate execution)
database	database	Local async with database backing
sqs	sqs	Production (Amazon SQS)
redis	redis	Alternative production option

Default: sync (overridden by QUEUE_CONNECTION environment variable)

Configuration: config/queue.php

6.3 Job Categories

6.4 Job Inventory

Job	Purpose	Timeout	Retry
RunAnalyseJob	Run file analysis/reanalysis	Default	WithoutOverlapping
RunDataParseJob	Parse imported run file	Default	Default
RunStoreJob	Persist run to database	Default	Default
RunResultExportJob	Export results to LIMS	Default	Default
AuditExportJob	Generate audit export file	900s	1
RunDeleteJob	Delete run file	Default	Default
ConfigDataImportJob	Import configuration data	Default	Default

6.5 Job Patterns

WithoutOverlapping Middleware:

Jobs like RunAnalyseJob use WithoutOverlapping middleware to prevent concurrent processing of the same run.

public function middleware(): array
{
    return [
        (new WithoutOverlapping)->releaseAfter(3),
    ];
}

Transaction Wrapping:

Export jobs wrap operations in database transactions with rollback on failure.

Progress Broadcasting:

Long-running jobs broadcast progress via Pusher for real-time UI updates.

6.6 Failed Jobs

Failed jobs are logged to the failed_jobs table with:

• Connection and queue name
• Payload (serialized job data)
• Exception message and stack trace
• Failed timestamp

Configuration: config/queue.php → failed

---

7. Database Connectivity

7.1 Dual Database Architecture

The system uses separate databases for application data and audit logs.

7.2 Connection Configuration

Connection	Purpose	Database
mysql	Application data (runs, wells, config)	DB_DATABASE
mysql_audit	Audit trail data	DB_AUDIT_DATABASE
mysql_test	Testing database	DB_DATABASE_TEST

Configuration: config/database.php

7.3 Cold Start Handling

Aurora Serverless databases may be paused when idle. The application handles cold starts with:

1. ApplicationDatabaseNotReadyException - Application database waking
2. AuditDatabaseNotReadyException - Audit database waking

User Experience: Retry prompt displayed; database typically available within seconds.

Pooling Configuration: app.database_pooling_time = 5 seconds

7.4 Redis Configuration

Redis (ElastiCache in production) provides:

• Default connection for general use
• Cache connection for caching layer

Prefix: {APP_NAME}_database_ prevents key collisions

---

8. Common Utilities

8.1 Service Providers

Provider	Purpose
AppServiceProvider	Application bindings and boot logic
AuthServiceProvider	Authentication and authorization
BroadcastServiceProvider	Pusher/WebSocket channels
EventServiceProvider	Event-listener registration
RouteServiceProvider	Route loading and configuration
VaporUiServiceProvider	Laravel Vapor dashboard
MicrosoftGraphServiceProvider	SharePoint integration

8.2 Facade Aliases

Standard Laravel facades are aliased for convenience:

• Cache, Config, DB, Log, Mail, Queue, Storage

8.3 Encryption

Algorithm: AES-256-CBC

Key: APP_KEY environment variable (32-character random string)

All sensitive data at rest uses Laravel's encryption service.

---

9. Non-Functional Requirements Coverage

This cross-cutting document provides implementation context for non-functional requirements that span all domains.

REQ ID	Title	Relevant Section	Implementation Notes
REQ-NFR-001	Page Load Time	§2 Logging, §3 Error Handling, §5 Caching	Infrastructure optimization via CDN, caching, and async job processing
REQ-NFR-002	Reanalysis Operation Time	§6 Job Queue	RunAnalyseJob with progress broadcasting via Pusher
REQ-NFR-003	Concurrent User Capacity	§5 Caching, §6 Job Queue, §7 Database	Aurora Serverless auto-scaling, ElastiCache, SQS queues
REQ-NFR-004	Browser Resize Handling	N/A	Frontend concern (Vue.js responsive CSS)
REQ-NFR-005	Zoom Level Usability	N/A	Frontend concern (Vue.js responsive CSS)

Note: REQ-NFR-004 and REQ-NFR-005 are primarily frontend/CSS concerns with no backend implementation anchors. These requirements are satisfied through Vue.js component design and Tailwind CSS responsive utilities.

---

10. Related Documents

Document	Relevance
SDS: Architecture Overview	System architecture context
SDS: Security Architecture	Authentication, authorization
SDS: Reference - Configuration	Full configuration reference
SDD: Architecture	Legacy architecture documentation
SDD: Configuration	Legacy configuration documentation