docs/README.md

ColorRM Pro

A real-time collaborative PDF annotation and drawing application built with modern web technologies.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    color_rm.html                          │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
│  │  │ ColorRm     │  │ ColorRm     │  │ ColorRm         │   │   │
│  │  │ Session.js  │──│ Renderer.js │──│ LiveSync.js     │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Backend                                  │
│  ┌──────────────────────┐    ┌─────────────────────────────┐    │
│  │  Cloudflare Workers  │    │  HuggingFace Spaces         │    │
│  │  ┌────────────────┐  │    │  ┌───────────────────────┐  │    │
│  │  │ worker.ts      │  │    │  │ Vite Dev Server       │  │    │
│  │  │ - API Routes   │  │    │  │ - Static files        │  │    │
│  │  │ - R2 Storage   │  │    │  │ - PDF Convert (7861)  │  │    │
│  │  └────────────────┘  │    │  └───────────────────────┘  │    │
│  │  ┌────────────────┐  │    └─────────────────────────────┘    │
│  │  │ Durable Objects│  │                                        │
│  │  │ - ColorRm DO   │  │    ┌─────────────────────────────┐    │
│  │  └────────────────┘  │    │  Liveblocks                 │    │
│  └──────────────────────┘    │  - Real-time sync           │    │
│                              │  - Presence                  │    │
│                              │  - Room management           │    │
│                              └─────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Key Modules

Frontend (public/scripts/modules/)

Module	Description
ColorRmSession.js	Main application controller. Handles state, tools, page management, import/export
ColorRmRenderer.js	Canvas rendering engine. Draws strokes, shapes, images, handles transformations
ColorRmStorage.js	IndexedDB and R2 storage. Manages local persistence and cloud sync
ColorRmLiveSync.js	Liveblocks integration. Real-time collaboration, cursors, history sync
ColorRmSvgImporter.js	SVG parsing and import. Converts SVG elements to ColorRM history items
ColorRmSvgExporter.js	SVG export. Renders history to vector SVG format

Backend (worker/)

File	Description
worker.ts	Main Cloudflare Worker entry point. Routes API requests
colorRmAssets.ts	R2 storage handlers for pages, history, modifications
pdfToSvg.ts	PDF conversion job management (placeholder for CF Workers)
ColorRmDurableObject.ts	Durable Object for room state management

Commands (cmd/)

Script	Description
pdf_convert_server.mjs	Local PDF to SVG server using pdf2svg binary
hf_init.mjs	HuggingFace authentication initialization
hf_backup.mjs	Periodic backup to HuggingFace Hub
hf_restore.mjs	Restore from HuggingFace Hub on startup

Data Flow

SVG Import Flow

1. User selects SVG file
   │
2. ColorRmSvgImporter.importSvg() parses SVG
   │
3. Elements are classified:
   ├── Images/Text → Rasterized to background blob
   └── Strokes/Shapes → Kept as vector history items
   │
4. Page object created with blob + history
   │
5. Sync to cloud:
   ├── Blob → R2 via _uploadPageBlob()
   ├── History → R2 via /api/color_rm/history/:sessionId/:pageId
   └── Structure → Liveblocks via _syncPageStructureToLive()
   │
6. Other users receive notification via Liveblocks
   │
7. Other users fetch page blob from R2

History Sync (Delta Architecture)

For pages with base history (SVG imports):

┌─────────────────────────────────────────────────────────────┐
│                    R2 Storage (Base)                         │
│  /api/color_rm/history/:sessionId/:pageId                   │
│  - Original SVG items (large, stored once)                  │
└─────────────────────────────────────────────────────────────┘
                              +
┌─────────────────────────────────────────────────────────────┐
│                 Liveblocks (Deltas Only)                     │
│  - New strokes added by users                               │
│  - Modifications to base items (position, color, etc.)      │
└─────────────────────────────────────────────────────────────┘
                              =
┌─────────────────────────────────────────────────────────────┐
│                    Final Rendered Page                       │
│  BaseHistory + Deltas + Modifications                       │
└─────────────────────────────────────────────────────────────┘

Thresholds

Condition	Threshold	Action
SVG page history	> 400 items	Use R2 for base, Liveblocks for deltas
Regular page history	> 2000 items	Convert to hybrid R2/Liveblocks
Modifications	> 100 items	Store in R2, sync metadata via Liveblocks

API Endpoints

Page Management

Method	Endpoint	Description
POST	/api/color_rm/page/:sessionId/:pageId	Upload page blob
GET	/api/color_rm/page/:sessionId/:pageId	Download page blob
DELETE	/api/color_rm/page/:sessionId/:pageId	Delete page

History

Method	Endpoint	Description
POST	/api/color_rm/history/:sessionId/:pageId	Upload base history
GET	/api/color_rm/history/:sessionId/:pageId	Get base history

Page Structure

Method	Endpoint	Description
GET	/api/color_rm/page_structure/:sessionId	Get page order
POST	/api/color_rm/page_structure/:sessionId	Update page order

PDF Conversion (Local Server)

Method	Endpoint	Description
POST	/convert/pdf	Upload PDF for conversion
GET	/convert/status/:jobId	Check conversion status
GET	/convert/page/:jobId/:pageNum	Download converted SVG page

Development

Local Development

npm install
npm run dev

HuggingFace Spaces Deployment

The Dockerfile runs:

1. hf_init.mjs - Authenticate with HF
2. hf_restore.mjs - Restore previous state
3. npm run dev - Vite dev server (port 7860)
4. hf_backup.mjs - Periodic backup worker
5. pdf_convert_server.mjs - PDF conversion (port 7861)

Environment Variables

Variable	Description
HF_TOKEN	HuggingFace API token
LIVEBLOCKS_SECRET_KEY	Liveblocks API key
PORT	Dev server port (default: 7860)

Tools

Tool	Shortcut	Description
Move	V	Select and move objects
Hand	H	Pan the canvas
Lasso	L	Free-form selection
Pen	P	Freehand drawing
Shape	S	Draw shapes (rect, ellipse, arrow, etc.)
Text	T	Add text annotations
Eraser	E	Erase strokes
Box/Capture	B	Capture region to clipboard

Collaboration Features

• Real-time cursors: See other users' cursors
• Live history sync: Strokes appear instantly for all users
• Page structure sync: Page order synchronized across users
• Presence indicators: See who's online in the room