GeneralBots/botserver
2
1
Fork 0
Code Issues Pull requests Projects Releases 323 Packages Wiki Activity Actions
botserver/docs/src/chapter-10-api/whiteboard-api.md

7.1 KiB
Raw Blame History

Whiteboard API

The Whiteboard API provides endpoints for collaborative drawing, diagramming, and visual collaboration within BotServer.

Status

⚠️ NOT IMPLEMENTED

This API is planned for future development but is not currently available in BotServer.

Planned Features

The Whiteboard API will enable:

  • Collaborative real-time drawing
  • Shape and diagram creation
  • Text annotations
  • Image uploads
  • Multi-user cursors
  • Version history
  • Export capabilities

Planned Endpoints

Whiteboard Management

  • POST /api/v1/whiteboards - Create whiteboard
  • GET /api/v1/whiteboards/{board_id} - Get whiteboard
  • PATCH /api/v1/whiteboards/{board_id} - Update whiteboard
  • DELETE /api/v1/whiteboards/{board_id} - Delete whiteboard
  • GET /api/v1/whiteboards - List whiteboards

Collaboration

  • POST /api/v1/whiteboards/{board_id}/join - Join session
  • POST /api/v1/whiteboards/{board_id}/leave - Leave session
  • GET /api/v1/whiteboards/{board_id}/participants - List participants
  • WebSocket /api/v1/whiteboards/{board_id}/ws - Real-time updates

Content Operations

  • POST /api/v1/whiteboards/{board_id}/elements - Add element
  • PATCH /api/v1/whiteboards/{board_id}/elements/{element_id} - Update element
  • DELETE /api/v1/whiteboards/{board_id}/elements/{element_id} - Delete element
  • POST /api/v1/whiteboards/{board_id}/clear - Clear board

Export

  • GET /api/v1/whiteboards/{board_id}/export/png - Export as PNG
  • GET /api/v1/whiteboards/{board_id}/export/svg - Export as SVG
  • GET /api/v1/whiteboards/{board_id}/export/pdf - Export as PDF

Planned Integration with BASIC

When implemented, whiteboard features will be accessible via BASIC keywords:

' Create whiteboard (not yet available)
board_id = CREATE WHITEBOARD "Architecture Diagram"
SHARE WHITEBOARD board_id, ["user123", "user456"]

' Add content (not yet available)
ADD TO WHITEBOARD board_id, "rectangle", {x: 100, y: 100, width: 200, height: 100}
ADD TO WHITEBOARD board_id, "text", {x: 150, y: 150, text: "Component A"}

' Export whiteboard (not yet available)
image_url = EXPORT WHITEBOARD board_id, "png"
SEND FILE image_url

Planned Data Models

Whiteboard

{
  "board_id": "wb_123",
  "name": "Architecture Diagram",
  "owner": "user123",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z",
  "settings": {
    "background": "grid",
    "canvas_width": 1920,
    "canvas_height": 1080,
    "allow_anonymous": false,
    "max_participants": 50
  },
  "participants": [
    {
      "user_id": "user123",
      "role": "owner",
      "cursor_position": {"x": 500, "y": 300}
    }
  ],
  "element_count": 42
}

Drawing Element

{
  "element_id": "elem_456",
  "board_id": "wb_123",
  "type": "rectangle",
  "properties": {
    "x": 100,
    "y": 100,
    "width": 200,
    "height": 100,
    "fill": "#ffffff",
    "stroke": "#000000",
    "stroke_width": 2
  },
  "created_by": "user123",
  "created_at": "2024-01-15T10:05:00Z",
  "z_index": 1
}

Planned Features Detail

Drawing Tools

  • Basic Shapes: Rectangle, circle, triangle, line, arrow
  • Freehand Drawing: Pen, pencil, highlighter
  • Text Tools: Labels, sticky notes, comments
  • Connectors: Smart connectors between shapes
  • Templates: Flowcharts, mind maps, wireframes

Collaboration Features

  • Real-time cursor tracking
  • User presence indicators
  • Change notifications
  • Commenting system
  • Version control
  • Conflict resolution

Advanced Features

  • Layers support
  • Grouping elements
  • Alignment and distribution
  • Copy/paste between boards
  • Undo/redo history
  • Keyboard shortcuts

Implementation Considerations

When implemented, the Whiteboard API will:

  1. Use WebSocket for real-time collaboration
  2. Implement CRDT for conflict-free editing
  3. Store in PostgreSQL with JSON columns
  4. Cache in cache component for performance
  5. Use SVG as primary format
  6. Support touch devices and stylus input
  7. Include access controls and permissions

Alternative Solutions

Until the Whiteboard API is implemented, consider:

  1. External Whiteboard Services

    • Integrate with Miro API
    • Embed Excalidraw
    • Use draw.io (diagrams.net)
    • Connect to Microsoft Whiteboard

  2. Simple Drawing Storage

    ' Store drawing as JSON
drawing = {
    "shapes": [
        {"type": "rect", "x": 10, "y": 10, "w": 100, "h": 50}
    ]
}
SET BOT MEMORY "drawing_001", JSON_STRINGIFY(drawing)

  3. Image-Based Collaboration

    • Upload and annotate images
    • Use existing image editing APIs
    • Share screenshots with markup

Future Technology Stack

The planned implementation will use:

  • Canvas API or SVG - Rendering
  • WebSocket - Real-time sync
  • Y.js or OT.js - Collaborative editing
  • Fabric.js - Canvas manipulation
  • PostgreSQL - Data persistence
  • Cache - Real-time state
  • Sharp - Image processing

Workaround Example

Until the Whiteboard API is available, you can implement basic diagram storage:

' Simple diagram system using text
FUNCTION CreateDiagram(name)
    diagram = {
        "name": name,
        "elements": [],
        "connections": []
    }
    SET BOT MEMORY "diagram_" + name, JSON_STRINGIFY(diagram)
    RETURN name
END FUNCTION

FUNCTION AddElement(diagram_name, element_type, label)
    diagram_key = "diagram_" + diagram_name
    diagram_json = GET BOT MEMORY diagram_key
    diagram = JSON_PARSE(diagram_json)
    
    element = {
        "id": GENERATE_ID(),
        "type": element_type,
        "label": label
    }
    
    diagram.elements = APPEND(diagram.elements, element)
    SET BOT MEMORY diagram_key, JSON_STRINGIFY(diagram)
    RETURN element.id
END FUNCTION

FUNCTION GenerateAsciiDiagram(diagram_name)
    diagram_json = GET BOT MEMORY "diagram_" + diagram_name
    diagram = JSON_PARSE(diagram_json)
    
    output = "Diagram: " + diagram.name + "\n\n"
    
    FOR EACH element IN diagram.elements
        IF element.type = "box" THEN
            output = output + "[" + element.label + "]\n"
        ELSE IF element.type = "circle" THEN
            output = output + "(" + element.label + ")\n"
        END IF
    NEXT
    
    RETURN output
END FUNCTION

Use Cases

Technical Planning

  • Architecture diagrams
  • Database schemas
  • Network topology
  • UML diagrams
  • Flowcharts

Business Collaboration

  • Mind mapping
  • Process flows
  • Organizational charts
  • Brainstorming sessions
  • Project planning

Education

  • Teaching illustrations
  • Student collaboration
  • Problem solving
  • Visual explanations

Integration Points

When available, the Whiteboard API will integrate with:

Status Updates

Check the GitHub repository for updates on Whiteboard API implementation status.

For immediate visual collaboration needs, consider embedding existing solutions like Excalidraw or Miro rather than waiting for the native implementation.