Design Specification
HelixOps Quality Management System - GxP Validation Documentation
1. Introduction #
This Design Specification (DS) defines the technical architecture and implementation details for the HelixOps platform. It translates the functional specifications from FS-HELIX-001 into concrete technical designs.
Technical Scope
This document covers system architecture, database design, API specifications, security implementation, and deployment configuration.
2. System Architecture #
Three-Tier Architecture
Technology Stack
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Frontend | React | 18.3.x | UI framework |
| Frontend | TanStack Query | 5.x | Data fetching & caching |
| Frontend | Tailwind CSS | 3.4.x | Styling |
| Backend | Node.js | 20 LTS | Runtime environment |
| Backend | Express | 4.x | HTTP framework |
| Backend | TypeScript | 5.x | Type safety |
| Database | PostgreSQL | 15.x | Primary database |
| ORM | Drizzle | 0.29.x | Database access |
3. Database Design #
The database schema is designed to support all HelixOps modules with proper normalization and referential integrity.
Core Entity Relationship
Risk Table Schema
CREATE TABLE risks (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
title VARCHAR(255) NOT NULL,
description TEXT,
category VARCHAR(50) NOT NULL,
status VARCHAR(20) DEFAULT 'Open',
likelihood INTEGER CHECK (likelihood BETWEEN 1 AND 5),
impact INTEGER CHECK (impact BETWEEN 1 AND 5),
risk_score INTEGER GENERATED ALWAYS AS (likelihood * impact) STORED,
treatment VARCHAR(20),
owner_id UUID REFERENCES users(id),
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
created_by UUID REFERENCES users(id),
updated_by UUID REFERENCES users(id)
); Audit Log Table Schema
CREATE TABLE audit_logs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
timestamp TIMESTAMPTZ DEFAULT NOW() NOT NULL,
user_id UUID NOT NULL REFERENCES users(id),
action VARCHAR(20) NOT NULL,
entity_type VARCHAR(50) NOT NULL,
entity_id UUID,
old_values JSONB,
new_values JSONB,
ip_address INET,
user_agent TEXT,
session_id VARCHAR(255)
);
-- Immutable audit log (no UPDATE/DELETE triggers)
CREATE INDEX idx_audit_timestamp ON audit_logs(timestamp);
CREATE INDEX idx_audit_user ON audit_logs(user_id);
CREATE INDEX idx_audit_entity ON audit_logs(entity_type, entity_id); 4. API Design #
The API follows RESTful conventions with consistent response formats and error handling.
Request Format
POST /api/risks
Content-Type: application/json
Authorization: Bearer <token>
{
"title": "Data breach risk",
"category": "Cybersecurity",
"likelihood": 3,
"impact": 5
} Response Format
{
"success": true,
"data": {
"id": "uuid-here",
"title": "Data breach risk",
"risk_score": 15,
"created_at": "2025-01-22T..."
}
} API Endpoints Summary
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/risks | List all risks | Viewer+ |
| POST | /api/risks | Create new risk | Manager+ |
| PATCH | /api/risks/:id | Update risk | Manager+ |
| DELETE | /api/risks/:id | Soft delete risk | Admin |
| GET | /api/audit-logs | List audit logs | Admin |
5. Security Design #
Encryption at Rest
- • AES-256 database encryption
- • Encrypted backup storage
- • Key rotation policy
Encryption in Transit
- • TLS 1.3 required
- • HSTS enabled
- • Certificate pinning
Authentication Flow
6. Deployment Architecture #
HelixOps is deployed on Replit with automated scaling and high availability configuration.
Infrastructure Components
7. Performance Requirements #
| Metric | Target | Measurement |
|---|---|---|
| Page Load Time | <2 seconds (P95) | Lighthouse CI |
| API Response Time | <500ms (P95) | APM monitoring |
| Database Query Time | <100ms (P95) | Query profiling |
| Concurrent Users | 100 without degradation | Load testing |
| Uptime | 99.5% | Synthetic monitoring |
Document Approval
Electronic signatures are considered equivalent to handwritten signatures in accordance with 21 CFR Part 11 requirements.