Initial architecture document for FolkJS migration
This commit is contained in:
commit
b5abd33cfd
|
|
@ -0,0 +1,198 @@
|
||||||
|
# FolkJS + Canvas-Website → rSpace.online Migration
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This document outlines the architectural strategy for migrating canvas-website's tldraw-based features to FolkJS infrastructure, deployable as community spaces on rSpace.online.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Fundamental Paradigm Shift
|
||||||
|
|
||||||
|
### TLdraw (current canvas-website)
|
||||||
|
- Canvas is an **isolated drawing surface** separate from the DOM
|
||||||
|
- Shapes are custom React components rendered into a canvas coordinate system
|
||||||
|
- State lives in a TLStore, synced via Automerge CRDT
|
||||||
|
- The canvas is an *application* you load
|
||||||
|
|
||||||
|
### FolkJS
|
||||||
|
- Spatial relationships are **native web primitives**
|
||||||
|
- HTML documents *become* spatial canvases seamlessly
|
||||||
|
- Elements communicate through **proximity-based connections**
|
||||||
|
- The web itself is the canvas - you can annotate, re-layout, and program *any* existing webpage
|
||||||
|
- "Folk programs" blur document/application boundaries
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current Canvas-Website Features
|
||||||
|
|
||||||
|
| Category | Features |
|
||||||
|
|----------|----------|
|
||||||
|
| **AI Generation** | ImageGen (SD/SDXL), VideoGen (Wan2.1), Prompt (LLM) |
|
||||||
|
| **Collaboration** | Automerge CRDT, WebSocket sync, presence awareness |
|
||||||
|
| **Knowledge Management** | Obsidian integration, Fathom notes, Markdown editing |
|
||||||
|
| **Communication** | Video chat (Daily.co), transcription (Whisper) |
|
||||||
|
| **Data Visualization** | HolonShape (H3 hexagonal), MapShape (OSM), graph layouts |
|
||||||
|
| **Privacy/Sovereignty** | PrivateWorkspaceShape, CryptID auth, per-board permissions |
|
||||||
|
| **23 Custom Shapes** | Each with StandardizedToolWrapper, theming, pinning |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Migration Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ rSpace.online Architecture │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────┐ ┌──────────────────────────────────┐ │
|
||||||
|
│ │ FolkJS Core │ │ Canvas-Website Features │ │
|
||||||
|
│ ├──────────────────┤ ├──────────────────────────────────┤ │
|
||||||
|
│ │ • HTML↔Canvas │ │ • 23 Custom Shapes │ │
|
||||||
|
│ │ transformation │ │ • AI Orchestrator │ │
|
||||||
|
│ │ • Proximity- │ + │ • Automerge CRDT Sync │ │
|
||||||
|
│ │ based relations│ │ • Obsidian/Fathom Integration │ │
|
||||||
|
│ │ • Web │ │ • Video/Audio/Transcription │ │
|
||||||
|
│ │ augmentation │ │ • Privacy Workspaces │ │
|
||||||
|
│ │ • Propagators │ │ • Permission System │ │
|
||||||
|
│ └────────┬─────────┘ └──────────────┬───────────────────┘ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────┬───────────────┘ │
|
||||||
|
│ ▼ │
|
||||||
|
│ ┌─────────────────────────────┐ │
|
||||||
|
│ │ Deployable Community │ │
|
||||||
|
│ │ Spaces │ │
|
||||||
|
│ ├─────────────────────────────┤ │
|
||||||
|
│ │ • Per-community instances │ │
|
||||||
|
│ │ • Custom shape libraries │ │
|
||||||
|
│ │ • Themed experiences │ │
|
||||||
|
│ │ • Federated identity │ │
|
||||||
|
│ └─────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Advantages of FolkJS Foundation
|
||||||
|
|
||||||
|
### 1. Web-Native Spatial Primitives
|
||||||
|
- Shapes become *actual HTML custom elements* that work anywhere
|
||||||
|
- `<folk-imagegen>`, `<folk-videoconf>`, `<folk-obsidian-note>`
|
||||||
|
- Embeddable in any webpage, not just your canvas
|
||||||
|
|
||||||
|
### 2. Progressive Enhancement
|
||||||
|
- Communities start with simple HTML pages
|
||||||
|
- Gradually add spatial capabilities without migration
|
||||||
|
- Existing web content becomes annotatable/programmable
|
||||||
|
|
||||||
|
### 3. LLM Integration Path
|
||||||
|
- FolkJS explicitly explores "LLM capabilities across any webpage"
|
||||||
|
- AI orchestrator could power Folk programs that intelligently compose interfaces
|
||||||
|
|
||||||
|
### 4. Lower Barrier to Entry
|
||||||
|
- Folk programs are "authored entirely in HTML"
|
||||||
|
- Communities create custom tools without deep React/TypeScript knowledge
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Migration Phases
|
||||||
|
|
||||||
|
### Phase 1: Core Infrastructure
|
||||||
|
- Port Automerge sync layer to work with FolkJS's propagator system
|
||||||
|
- Create `folk-shape` base class that mirrors StandardizedToolWrapper behavior
|
||||||
|
- Implement proximity-based connections between shapes
|
||||||
|
|
||||||
|
### Phase 2: Shape Migration
|
||||||
|
Convert high-value shapes first:
|
||||||
|
- `ImageGenShape` → `<folk-imagegen>`
|
||||||
|
- `MarkdownShape` → `<folk-markdown>`
|
||||||
|
- `ObsNoteShape` → `<folk-obsidian>`
|
||||||
|
- Preserve AI orchestrator integration
|
||||||
|
|
||||||
|
### Phase 3: Community Deployment
|
||||||
|
- Multi-tenant architecture on rSpace.online
|
||||||
|
- Per-community shape libraries (enable/disable features)
|
||||||
|
- Federated identity (CryptID across spaces)
|
||||||
|
- Community-specific themes and layouts
|
||||||
|
|
||||||
|
### Phase 4: Web Augmentation
|
||||||
|
- Enable communities to annotate *any* webpage spatially
|
||||||
|
- "Save to rSpace" browser extension
|
||||||
|
- Collaborative annotation layers over external sites
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical Decisions
|
||||||
|
|
||||||
|
### What to Keep from Canvas-Website
|
||||||
|
- **Automerge CRDT** - Superior offline-first sync
|
||||||
|
- **AI Orchestrator** - Local/cloud routing (RS8000 + RunPod)
|
||||||
|
- **R2 asset storage** - Cloudflare integration pattern
|
||||||
|
- **Permission system** - Board-level access control
|
||||||
|
- **CryptID auth** - Self-sovereign identity
|
||||||
|
|
||||||
|
### What FolkJS Provides
|
||||||
|
- Spatial primitives as web components
|
||||||
|
- Proximity/relation system
|
||||||
|
- HTML↔Canvas fluidity
|
||||||
|
- Propagator event system
|
||||||
|
- Simulation/physics for layout
|
||||||
|
|
||||||
|
### What Needs New Development
|
||||||
|
- Multi-tenant deployment infrastructure
|
||||||
|
- Community management dashboard
|
||||||
|
- Shape marketplace/library system
|
||||||
|
- Cross-space federation protocol
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## rSpace.online Vision
|
||||||
|
|
||||||
|
```
|
||||||
|
https://mycofi.rspace.online → MycoFi community space
|
||||||
|
https://commons.rspace.online → Commons Stack community
|
||||||
|
https://token.rspace.online → Token Engineering community
|
||||||
|
https://custom.rspace.online → Any community's custom space
|
||||||
|
|
||||||
|
Each space:
|
||||||
|
├── FolkJS foundation (spatial web primitives)
|
||||||
|
├── Canvas-website shapes (AI, collab, knowledge)
|
||||||
|
├── Community-specific shapes (custom tools)
|
||||||
|
├── Shared identity (CryptID federation)
|
||||||
|
└── Configurable feature flags
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Risks & Mitigations
|
||||||
|
|
||||||
|
| Risk | Mitigation |
|
||||||
|
|------|------------|
|
||||||
|
| FolkJS is pre-1.0, unstable | Fork and stabilize core primitives needed |
|
||||||
|
| Learning curve for team | Start with simple shapes, migrate incrementally |
|
||||||
|
| Performance at scale | Benchmark early, optimize relation system |
|
||||||
|
| Loss of tldraw features | Keep tldraw as optional rendering backend |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. **Clone folkjs** and explore the monorepo structure
|
||||||
|
2. **Build a proof-of-concept**: Port `MarkdownShape` to a Folk component
|
||||||
|
3. **Test the sync story**: Can Automerge work with Folk's propagator system?
|
||||||
|
4. **Prototype multi-tenancy**: Single deployment, community subdomains
|
||||||
|
5. **Create decision documents** for architectural choices
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- [FolkJS Website](https://folkjs.org)
|
||||||
|
- [FolkJS GitHub](https://github.com/folk-canvas/folk-canvas)
|
||||||
|
- [FolkJS Live 2025 Presentation](https://folkjs.org/live-2025/)
|
||||||
|
- [Canvas-Website Repository](/home/jeffe/Github/canvas-website)
|
||||||
|
- [TLdraw Documentation](https://tldraw.dev)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Document created: 2025-12-11*
|
||||||
Loading…
Reference in New Issue