Skip to content

Diagramming Guidelines

This document outlines the standard tools and practices for creating diagrams in the NepWalk documentation. To ensure maintainability and a clean aesthetic, we have transitioned away from PlantUML and now exclusively use Mermaid.js (for text-based diagrams) and Excalidraw (for high-level architectural sketches).

Mermaid.js

Mermaid is natively integrated into our MkDocs Material theme. You do not need to install any external plugins or tools.

When to use Mermaid

  • Sequence Diagrams: Great for API flows and authentication handshakes.
  • Flowcharts: Ideal for simple logic trees and user decision paths.
  • State Diagrams: Useful for illustrating object lifecycles (e.g., booking states).

How to use Mermaid

Simply create a mermaid code block in any Markdown file. The theme will automatically render it, and it even supports our custom brand colors (NepWalk Dark Green & Saffron Gold) out of the box.

Example: Sequence Diagram

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: Submit Login Form
    Frontend->>API: POST /api/auth/login
    API->>Database: Verify Credentials
    Database-->>API: Validated User Data
    API-->>Frontend: Token & Session
    Frontend-->>User: Redirect to Dashboard

Example: Simple Flowchart

graph LR
    A[Start] --> B{Is Registered?}
    B -- Yes --> C[Login]
    B -- No --> D[Sign Up]
    C --> E[Dashboard]
    D --> E

Excalidraw

For diagrams that require more freedom, visual appeal, or custom branding (like system architecture overviews or complex UI flow mappings), we use Excalidraw.

When to use Excalidraw

  • High-level System Architecture
  • Infrastructure Diagrams
  • Mental Models or Component Maps

Excalidraw Workflow

  1. Draw your diagram on excalidraw.com or via the Excalidraw Obsidian/VSCode plugin.
  2. Export as SVG: Export your diagram as an .svg file. Ensure "Embed scene" is checked so the file can be edited later.
  3. Save: Place the .svg file in the appropriate images/ directory within docs/.
  4. Embed: Link the SVG in your Markdown file just like a normal image.
![System Architecture Flow](./images/architecture-flow.svg)

Tip: By keeping the "Embed scene" option checked when exporting, any developer can simply drag the .svg file back into Excalidraw to make updates without needing a separate source file!