Design

Design reviews, architecture decision records, and design patterns for regulated software

Design is the disciplined process of creating the internal structure and behavior of a system that is robust, extensible, and high-quality. Good design improves quality and makes a system easier to maintain and extend, while poor design can significantly raise the cost of producing and maintaining software.

What is Design?

Design is an abstraction of the code that presents the system from a perspective that makes it easier to address structure and behavior. The critical element of design is that it describes how different elements of the system interact to fulfill requirements.

Design Lifecycle

Design Activity	Purpose	Outputs
Architectural Design	Define high-level structure	Component diagrams, architecture decisions
Detailed Design	Define component internals	Class diagrams, sequence diagrams
Interface Design	Define API contracts	API specifications, interface documents
Data Design	Define data structures	Database schemas, data models

Design Principles

YAGNI (You Aren't Going to Need It)

Keep designs simple by not adding functionality until you need it:

Add what's needed for the current requirement
Refactor the design when more functionality is needed
Avoid assumptions about future needs

Coupling and Cohesion

Two fundamental principles of good design:

Principle	Definition	Goal
High Cohesion	Elements within a component are closely related	Easy to understand and maintain
Low Coupling	Minimal dependencies between components	Easy to change and replace

High Cohesion, Low Coupling Example

Open-Closed Principle

Elements should be "open" for extension but "closed" for modification:

Extend functionality without changing existing code
Reduces risk of introducing bugs
Enables reuse without knowing implementation details

SOLID Principles

Principle	Description
Single Responsibility	A class should have only one reason to change
Open-Closed	Open for extension, closed for modification
Liskov Substitution	Subtypes must be substitutable for base types
Interface Segregation	Many specific interfaces are better than one general
Dependency Inversion	Depend on abstractions, not concretions

Design vs Architecture

Aspect	Architecture	Design
Scope	System-wide	Component-level
Focus	Principles, constraints	Implementation details
Decisions	Hard to change	Easier to change
Documentation	Architecture Decision Records	Design documents

Architecture helps ensure the design is consistent and appropriate to system goals by balancing competing technical issues across the entire system.

Multiple Design Passes

Design is iterative and performed in different contexts:

Pass 1: Analysis Pass
├── Identify participants in collaboration
├── Define high-level behavior
└── Document initial concepts

Pass 2: Architectural Pass
├── Identify coarse-grained elements
├── Define component boundaries
└── Document architecture decisions

Pass 3: Detailed Design Pass
├── Design within components
├── Define classes and interfaces
└── Document detailed interactions

Pass 4: Context-Specific Passes
├── Database design context
├── UI design context
└── Integration design context

Design Documentation

What to Document

Priority	Documentation Level	Examples
Always	Architecturally significant	Component interactions, key patterns
Important	Complex behavior	Algorithms, state machines
Optional	Implementation details	Class internals, simple flows
Archive	Initial decisions	Whiteboard images, meeting notes

Design Document Structure

# Component Design Document

## Overview
Brief description of the component's purpose

## Context
Where this component fits in the system

## Design Decisions
Key choices and their rationale (link to ADRs)

## Component Diagram
Visual representation of structure

## Interface Specification
Public APIs and contracts

## Data Model
Data structures and relationships

## Error Handling
How errors are managed

## Security Considerations
Security-relevant design decisions

## Open Questions
Items requiring further discussion

Design Quality Checklist

Structure

High cohesion within components
Low coupling between components
Clear separation of concerns
Appropriate abstraction levels

Behavior

Well-defined interfaces
Consistent error handling
Clear state management
Documented side effects

Maintainability

Design is understandable
Changes can be localized
Testing is straightforward
Documentation is current

Compliance

Security requirements addressed
Audit requirements met
Regulatory constraints satisfied
Traceability maintained

Design in Regulated Environments

For FDA, HIPAA, and other regulatory frameworks:

Requirement	Design Consideration
Traceability	Link design to requirements
Risk Management	Document safety-critical design decisions
Change Control	Version all design artifacts
Verification	Design reviews with evidence
Validation	Design supports intended use

Design History File (DHF) Items

Design input (requirements)
Design output (specifications)
Design reviews (meeting records)
Design verification (test results)
Design validation (user acceptance)

Best Practices

Do

Design in small, proven chunks
Document architecturally significant decisions
Review designs before implementation
Refactor to improve design quality
Maintain traceability to requirements
Consider security from the start

Don't

Over-engineer (analysis paralysis)
Design beyond current needs
Skip design reviews for "simple" changes
Let documentation drift from reality
Ignore non-functional requirements
Treat design as a one-time activity

Compliance

This section fulfills ISO 13485 requirements for design planning (7.3.2), design inputs (7.3.3), design outputs (7.3.4), design review (7.3.5), and design changes (7.3.7), and ISO 27001 requirements for secure development lifecycle (A.8.25), application security requirements (A.8.26), secure architecture (A.8.27), and information security in project management (A.5.8).

View full compliance matrix

How is this guide?

Last updated on

Design

On this page