Excalidraw Diagrams

Excalidraw is an open-source virtual whiteboard that creates hand-drawn style diagrams directly in your ArchDoc documents.

What is Excalidraw?

Excalidraw provides:

• Hand-drawn aesthetic: Diagrams look sketched, approachable
• Full-featured whiteboard: Shapes, arrows, text, images
• Real-time collaboration: Work together on diagrams
• Embedded in documents: No external tools needed

Creating an Excalidraw Diagram

Method 1: Toolbar Button

1. Place your cursor where you want the diagram
2. Click the Diagram button (✏️) in the toolbar
3. An empty Excalidraw canvas appears
4. Click Edit to open the full editor

Method 2: Keyboard

The diagram button is your quickest option in the current editor.

Using Excalidraw

The Canvas

When you click Edit, a full-screen editor opens:

• Left toolbar: Drawing tools
• Canvas: Your working area
• Top bar: Style options
• Bottom bar: Zoom and navigation

Drawing Tools

Styling Elements

Select an element to access style options:

• Stroke color: Line/border color
• Background color: Fill color
• Fill style: Solid, hatch, cross-hatch, or none
• Stroke width: Thin, bold, or extra bold
• Stroke style: Solid, dashed, or dotted
• Edge style: Sharp, round, or sketch
• Opacity: Transparency level

Creating Common Diagrams

Architecture Diagram

1. Add boxes for each component (services, databases)
2. Label each box with text
3. Connect with arrows to show relationships
4. Add notes for additional context

System Flow

1. Start with an entry point (user, request)
2. Add process boxes for each step
3. Connect with arrows showing flow direction
4. Add decision diamonds for branches
5. End with outcomes

Component Diagram

1. Draw boundaries with rectangles
2. Place components inside boundaries
3. Show connections between components
4. Add labels and annotations

Example Diagrams

Microservices Architecture

┌─────────────────────────────────────────────┐
│                  API Gateway                 │
└─────────────────────┬───────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ User    │  │ Order   │  │ Product │
   │ Service │  │ Service │  │ Service │
   └────┬────┘  └────┬────┘  └────┬────┘
        │            │            │
        ▼            ▼            ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ User DB │  │ Order DB│  │Prod. DB │
   └─────────┘  └─────────┘  └─────────┘

Request Flow

┌──────┐     ┌──────────┐     ┌────────┐
│Client│────▶│   Load   │────▶│ Server │
└──────┘     │ Balancer │     │   1    │
             └──────────┘     └───┬────┘
                    │             │
                    │         ┌───▼────┐
                    └────────▶│ Server │
                              │   2    │
                              └────────┘

Saving Diagrams

Auto-save

• Diagrams save automatically when you close the editor
• Changes are persisted with the document

Explicit Save

1. Click Save in the Excalidraw editor
2. Click the X to close the editor
3. Your diagram is now part of the document

Editing Existing Diagrams

1. Click on the diagram in your document
2. Click the Edit button
3. Make your changes
4. Save and close

Tips and Best Practices

Keep It Simple

• Don't overcrowd diagrams
• Use clear, readable labels
• Focus on one concept per diagram

Use Consistent Styling

• Stick to a color palette
• Use similar shapes for similar concepts
• Maintain consistent sizing

Add Context

• Label everything important
• Use arrows to show flow
• Add text annotations

Think About Readability

• Ensure sufficient contrast
• Don't make text too small
• Leave whitespace between elements

Keyboard Shortcuts

Troubleshooting

Diagram Not Saving

• Ensure you click Save before closing
• Check your network connection
• Try refreshing and editing again

Editor Won't Open

• Try refreshing the page
• Clear browser cache
• Ensure JavaScript is enabled

Slow Performance

• Reduce the number of elements
• Simplify complex shapes
• Close other browser tabs

Limitations

• Large diagrams may impact page load time
• Collaboration on diagrams is separate from document collaboration
• Some browser extensions may interfere