Design Tools

Design tools support architecture documentation, API specification, data modeling, and system visualization. This guide covers tools for each aspect of software design.

Architecture Diagramming

Diagramming Tools

Visual Editors

Diagram-as-Code Tools

C4 Model Tools

The C4 model provides a hierarchical approach to software architecture documentation.

Structurizr DSL Example

workspace {
    model {
        user = person "User" "A user of the system"

        softwareSystem = softwareSystem "My System" {
            webapp = container "Web Application" "React frontend" "TypeScript"
            api = container "API" "REST API" "Node.js"
            database = container "Database" "PostgreSQL" "PostgreSQL 15"
        }

        user -> webapp "Uses"
        webapp -> api "Makes API calls to" "HTTPS/JSON"
        api -> database "Reads from and writes to" "SQL/TCP"
    }

    views {
        systemContext softwareSystem {
            include *
            autolayout lr
        }

        container softwareSystem {
            include *
            autolayout lr
        }

        theme default
    }
}

Mermaid C4 Diagram

C4Context
    title System Context diagram for My System

    Person(user, "User", "A user of the system")
    System(system, "My System", "The main system")
    System_Ext(email, "Email System", "Sends emails")
    System_Ext(payment, "Payment Provider", "Handles payments")

    Rel(user, system, "Uses")
    Rel(system, email, "Sends emails using")
    Rel(system, payment, "Processes payments via")

API Design Tools

OpenAPI/Swagger

OpenAPI Specification Example

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1
    description: Production server

paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - name

    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        password:
          type: string
          minLength: 8
      required:
        - email
        - name
        - password

    Pagination:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

Data Modeling Tools

Database Design Tools

dbdiagram.io Example

// Use DBML to define your database structure

Table users {
  id uuid [pk]
  email varchar [unique, not null]
  name varchar [not null]
  password_hash varchar [not null]
  created_at timestamp [default: `now()`]
  updated_at timestamp

  indexes {
    email [unique]
  }
}

Table organizations {
  id uuid [pk]
  name varchar [not null]
  slug varchar [unique, not null]
  created_at timestamp [default: `now()`]
}

Table memberships {
  id uuid [pk]
  user_id uuid [ref: > users.id]
  organization_id uuid [ref: > organizations.id]
  role varchar [not null, default: 'member']
  created_at timestamp [default: `now()`]

  indexes {
    (user_id, organization_id) [unique]
  }
}

Table projects {
  id uuid [pk]
  organization_id uuid [ref: > organizations.id]
  name varchar [not null]
  description text
  status varchar [default: 'active']
  created_at timestamp [default: `now()`]
}

UML Modeling

PlantUML Examples

@startuml
' Class Diagram
class User {
  - id: UUID
  - email: String
  - name: String
  + getFullName(): String
  + updateProfile(data: ProfileData): void
}

class Organization {
  - id: UUID
  - name: String
  - slug: String
  + addMember(user: User, role: Role): Membership
}

class Membership {
  - id: UUID
  - role: Role
  + promote(newRole: Role): void
}

User "1" -- "*" Membership
Organization "1" -- "*" Membership
@enduml

@startuml
' Sequence Diagram
actor User
participant "Web App" as Web
participant "API" as API
participant "Database" as DB
participant "Cache" as Cache

User -> Web: Login request
Web -> API: POST /auth/login
API -> DB: Validate credentials
DB --> API: User data
API -> Cache: Store session
Cache --> API: Session ID
API --> Web: JWT token
Web --> User: Redirect to dashboard
@enduml

Prototyping Tools

UI/UX Design

Customer Journey Mapping

Documentation Tools

Technical Documentation

Architecture Decision Records (ADRs)

# ADR-001: Use PostgreSQL as Primary Database

## Status
Accepted

## Context
We need to select a primary database for the application.
Requirements include:
- ACID compliance for financial transactions
- JSON support for flexible schemas
- Strong community and tooling support

## Decision
We will use PostgreSQL 15 as our primary database.

## Consequences
### Positive
- Excellent JSON/JSONB support
- Strong ACID compliance
- Mature ecosystem with excellent tooling
- Cost-effective (open source)

### Negative
- Team needs to upskill on PostgreSQL-specific features
- Horizontal scaling requires additional tooling (Citus, etc.)

## Alternatives Considered
- MySQL: Less JSON support
- MongoDB: Not ACID-compliant by default
- CockroachDB: Higher operational complexity

Integration Patterns

Diagram-as-Code in Documentation

# Architecture Overview

The system follows a microservices architecture:

graph TB subgraph "Frontend" A[React App] end

subgraph "API Gateway" B[Kong Gateway] end

subgraph "Services" C[User Service] D[Order Service] E[Payment Service] end

subgraph "Data" F[(PostgreSQL)] G[(Redis)] H[(Kafka)] end

A --> B B --> C B --> D B --> E C --> F D --> F E --> H C --> G

Related Resources

• Design - Design practices and patterns
• Architecture Templates - ADR templates
• API Design - API guidelines
• Code Reviews - Design review process

Compliance

This section fulfills ISO 13485 requirements for design and development planning (7.3.2), design outputs (7.3.4), and design documentation (4.2.3), and ISO 27001 requirements for secure architecture (A.8.27), secure development (A.8.25), and documented operating procedures (A.5.37).

View full compliance matrix