How drawDB and drawdb-server Work Together to Enable Diagram Sharing

drawDB relies on drawdb-server, a lightweight Node.js backend, to persist diagram JSON data and generate shareable URLs via REST API endpoints.

drawDB is a client-side database diagramming tool that runs entirely in the browser. When users need to collaborate or share their work, the application requires external persistence. This is achieved through drawdb-server, a companion service that provides the storage layer necessary for diagram sharing.

The Architecture of Diagram Sharing

Understanding how these two components interact requires examining their distinct responsibilities.

Client-Side Rendering (drawDB)

The drawDB frontend handles all diagram creation, editing, and rendering logic within the browser. Built as a React application, it manages the state of database schemas, tables, and relationships entirely on the client until the user initiates a share action.

Server-Side Persistence (drawdb-server)

drawdb-server operates as a standalone Node.js service that exposes a simple REST API. It accepts JSON payloads containing diagram data, stores them with unique identifiers, and serves them back upon request. This separation of concerns allows drawDB to remain a static, deployable frontend while delegating persistence to the lightweight backend.

How the Integration Works

The sharing workflow follows a straightforward request-response pattern between the two systems.

When a user clicks the share button, drawDB serializes the current diagram state and sends it to the drawdb-server /save endpoint. The server stores this JSON and returns a unique identifier. The client then constructs a shareable URL using this ID, typically formatted as https://<your-domain>/?id=<uid>.

Recipients opening this URL trigger drawDB to check for the id query parameter. If present, the application makes a GET request to the server's /load/:id endpoint, retrieves the diagram JSON, and hydrates the editor state. According to the drawdb-io/drawdb source code, this logic resides in src/pages/Editor.jsx, which handles the initial route parsing and data fetching on page load.

Implementing the Save and Load Logic

The communication between drawDB and drawdb-server relies on standard fetch calls. The client expects the environment variable REACT_APP_DRAWDB_SERVER_URL to be configured with the server's base address.

Here is the pattern used to persist a diagram:

// Example: Saving a diagram from the client (Draw DB)
async function saveDiagram(diagram) {
  const res = await fetch(
    `${process.env.REACT_APP_DRAWDB_SERVER_URL}/save`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ diagram })
    }
  );
  const { id } = await res.json();       // <- unique share ID
  return `${window.location.origin}/?id=${id}`;
}

Loading a shared diagram uses the ID from the URL query string:

// Example: Loading a shared diagram on page load
async function loadDiagram(id) {
  const res = await fetch(
    `${process.env.REACT_APP_DRAWDB_SERVER_URL}/load/${id}`
  );
  const { diagram } = await res.json();
  // Initialise the editor with the fetched diagram
  initEditor(diagram);
}

The src/api/gists.js file in the drawDB repository demonstrates similar patterns for external API communication, which the drawdb-server integration mirrors.

Configuration and Environment Setup

To enable diagram sharing, you must run drawdb-server separately and configure drawDB to communicate with it. The repository's README.md documents this setup at line 64 in the sharing section, specifying the required environment variables for the connection.

Without these variables set, drawDB operates in standalone mode without persistence capabilities. When properly configured, the integration enables seamless collaborative workflows where users generate links and share complex database schemas instantly.

Summary

• drawDB is a browser-based diagramming tool that handles UI rendering and state management entirely on the client.
• drawdb-server provides the REST API backend required to store and retrieve diagram JSON data for sharing.
• The integration uses fetch requests to /save and /load/:id endpoints, generating unique shareable URLs with query parameters.
• Configuration requires setting REACT_APP_DRAWDB_SERVER_URL as documented in the README.
• Key implementation files include src/pages/Editor.jsx for loading logic and src/api/gists.js for API communication patterns.

Frequently Asked Questions

Do I need drawdb-server to use drawDB?

No. drawDB functions fully as a standalone client-side application without drawdb-server. The server component is only required if you want to enable the diagram sharing feature that allows users to generate persistent, shareable links.

How does drawdb-server store diagram data?

drawdb-server uses a lightweight JSON-based storage system. When drawDB sends a POST request to the /save endpoint, the server persists the diagram JSON and associates it with a unique identifier, allowing later retrieval via the /load/:id endpoint.

What API endpoints does drawdb-server expose?

drawdb-server exposes at minimum two critical endpoints: POST /save for persisting new diagrams and returning a unique ID, and GET /load/:id for retrieving stored diagram JSON by its identifier. These endpoints enable the complete sharing lifecycle from creation to access.

Where is the server communication configured in the drawDB codebase?

The connection logic is implemented using standard fetch APIs, with the server URL sourced from the REACT_APP_DRAWDB_SERVER_URL environment variable. The loading logic for shared diagrams is handled in src/pages/Editor.jsx, while src/api/gists.js provides reference patterns for external API integration similar to the drawdb-server communication.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}