# Whiteboard API

A collaborative whiteboard API that allows agents to create, read, update, and delete drawings. All changes sync in real-time to connected browser clients via WebSocket.

**Base URL:** http://whiteboard-75tz.onrender.com

## Quick Start

1. Choose a session ID (any alphanumeric string) or use an existing one
2. POST elements to `/api/sessions/{sessionId}/elements`
3. View the whiteboard at `http://whiteboard-75tz.onrender.com/{sessionId}`
4. All changes appear instantly in connected browsers

### Example: Draw a rectangle

```bash
curl -X POST http://whiteboard-75tz.onrender.com/api/sessions/my-session/elements \
  -H "Content-Type: application/json" \
  -d '{"type":"rectangle","x":100,"y":100,"width":200,"height":150,"color":"#3498db","strokeWidth":2}'
```

Then view at: http://whiteboard-75tz.onrender.com/my-session

## User Interface

The whiteboard features a horizontal toolbar design for easy access to all tools.

### Primary Toolbar (Top Row)

| Group | Contents |
|-------|----------|
| Brand | Logo, Session ID |
| History | Undo, Redo |
| Drawing Tools | Select, Pen, Line, Arrow, Rectangle, Circle, Note, Text |
| Edit Tools | Eraser, Clear All |
| Session | User count, Share button |

### Options Bar (Second Row)

| Group | Contents |
|-------|----------|
| Colors | 8 preset colors (Black, Red, Blue, Green, Orange, Purple, Teal, Dark Gray) |
| Stroke | Thin (2px), Medium (4px), Thick (8px) |
| Contextual | Tool-specific options (e.g., arrow style when arrow tool selected) |
| Zoom | Zoom out, percentage, Zoom in, Reset |
| Export | PNG, SVG export buttons |

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| V | Select tool |
| P | Pen tool |
| L | Line tool |
| A | Arrow tool |
| R | Rectangle tool |
| C | Circle tool |
| N | Note tool |
| T | Text tool |
| E | Eraser tool |
| Delete | Delete selected element |
| Ctrl+Z | Undo |
| Ctrl+Shift+Z | Redo |
| Ctrl++ | Zoom in |
| Ctrl+- | Zoom out |
| Ctrl+0 | Reset zoom |
| Space+Drag | Pan canvas |

## Coordinate System

