Draw.io Architecture Diagrams

When to Use This Skill

Use this skill when you need to:

• Create system architecture diagrams for the chaoticsemanticmemory crate
• Visualize module relationships and data flows
• Generate .drawio files for documentation
• Create diagrams from plans/ folder content (GOALS.md, ACTIONS.md, GOAP_STATE.md)

Inline Diagram Output (Responses & Plan Files)

When rendering a diagram inline (in a chat response, plan file, or terminal output), NEVER use raw ASCII box art. ASCII characters misalign because LLMs cannot guarantee consistent character widths across fonts and terminal environments.

Output Format Rules

Canonical Inline Diagram - ChaoticSemanticFramework

graph TD
  subgraph CSF["ChaoticSemanticFramework"]
    S["Singularity\n(Concepts)"]
    R["Reservoir\n(Temporal ESN)"]
    P["Persistence\n(libSQL)"]
    H["Hyperdim\n(HVec10240 Operations)"]
  end
  S --> H
  R --> H
  P --> H

This renders pixel-perfectly in GitHub, VS Code, and all markdown viewers. No character counting. No alignment bugs.

Diagram Types for This Project

High-Level Architecture Diagram

Create diagrams showing:

• Core modules: hyperdim, reservoir, singularity, persistence, framework
• Data flow: Input -> Reservoir -> Singularity -> Persistence
• WASM boundary with conditional compilation
• External dependencies: libsql, tokio, rayon

Module Relationship Diagram

Show interactions between:

• HVec10240 (hyperdimensional vectors)
• Reservoir (echo state network)
• Singularity (concept storage + search)
• ChaoticSemanticFramework (orchestrator)
• Persistence (libsql/Tokio)

GOAP Visualization

Map actions from plans/ACTIONS.md:

• Phase 1: Correctness fixes
• Phase 2: Performance optimizations
• Phase 3: Capabilities

Creating Diagrams

Option 1: Generate Tool (draw.io GUI)

1. Open draw.io
2. Click the sparkle (✨) Generate tool in toolbar
3. Describe the architecture you want
4. Adjust layout and styling

Option 2: MCP Server (if available)

# Use drawio MCP server for programmatic generation
# Requires MCP access configured in session

Option 3: Manual XML Creation

Create .drawio files with this structure:

<mxfile host="app.diagrams.net">
  <diagram name="Architecture">
    <mxGraphModel><root>
      <mxCell id="0"/>
      <mxCell id="1" parent="0"/>
    </root></mxGraphModel>
  </diagram>
</mxfile>

Styling Guidelines

Output Locations

• Save diagrams to docs/architecture/
• Use docs/architecture/high-level-arch.drawio
• Export PNG versions for README: docs/architecture/high-level-arch.png

Best Practices

1. Never use raw ASCII art for inline diagram output - use mermaid fenced blocks
2. Start high-level: Show module boundaries first, then detail
3. Consistent styling: Use same colors/shapes for similar elements
4. Include legend: Explain shapes and colors
5. Export PNG: For embedding in Markdown/HTML docs
6. Version control: Commit .drawio XML, not PNG