# Technical Design

> Create technical design documents for Talosix EDC features and systems. Covers architecture, data flow, component design, regulatory compliance, performance, scalability, and security.

- Skill: `nroze22/technical-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nroze22/technical-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nroze22/technical-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: nroze22 (https://skillmd.com/u/nroze22)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nroze22/technical-design

---


# 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

```markdown
# 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]([column]) -- [justification]

Constraints:
- FK: [column] REFERENCES [other_table](id)
- 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 <token>
  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.