Design: Architecture Decisions, Modular Patterns & API Standards
Intentional blueprints describing system structure, component boundaries, and public API contracts with formal verification records.
Software Design: The Blueprint of Structure, Behavior & Boundaries
In software engineering, Design is the deliberate process of planning system boundaries, module interactions, data models, and API interfaces before writing code. In regulated systems, design creates the documented link between user requirements (Design Inputs) and the final codebase (Design Outputs), satisfying FDA 21 CFR §820.30 and ISO 13485 Clause 7.3 requirements.
Architecture vs. Design: Primary Orientation & Scope Boundaries
Understanding the boundary between architecture and design prevents organizational friction: Architecture decisions are system-wide, high-friction commitments that are expensive to reverse once implemented. Design decisions are localized, component-level choices that evolve sprint-to-sprint through automated test refactoring.
| Dimension | System Architecture (System-Wide) | Detailed Software Design (Component-Level) | Practical Example |
|---|---|---|---|
| Scope of Impact | System-wide, multi-service boundaries, global data storage, and distributed topology. | Component-level, class interfaces, module interactions, and localized algorithmic transforms. | Event-driven pub/sub backbone (Architecture) vs. Strategy pattern for payload parsing (Design). |
| Cost & Friction of Change | Extremely high; changes require database schema migrations, distributed service rewrites, and client contract updates. | Low to medium; easily refactored inside a single module or service via automated test safety nets. | Replacing PostgreSQL with DynamoDB (Architecture) vs. Refactoring a 300-line controller into smaller service helpers (Design). |
| Decision Lifespan | Multi-year commitments that often outlive the initial engineering team. | Iterative, evolving sprint-to-sprint as features expand and new edge cases emerge. | Microservices vs. Modular Monolith (Architecture) vs. Factory method vs. Dependency Injection (Design). |
| Primary Artifacts | Architecture Decision Records (ADRs), C4 System Context & Container diagrams, deployment topologies. | Class diagrams, sequence diagrams, OpenAPI 3.1 specs, TypeScript interface definitions. | ADR-014 Asynchronous Telemetry (Architecture) vs. PatientTelemetryValidator interface (Design). |
| Key Stakeholders | Principal Architects, VP of Engineering, Security Officers, DevOps/Platform Leads. | Software Engineers, Senior Developers, Tech Leads, Code Reviewers. | SOC-2 tenancy boundary approval (Architecture) vs. PR code review approval (Design). |
| Regulated Verification Role | FDA 21 CFR §820.30(c) Design Inputs & ISO 13485 Cl. 7.3.3 system-level architectural specifications. | FDA 21 CFR §820.30(d) Design Outputs & ISO 13485 Cl. 7.3.4 component-level detailed specifications. | System Architecture Document (Architecture) vs. Detailed Software Unit Design (Design). |
High Cohesion & Loose Coupling vs. Spaghetti Anti-Pattern
High Cohesion & Loose Coupling
Cohesion means everything inside a single module works together toward one clear purpose (e.g. JWT validation only). Loose Coupling means modules only talk across clean, public interface ports without reaching into each other's internal data structures.
The Four Core Design Activity Types
Design activities occur across four distinct dimensions, each producing specific regulatory outputs:
1. Architectural Design
High-level subsystem boundaries, distributed messaging patterns, data tier isolation, and global security boundaries.
2. Detailed Component Design
Module structures, class hierarchies, SOLID principle adherence, state machine transitions, and concurrency safety.
3. Interface & API Design
Public API contracts, REST endpoint conventions, RFC 7807 error envelopes, authentication flows, and SDK interfaces.
4. Data & Storage Design
Relational entity schemas, indexing strategies, caching lifecycles (Redis), event serialization, and data retention policies.
The Multiple Design Passes Sequence
Design is executed as a progressive sequence rather than an all-at-once document:
Deconstruct requirements into core domain entities, state machines, and business rules before writing code.
Domain Model & State Transition TableEstablish subsystem boundaries, choose distributed communications, and document tradeoffs in an ADR.
Architecture Decision Record (ADR) & C4 DiagramDesign class interfaces, apply SOLID principles, define public API schemas (OpenAPI), and specify error envelopes.
OpenAPI 3.1 Spec & TypeScript InterfacesPerform security threat modeling, evaluate rate limiting, verify database indexing, and execute formal Design Review.
Design Review Record (ISO 13485 Cl. 7.3.5)Design Documentation Priorities Matrix
What to document and at what retention level in enterprise software engineering:
Public API Contracts & Security Boundaries
OpenAPI 3.1 specifications, authentication models (OAuth 2.0 PKCE), rate limits, and cryptographic payload formats.
Architecture Decision Records (ADRs)
Documenting architectural choices, rationale, alternatives considered, and tradeoffs for decisions with high change cost.
Internal Helper Class Diagrams
Ephemeral UML class diagrams for localized private utility classes that are thoroughly verified by automated unit tests.
Superseded Design Whitepapers & RFCs
Exploratory spike documents and brainstorming drafts that have been formalized into accepted ADRs or codebase implementations.
Explore Design Sub-Topics
Deep-dive into formal review gates, architecture decision records, SOLID patterns, and public API standards:
Design Reviews
Formal Review Gates & Quality Checklist
Architecture Decisions
Immutable Records & Telemetry Example
Design Patterns & SOLID
Plain-Language Rules & Code Refactoring
API Design
Contracts, PKCE Flow & RFC 7807
Community Discussion & Feedback
Attributed peer feedback and official Netspective architecture notes.