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 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 |
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 contextDesign 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 discussionDesign 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
Related Resources
- Design Reviews
- Architecture Decisions
- Design Patterns
- API Design
- Code Reviews
- Microsoft Playbook: Design Reviews
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).
How is this guide?
Last updated on