- **Origin:** Top-left corner (0, 0)
- **X-axis:** Increases to the right
- **Y-axis:** Increases downward
- **Recommended bounds:** x: 100-800, y: 80-500 for best visibility

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/sessions/{sessionId}` | Get session info and all elements |
| GET | `/api/sessions/{sessionId}/elements` | Get all elements |
| GET | `/api/sessions/{sessionId}/elements/{elementId}` | Get specific element |
| POST | `/api/sessions/{sessionId}/elements` | Create single element |
| POST | `/api/sessions/{sessionId}/elements/batch` | Create multiple elements |
| PUT | `/api/sessions/{sessionId}/elements/{elementId}` | Update element |
| DELETE | `/api/sessions/{sessionId}/elements/{elementId}` | Delete element |
| DELETE | `/api/sessions/{sessionId}/elements` | Clear all elements |

## Element Types

### Rectangle

```json
{
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 150,
  "color": "#3498db",
  "strokeWidth": 2
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | yes | Must be "rectangle" |
| x | number | yes | X position of top-left corner |
| y | number | yes | Y position of top-left corner |
| width | number | yes | Width in pixels |
| height | number | yes | Height in pixels |
| color | string | no | Stroke color hex (default: #000000) |
| strokeWidth | number | no | Line thickness (default: 2) |

### Circle

```json
{
  "type": "circle",
  "cx": 200,
  "cy": 200,
  "radius": 50,
  "color": "#e74c3c",
  "strokeWidth": 2
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | yes | Must be "circle" |
| cx | number | yes | X position of center |
| cy | number | yes | Y position of center |
| radius | number | yes | Radius in pixels |
| color | string | no | Stroke color hex (default: #000000) |
| strokeWidth | number | no | Line thickness (default: 2) |

### Line

```json
{
  "type": "line",
  "x1": 50,
  "y1": 50,
  "x2": 200,
  "y2": 150,
  "color": "#2ecc71",
  "strokeWidth": 2
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | yes | Must be "line" |
| x1 | number | yes | Starting X position |
| y1 | number | yes | Starting Y position |
| x2 | number | yes | Ending X position |
| y2 | number | yes | Ending Y position |
| color | string | no | Line color hex (default: #000000) |
| strokeWidth | number | no | Line thickness (default: 2) |

### Arrow

```json
{
  "type": "arrow",
  "x1": 50,
  "y1": 50,
  "x2": 200,
  "y2": 150,
  "color": "#2ecc71",
  "strokeWidth": 2,
  "arrowStyle": "single"
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | yes | Must be "arrow" |
| x1 | number | yes | Starting X position |
| y1 | number | yes | Starting Y position |
| x2 | number | yes | Ending X position |
| y2 | number | yes | Ending Y position |
| color | string | no | Arrow color hex (default: #000000) |
| strokeWidth | number | no | Line thickness (default: 2) |
| arrowStyle | string | no | "single" (head at end) or "double" (heads at both ends) |

#### Single-headed Arrow (default)
```json
{"type": "arrow", "x1": 100, "y1": 100, "x2": 250, "y2": 100, "color": "#3498db", "strokeWidth": 2, "arrowStyle": "single"}
```

#### Double-headed Arrow
```json
{"type": "arrow", "x1": 100, "y1": 150, "x2": 250, "y2": 150, "color": "#e74c3c", "strokeWidth": 2, "arrowStyle": "double"}
```

### Pen (Freehand)

```json
{
  "type": "pen",
  "points": [{"x":10,"y":10},{"x":20,"y":30},{"x":40,"y":25}],
  "color": "#9b59b6",
  "strokeWidth": 2
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | yes | Must be "pen" |
| points | array | yes | Array of {x, y} coordinates |
| color | string | no | Stroke color hex (default: #000000) |
| strokeWidth | number | no | Line thickness (default: 2) |

### Text

```json
{
  "type": "text",
  "x": 100,
  "y": 100,
  "text": "Hello World",
  "fontSize": 24,
  "color": "#2c3e50"
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | yes | Must be "text" |
| x | number | yes | X position |
| y | number | yes | Y position (baseline) |
| text | string | yes | Text content |
| fontSize | number | no | Font size in pixels (default: 16) |
| color | string | no | Text color hex (default: #000000) |

### Note (Sticky Note)

```json
{
  "type": "note",
  "x": 300,
  "y": 100,
  "width": 150,
  "height": 100,
  "text": "Remember this!",
  "backgroundColor": "#fff9c4"
}
```

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| type | string | yes | Must be "note" |
| x | number | yes | X position of top-left |
| y | number | yes | Y position of top-left |
| width | number | no | Width in pixels (default: 150) |
| height | number | no | Height in pixels (default: 100) |
| text | string | yes | Note content |
| backgroundColor | string | no | Background color hex (default: #fff9c4) |

## Color Palette

| Name | Hex |
|------|-----|
| Black | #000000 |
| White | #FFFFFF |
| Red | #e74c3c |
| Blue | #3498db |
| Green | #2ecc71 |
| Yellow | #f1c40f |
| Orange | #e67e22 |
| Purple | #9b59b6 |
| Teal | #1abc9c |
| Dark Gray | #2c3e50 |
| Brown | #8B4513 |
| Pink | #e91e63 |

## Tips

- Use the batch endpoint for complex drawings to reduce API calls
- Elements render in order - later elements appear on top
- Session IDs can be any string (e.g., "project-diagram", "meeting-notes")
- Keep coordinates within x: 100-800, y: 80-500 for visibility
- All changes sync instantly to connected browsers
- Use strokeWidth to make elements more visible

## Example: Draw a House

```bash
curl -X POST http://whiteboard-75tz.onrender.com/api/sessions/my-house/elements/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"type":"rectangle","x":250,"y":180,"width":250,"height":180,"color":"#8B4513","strokeWidth":2},
    {"type":"line","x1":250,"y1":180,"x2":375,"y2":80,"color":"#8B0000","strokeWidth":2},
    {"type":"line","x1":375,"y1":80,"x2":500,"y2":180,"color":"#8B0000","strokeWidth":2},
    {"type":"rectangle","x":340,"y":280,"width":50,"height":80,"color":"#654321","strokeWidth":2},
    {"type":"rectangle","x":270,"y":210,"width":45,"height":45,"color":"#87CEEB","strokeWidth":2},
    {"type":"rectangle","x":435,"y":210,"width":45,"height":45,"color":"#87CEEB","strokeWidth":2},
    {"type":"circle","cx":550,"cy":100,"radius":35,"color":"#FFD700","strokeWidth":3},
    {"type":"text","x":300,"y":400,"text":"Home Sweet Home","fontSize":24,"color":"#2c3e50"}
  ]'
```

## Example: Draw a Flowchart

```bash
curl -X POST http://whiteboard-75tz.onrender.com/api/sessions/my-flowchart/elements/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"type":"rectangle","x":300,"y":100,"width":120,"height":50,"color":"#3498db","strokeWidth":2},
    {"type":"text","x":330,"y":130,"text":"Start","fontSize":16,"color":"#2c3e50"},
    {"type":"arrow","x1":360,"y1":150,"x2":360,"y2":200,"color":"#333333","strokeWidth":2,"arrowStyle":"single"},
    {"type":"rectangle","x":300,"y":200,"width":120,"height":50,"color":"#2ecc71","strokeWidth":2},
    {"type":"text","x":320,"y":230,"text":"Process","fontSize":16,"color":"#2c3e50"},
    {"type":"arrow","x1":360,"y1":250,"x2":360,"y2":300,"color":"#333333","strokeWidth":2,"arrowStyle":"single"},
    {"type":"rectangle","x":300,"y":300,"width":120,"height":50,"color":"#e74c3c","strokeWidth":2},
    {"type":"text","x":340,"y":330,"text":"End","fontSize":16,"color":"#2c3e50"}
  ]'
```