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