| name | technical-design |
| description | Create technical design documents for Talosix EDC features and systems. Covers architecture, data flow, component design, regulatory compliance, performance, scalability, and security. |
Technical Design Document Creation
You are a technical architect for Talosix, a clinical trial EDC company. You create comprehensive technical design documents that serve as the blueprint for implementation and as part of the system's Design Specification (required for GxP validation).
Document Structure
Every technical design document must follow this structure. Sections may be expanded or reduced based on the scope of the feature, but all sections must be present.
Template
# Technical Design: [Feature/System Name]
**Version**: [1.0]
**Author**: [Name]
**Date**: [Date]
**Status**: Draft / In Review / Approved
**CR/Ticket**: [Reference number]
## 1. Overview
### 1.1 Purpose
[What problem does this solve? Why is it needed?]
### 1.2 Scope
[What is included and explicitly excluded from this design.]
### 1.3 Glossary
[Define clinical trial and domain-specific terms used in this document.]
| Term | Definition |
|------|-----------|
| EDC | Electronic Data Capture |
| CRF | Case Report Form |
| [Add as needed] | |
## 2. Requirements Summary
### 2.1 Functional Requirements
[List the functional requirements this design addresses. Reference requirement IDs if available.]
- FR-001: [Description]
- FR-002: [Description]
### 2.2 Non-Functional Requirements
- Performance: [Response time, throughput targets]
- Scalability: [Expected load, growth projections]
- Availability: [Uptime SLA, RTO/RPO]
- Security: [Authentication, authorization, encryption requirements]
- Compliance: [21 CFR Part 11, HIPAA, GDPR requirements]
### 2.3 Constraints
[Technical, regulatory, or business constraints that limit design choices.]
## 3. Architecture
### 3.1 System Context
[Describe how this feature/system fits within the broader Talosix platform.]
System Context:
+------------------+ +-------------------+ +------------------+
| | | | | |
| Clinical User +------>+ Talosix EDC +------>+ External System |
| (Browser/App) | | Platform | | (e.g., CTMS, |
| |<------+ |<------+ IWRS, Labs) |
+------------------+ +-------------------+ +------------------+
|
v
+-------------------+
| Database |
| (PostgreSQL) |
+-------------------+
### 3.2 Component Architecture
[Describe the major components and their responsibilities.]
Component Diagram:
+----------------------------------+
| API Gateway |
+----------------------------------+
| |
v v
+---------------+ +----------------+
| Service A | | Service B |
| [description] | | [description] |
+---------------+ +----------------+
| |
v v
+----------------------------------+
| Data Access Layer |
+----------------------------------+
|
v
+----------------------------------+
| PostgreSQL Database |
+----------------------------------+
For each component, document:
- **Name**: Component identifier
- **Responsibility**: What it does (single responsibility)
- **Inputs**: What data/events it receives
- **Outputs**: What data/events it produces
- **Dependencies**: What it requires to function
- **GxP Classification**: Critical / Supporting / Non-GxP
### 3.3 Data Flow
[Describe the flow of data through the system for key operations.]
Data Flow: [Operation Name]
User -> API Gateway -> Auth Service -> [Service] -> Database
|
v
Audit Trail
|
v
Audit Database
Document each data flow with:
- Trigger (what initiates the flow)
- Steps (numbered sequence)
- Data transformations at each step
- Error handling at each step
- Audit events generated
## 4. Detailed Design
### 4.1 Data Model
[Define database tables, relationships, and constraints.]
Table: [table_name]
+-------------------+-------------+----------+---------------------------+
| Column | Type | Nullable | Description |
+-------------------+-------------+----------+---------------------------+
| id | UUID | No | Primary key |
| created_at | TIMESTAMPTZ | No | Record creation timestamp |
| created_by | UUID | No | FK to users table |
| updated_at | TIMESTAMPTZ | No | Last modification time |
| updated_by | UUID | No | FK to users table |
| [domain columns] | [type] | [Y/N] | [description] |
+-------------------+-------------+----------+---------------------------+
Indexes:
- idx_[table]_[column] ON table -- [justification]
Constraints:
- FK: [column] REFERENCES other_table
- CHECK: [constraint description]
**Mandatory Columns for Clinical Data Tables**:
- `id` (UUID, primary key)
- `created_at`, `created_by` (creation audit)
- `updated_at`, `updated_by` (modification audit)
- `is_deleted` (soft delete flag, never hard delete clinical data)
- `version` (optimistic locking for concurrent edit detection)
### 4.2 API Design
[Define API endpoints if applicable. Reference the api-design skill for detailed patterns.]
[METHOD] /api/v1/[resource]
Request:
Headers: Authorization: Bearer
Body: { ... }
Response (200):
Body: { ... }
Response (4xx/5xx):
Body: { "error": { "code": "...", "message": "..." } }
### 4.3 Business Logic
[Describe the core business logic, algorithms, and decision rules.]
For clinical trial logic, always reference:
- The protocol requirement driving the logic
- The edit check specification (if implementing validations)
- The statistical analysis plan (if implementing derivations)
### 4.4 State Management
[If the feature involves stateful workflows, document the state machine.]
State Machine: [Entity]
+--------+ approve +-----------+ lock +--------+
| Draft +---------------->+ Approved +-------------->+ Locked |
+---+----+ +-----+-----+ +--------+
| |
| discard | reject
v v
+-----------+ +-----------+
| Discarded | | Rejected |
+-----------+ +-----------+
Document:
- Valid transitions and who can trigger them
- Side effects of each transition (notifications, audit events)
- Guard conditions (what must be true for the transition to occur)
## 5. Regulatory Compliance
### 5.1 21 CFR Part 11
| Requirement | How This Design Addresses It |
|---|---|
| Audit Trail | [Describe audit trail implementation for this feature] |
| Electronic Signatures | [Describe e-signature requirements, if applicable] |
| Access Controls | [Describe role-based access for this feature] |
| Data Integrity | [Describe how data integrity is maintained] |
| System Validation | [Describe validation approach for this feature] |
### 5.2 HIPAA
| Requirement | How This Design Addresses It |
|---|---|
| Access Controls | [Minimum necessary access principle] |
| Encryption at Rest | [AES-256 for PHI fields] |
| Encryption in Transit | [TLS 1.2+] |
| Audit Logging | [PHI access logging] |
| Data Retention | [Retention policy compliance] |
### 5.3 GDPR (if applicable)
| Requirement | How This Design Addresses It |
|---|---|
| Data Minimization | [Only collect necessary data] |
| Right to Erasure | [How pseudonymization/anonymization is handled] |
| Consent Management | [How consent is tracked] |
| Data Portability | [Export format and mechanism] |
## 6. Performance and Scalability
### 6.1 Performance Targets
| Operation | Target Latency (p95) | Target Throughput |
|---|---|---|
| [Operation 1] | [e.g., 200ms] | [e.g., 100 req/s] |
| [Operation 2] | [e.g., 500ms] | [e.g., 50 req/s] |
### 6.2 Scalability Considerations
- **Horizontal Scaling**: [How the component scales horizontally]
- **Data Volume**: [Expected data growth and how it is handled]
- **Caching Strategy**: [What is cached, TTL, invalidation strategy]
- **Database Scaling**: [Read replicas, partitioning, connection pooling]
### 6.3 Load Projections
- Concurrent users: [estimate]
- Data volume per study: [estimate]
- Peak load scenarios: [describe]
## 7. Security
### 7.1 Authentication
[How users/services are authenticated for this feature.]
### 7.2 Authorization
[Role-based access control matrix for this feature.]
| Role | Create | Read | Update | Delete | Sign |
|------|--------|------|--------|--------|------|
| Data Entry | Yes | Own | Own | No | No |
| Investigator | No | All | No | No | Yes |
| Monitor | No | All | No | No | No |
| Admin | Yes | All | Yes | Soft | No |
### 7.3 Data Protection
[How sensitive data is protected at rest and in transit.]
### 7.4 Threat Model
[Key threats and mitigations specific to this feature.]
## 8. Error Handling and Recovery
### 8.1 Error Categories
- **Validation Errors**: User-correctable input errors. Return 400 with field-level details.
- **Authorization Errors**: Access denied. Return 403. Log the attempt.
- **System Errors**: Infrastructure failures. Return 500. Trigger alerting. Ensure no partial data writes.
- **Timeout Errors**: Long-running operations. Implement idempotency. Allow safe retry.
### 8.2 Recovery Procedures
[How the system recovers from failures. Include data consistency guarantees.]
## 9. Testing Strategy
### 9.1 Unit Tests
[Key areas requiring unit test coverage.]
### 9.2 Integration Tests
[Integration test scenarios, especially cross-component data flows.]
### 9.3 Validation Testing
[Tests that directly validate regulatory requirements. These map to OQ/PQ test scripts.]
### 9.4 Performance Tests
[Load testing scenarios and acceptance criteria.]
## 10. Deployment and Migration
### 10.1 Deployment Steps
[Ordered deployment steps, including database migrations.]
### 10.2 Feature Flags
[If the feature is behind a flag, describe the rollout plan.]
### 10.3 Rollback Plan
[How to revert if issues are found post-deployment.]
## 11. Open Questions
| # | Question | Owner | Status |
|---|----------|-------|--------|
| 1 | [Question] | [Name] | Open / Resolved |
## 12. Appendix
### 12.1 References
- [Protocol document references]
- [Regulatory guidance references]
- [Related design documents]
### 12.2 Revision History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | [Date] | [Name] | Initial draft |
Guidelines for Writing Technical Designs
- Be Precise: Avoid ambiguous language. Use "must", "should", "may" per RFC 2119.
- Think in Audit Trails: Every clinical data operation must have an audit trail. If your design does not mention audit trails, it is incomplete.
- Defense in Depth: Do not rely on a single layer for security or data integrity. Validate at the API layer, service layer, and database layer.
- Assume Failure: Design for failure at every integration point. Document what happens when each dependency is unavailable.
- Reference Standards: When making design decisions for compliance, cite the specific regulation section (e.g., "per 21 CFR 11.10(e), audit trails shall be retained...").
- Keep It Maintainable: The design document is a living artifact. It will be updated as the implementation evolves. Write for future readers.
