Architecture Diagrams

Purpose

Configuration and guidelines for creating technical diagrams to document AudioLab's architecture, design, and workflows. Includes setup for PlantUML, Mermaid, and other diagramming tools.

Contents

Configuration

• plantuml_config.puml - AudioLab theme and styling for PlantUML
• Brand colors and styling
• Custom macros (RT-SAFE, THREAD-SAFE, etc.)
• Consistent appearance across all diagrams

Guidelines

• diagram_types.md - When to use which diagram type
• mermaid_setup.md - Mermaid diagrams in markdown

Quick Start

PlantUML

Installation

# Windows
winget install plantuml

# Requires Java (if not installed)
winget install Oracle.JDK.21

Create Diagram

@startuml
!include plantuml_config.puml

title Simple Audio Buffer

class AudioBuffer {
    + getChannelData(): float*
    + getNumSamples(): size_t
}

note right of AudioBuffer
  RT_SAFE
end note

@enduml

Generate Image

# PNG
plantuml diagram.puml

# SVG (preferred)
plantuml -tsvg diagram.puml

# All diagrams in directory
plantuml *.puml

Mermaid

In Markdown (MkDocs)

```mermaid
flowchart LR
    A[Input] --> B[Process]
    B --> C[Output]
```

Renders automatically when MkDocs builds.

CLI Tool (Optional)

# Install
npm install -g @mermaid-js/mermaid-cli

# Generate SVG
mmdc -i diagram.mmd -o diagram.svg

Diagram Types

Class Diagrams

Use for: Class structure, inheritance, relationships

@startuml
!include plantuml_config.puml

class AudioProcessor {
    + process(buffer)
}

class GainProcessor {
    + setGain(value)
}

AudioProcessor <|-- GainProcessor
@enduml

Sequence Diagrams

Use for: Message flow, protocols, interactions

@startuml
!include plantuml_config.puml

Host -> Plugin: processBlock()
Plugin -> DSP: process()
DSP --> Plugin: return
Plugin --> Host: return
@enduml

Component Diagrams

Use for: System architecture, module dependencies

@startuml
!include plantuml_config.puml

package "Core" {
    [Buffer Manager]
    [Parameter System]
}

package "DSP" {
    [Effects]
    [Filters]
}

[Effects] --> [Buffer Manager]
@enduml

State Diagrams

Use for: State machines, lifecycle

@startuml
!include plantuml_config.puml

[*] --> Idle
Idle --> Processing
Processing --> Idle
Processing --> [*]
@enduml

Flowcharts (Mermaid)

Use for: Workflows, decision logic

```mermaid
flowchart TD
    A[Start] --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
```

See: diagram_types.md for detailed guide on choosing diagram types

AudioLab Custom Macros

The plantuml_config.puml defines macros for audio-specific annotations:

RT_SAFE

note right of Component
  RT_SAFE
end note

Indicates real-time safe code (no allocations, locks).

RT_UNSAFE

note right of Component
  RT_UNSAFE
end note

Indicates not real-time safe (may allocate or block).

THREAD_SAFE

note right of Component
  THREAD_SAFE
end note

Indicates thread-safe for concurrent access.

LOCK_FREE

note right of Component
  LOCK_FREE
end note

Indicates lock-free implementation.

SIMD_OPT

note right of Component
  SIMD_OPT
end note

Indicates SIMD-optimized code path.

Styling Guidelines

Colors (From AudioLab Brand)

• Primary: #2C3E50 (dark blue-gray)
• Secondary: #3498DB (blue)
• Accent: #E74C3C (red)
• Success: #27AE60 (green)
• Warning: #F39C12 (orange)

Already configured in plantuml_config.puml.

Diagram Quality Standards

Mandatory

• Title describing diagram purpose
• All elements labeled
• Consistent styling (use config)
• Source file in version control

Recommended

• Notes for RT-safety, thread-safety
• Limited complexity (<15 elements)
• SVG format (preferred for docs)
• Legend for non-obvious symbols

File Organization

Recommended Structure

10_DOCUMENTATION/diagrams/
├── architecture/              # System architecture
│   ├── overall-system.puml
│   ├── module-dependencies.puml
│   └── README.md
├── classes/                   # Class diagrams
│   ├── buffer-hierarchy.puml
│   ├── parameter-system.puml
│   └── README.md
├── sequences/                 # Sequence diagrams
│   ├── audio-callback.puml
│   ├── parameter-change.puml
│   └── README.md
├── workflows/                 # Activity/flowcharts
│   ├── plugin-init.puml
│   ├── build-process.mmd
│   └── README.md
└── signal-flow/               # Audio routing
    ├── effect-chain.svg
    ├── mixer-topology.svg
    └── README.md

Naming Conventions

