Software Design Specification: Architecture Overview
Document Type: System-Level (Tier 1) Status: Draft Last Updated: 2026-01-25
1. Purpose
This document describes the high-level architecture of the PCR Analysis System (PCRI.AI). It provides:
- System decomposition into major components
- Technology stack and platform choices
- Architectural patterns employed
- Layer organization and dependencies
This is a synthesis document. It does not trace individual requirements. Domain-specific design is covered in Tier 2 documents.
2. System Overview
PCRI.AI is a web-based clinical laboratory application for automated analysis, quality control, and reporting of real-time PCR data. The system enables:
- Automated run file import and analysis
- Rule-based classification and QC evaluation
- Multi-site laboratory management
- LIMS integration and export
Key characteristics:
- Serverless cloud deployment (AWS Lambda via Laravel Vapor)
- Multi-tenant architecture with site-based access control
- No PII/PHI storage (all data anonymized prior to analysis)
3. High-Level Architecture
3.1 Layer Diagram
This diagram illustrates the high-level component organization. It does not specify all interactions.
3.2 Component Overview
| Component | Purpose | Location |
|---|---|---|
| Vue.js SPA | User interface, state management | resources/frontend/src/ |
| REST API | HTTP endpoints for frontend | routes/api.php, app/Http/Controllers/ |
| Controllers | Request handling, response formatting | app/Http/Controllers/ (~145 controllers) |
| Actions | Single-responsibility business operations | app/Actions/ (~40 action classes) |
| Analyzer Engine | Core analysis orchestration | app/Analyzer/ |
| Rules Engine | Rule execution and evaluation | app/Analyzer/Rules/ (~40 rule classes) |
| Repositories | Data access abstraction | app/Analyzer/Contracts/, implementations |
| Eloquent Models | ORM entities | app/*.php, app/Analyzer/*.php |
4. Technology Stack
4.1 Backend
| Technology | Version | Purpose |
|---|---|---|
| PHP | 8.3+ | Server-side language |
| Laravel | 12.x | Web framework |
| Laravel Vapor | - | Serverless deployment platform |
| Eloquent ORM | - | Database abstraction |
| Laravel Passport/Sanctum | - | API authentication |
4.2 Frontend
| Technology | Purpose |
|---|---|
| Vue.js | Reactive UI framework |
| Vuex | State management (13 store modules) |
| Vue Router | Client-side routing |
4.3 Infrastructure (AWS)
| Service | Purpose |
|---|---|
| AWS Lambda | Serverless compute (via Vapor) |
| Aurora MySQL v2 | Primary database (serverless) |
| Amazon S3 | File storage (run files, exports, archives) |
| Amazon Cognito | User authentication, MFA, SSO |
| Amazon ElastiCache | Redis caching layer |
| Amazon SQS | Message queue for async processing |
| Amazon SES | Email delivery (alternative to SendGrid) |
| Amazon DynamoDB | Session storage (Vapor default) |
4.4 Third-Party Services
| Service | Purpose |
|---|---|
| Pusher | Real-time WebSocket communication |
| SendGrid | Primary email delivery |
| Sentry | Error tracking and performance monitoring |
5. Architectural Patterns
5.1 Domain-Driven Design Elements
The system implements DDD patterns for organizing business logic:
Domain Services:
| Directory | Purpose |
|---|---|
app/Analyzer/ | Core analysis engine - coordinates rule execution |
app/Services/ | Business logic services |
app/Actions/ | Single-responsibility use case handlers |
Domain Models:
| Model | Contract | Description |
|---|---|---|
Well | AnalyzableWell | Core well entity with observations |
Observation | AnalyzableObservation | Target observation entity |
Run | - | Run file entity |
Target | - | Target configuration entity |
Value Objects:
| Class | Purpose |
|---|---|
WellNumber | Immutable well position (A1-H12) |
HasUuid | UUID trait for entity identification |
5.2 Repository Pattern
Configuration data is accessed through repository contracts:
Location: app/Analyzer/Contracts/ (contracts), app/Analyzer/ (implementations)
5.3 Strategy Pattern (Rules Engine)
Analysis rules are implemented as pluggable strategies:
| Component | Location | Purpose |
|---|---|---|
| Rule Contract | app/Analyzer/Contracts/AnalyzerRuleContract.php | Defines rule interface |
| Rule Classes | app/Analyzer/Rules/*.php | Concrete rule implementations |
| Rule Model | app/Rule.php | Database model with strategy mapping |
Mapping: The programmatic_rule_name field maps to PHP class names via App\Analyzer\Rules\{StudlyCase}Rule.
5.4 Factory Pattern
| Factory | Location | Purpose |
|---|---|---|
| Analyzer Factory | app/Analyzer/ | Creates analysis components |
| RunFileConverter Factories | app/RunFileConverter/ | Creates file conversion components |
| Normalizer Factory | app/Analyzer/Normalizer/ | Creates data normalizers |
5.5 MVC + Service Layer
Controllers delegate complex operations to Actions or Services, maintaining thin controller design.
6. Analysis Pipeline
The core analytical workflow follows a 6-stage pipeline:
Supported file formats: .sds, .pcrd, .eds, .ixo
7. Frontend Architecture
7.1 Directory Structure
resources/frontend/src/
├── components/ # Reusable UI components (~50 directories)
├── mixins/ # Shared component logic
│ ├── resolution/ # Error resolution workflows
│ ├── well-multiselect/# Well selection handling
│ └── client-configurations/
├── store/modules/ # Vuex state management (13 modules)
├── views/ # Page-level components
├── router/ # Vue Router configuration
├── plugins/ # Vue plugins
└── utils/ # Utility functions
7.2 State Management (Vuex)
| Module | Purpose |
|---|---|
auth.js | User authentication and session |
runs.js | Recent runs and upload progress |
features.js | Feature flag toggles |
auditOptions.js | Audit trail filtering |
clientConfigurations.js | Client settings |
runOptions.js | Run filtering options |
ljChartSettings.js | Levey-Jennings chart configuration |
7.3 Component Patterns
| Pattern | Purpose | Example |
|---|---|---|
| Mixins | Shared logic across components | Wells.js, FilterWells.js |
| Store Modules | Centralized state | auth.js, runs.js |
| Resolution Components | Error handling workflows | WellResolutionProposalForm.js |
8. Deployment Architecture
8.1 Serverless Model
8.2 Multi-Tenant Architecture
- Client isolation: Each client has dedicated AWS account with S3 and Cognito
- Site-based access: Users assigned to sites; data filtered by site permissions
- Single codebase: Shared application deployed per-client
9. Key Architectural Decisions
| Decision | Rationale |
|---|---|
| Serverless (Lambda/Vapor) | Auto-scaling, pay-per-use, reduced operational overhead |
| Aurora Serverless v2 | Cost optimization for variable workloads, auto-scaling |
| Strategy pattern for rules | New rules added without modifying engine core |
| Repository pattern | Testability, alternative implementations for testing |
| Vuex for state | Predictable state management, component decoupling |
| UUID primary keys | Distributed generation, no collision risk |
| Soft deletes | Audit trail preservation, data recovery |
10. Technology Selection Rationale
This section documents the rationale for key AWS technology selections.
10.1 Compute: AWS Lambda
| Criteria | AWS Lambda | Amazon EC2 |
|---|---|---|
| Cost model | Pay per execution | Pay for provisioned capacity |
| Scaling | Automatic | Manual/Auto Scaling Groups |
| Management | Zero infrastructure | Full server management |
| Cold start | Yes (mitigated by Vapor) | No |
| Best for | Event-driven, variable load | Constant, predictable load |
Decision: Lambda selected due to variable workload patterns and reduced operational overhead.
10.2 Authentication: Amazon Cognito
| Criteria | Amazon Cognito | Laravel Native |
|---|---|---|
| User capacity | Unlimited scaling | Database-bound |
| Features | MFA, TOTP, SSO, SAML | Basic auth only |
| Security | AWS security features | Application-level |
| Cross-device sync | Built-in | Custom implementation |
| Federation | OpenID Connect, SAML | Custom integration |
| Cost | Pay-as-you-go | Infrastructure cost |
Decision: Cognito selected due to enterprise requirements (SAML/SSO, MFA) and scalability needs.
10.3 Database: Aurora Serverless v2
| Criteria | Aurora Serverless v2 | Standard Aurora |
|---|---|---|
| Capacity | Auto-adjusting | Fixed provisioned |
| Cost model | Pay per ACU used | Pay for provisioned |
| Scaling | Automatic, seamless | Manual or scheduled |
| Management | Minimal | Standard RDS management |
| Cold start | Minimal (v2) | None |
Decision: Aurora Serverless v2 selected due to variable workload patterns and cost optimization.
11. Related Documents
| Document | Location | Purpose |
|---|---|---|
| System Context | sds-02-system-context.md | External actors and boundaries |
| Data Architecture | sds-04-data-architecture.md | Global data model |
| Security Architecture | sds-05-security-architecture.md | Auth, authz, audit |
| Cross-Cutting Concerns | sds-06-cross-cutting.md | Logging, errors, config |
| Database Reference | reference/sds-ref-database.md | Full schema |
| API Reference | reference/sds-ref-api.md | Endpoint documentation |
| Legacy SDD Architecture | ../sdd/sdd-architecture.md | Predecessor documentation |