From b5abd33cfd44b8de24835e400433650b279bbb9b Mon Sep 17 00:00:00 2001 From: Jeff Emmett Date: Thu, 11 Dec 2025 16:40:43 -0500 Subject: [PATCH] Initial architecture document for FolkJS migration --- ARCHITECTURE.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..21f6089 --- /dev/null +++ b/ARCHITECTURE.md @@ -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 +- ``, ``, `` +- 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` → `` +- `MarkdownShape` → `` +- `ObsNoteShape` → `` +- 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*