• Lowercase with hyphens: audio-buffer-class.puml
• Descriptive: plugin-lifecycle-states.puml not states.puml
• Match content directory: classes/, sequences/, etc.

Integration with Documentation

In MkDocs (User Docs)

## Audio Processing Pipeline

![Pipeline Diagram](../diagrams/architecture/processing-pipeline.svg)

The pipeline consists of three stages:
1. Input buffering
2. Effect processing
3. Output buffering

In Doxygen (API Docs)

/**
 * @brief Audio buffer management
 *
 * @image html buffer-hierarchy.png "Buffer Class Hierarchy"
 */
class AudioBuffer { /* ... */ };

In Source Code Comments

// State machine diagram: docs/diagrams/workflows/plugin-states.puml
enum class PluginState {
    Unloaded,
    Loaded,
    Initialized,
    Active
};

Automation

Generate All Diagrams Script

Create generate_diagrams.ps1:

# Generate all PlantUML diagrams
Get-ChildItem -Recurse -Filter *.puml | ForEach-Object {
    Write-Host "Generating $($_.Name)..."
    plantuml -tsvg $_.FullName
}

# Generate Mermaid diagrams (if using CLI)
Get-ChildItem -Recurse -Filter *.mmd | ForEach-Object {
    Write-Host "Generating $($_.Name)..."
    mmdc -i $_.FullName -o ($_.FullName -replace '.mmd', '.svg')
}

CI/CD Integration

# .github/workflows/diagrams.yml
name: Generate Diagrams

on:
  push:
    paths:
      - '10_DOCUMENTATION/diagrams/**/*.puml'
      - '10_DOCUMENTATION/diagrams/**/*.mmd'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup PlantUML
        run: sudo apt-get install -y plantuml

      - name: Generate diagrams
        run: |
          find 10_DOCUMENTATION/diagrams -name "*.puml" -exec plantuml -tsvg {} \;

      - name: Commit generated files
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add "10_DOCUMENTATION/diagrams/**/*.svg"
          git commit -m "docs: regenerate diagrams" || true
          git push

Tools Comparison

Tool	Pros	Cons	Best For
PlantUML	Powerful, many diagram types, customizable	Requires Java, separate tool	Complex diagrams, API docs
Mermaid	Renders in markdown, no tools needed	Less powerful, browser-dependent	Quick diagrams, user docs
draw.io	WYSIWYG, easy to use	Not text-based, harder to version	Custom diagrams, presentations
FossFLOW	Isometric, great for audio routing	Specialized, learning curve	Audio signal flow

VS Code Extensions

PlantUML

Name: PlantUML
ID: jebbs.plantuml

Features: Live preview, syntax highlighting, auto-completion

Mermaid

Name: Mermaid Preview
ID: bierner.markdown-mermaid

Features: Live preview in markdown

draw.io

Name: Draw.io Integration
ID: hediet.vscode-drawio

Features: Edit .drawio files in VS Code

Best Practices

1. Keep It Simple

• Limit to 10-15 elements per diagram
• Split complex diagrams into multiple views
• Use subgraphs/packages for grouping

2. Consistent Styling

• Always include !include plantuml_config.puml
• Use defined color macros
• Follow naming conventions

3. Version Control

• Commit source files (.puml, .mmd)
• Commit generated images (for easy viewing)
• Use meaningful commit messages

4. Documentation

• Add title to every diagram
• Include notes for context
• Create README in each diagram directory

5. Maintainability

• Update diagrams when code changes
• Review diagrams during PR review
• Archive outdated diagrams (don't delete)

Examples Repository

See example diagrams in:

10_DOCUMENTATION/diagrams/examples/
├── class-diagram-example.puml
├── sequence-diagram-example.puml
├── component-diagram-example.puml
├── state-diagram-example.puml
└── flowchart-example.mmd

Troubleshooting

PlantUML Not Generating

# Check Java installation
java -version

# Check PlantUML installation
plantuml -version

# Test with simple diagram
echo "@startuml
A -> B
@enduml" > test.puml
plantuml test.puml

Mermaid Not Rendering in MkDocs

• Verify pymdownx.superfences configured in mkdocs.yml
• Check syntax at https://mermaid.live/
• Ensure proper markdown code fence

Custom Theme Not Applied

• Check file path in !include plantuml_config.puml
• Use absolute path if needed: !include /full/path/to/plantuml_config.puml
• Verify PlantUML can find the file

References

Documentation

• PlantUML Official Docs
• PlantUML Language Reference
• Mermaid Documentation
• Mermaid Live Editor

Guides

• Diagram Types Guide
• Mermaid Setup

Tools

• PlantUML Online Server
• draw.io
• FossFLOW

Support

• PlantUML issues: https://github.com/plantuml/plantuml/issues
• Mermaid issues: https://github.com/mermaid-js/mermaid/issues
• AudioLab diagram standards: See diagram_types.md