How deta/surf works
Project Type & Purpose
• Deta Surf is a desktop “full-stack” Electron application combining:
• A Svelte/TypeScript UI (renderer + preload + service libraries)
• An Electron main process for window + IPC + orchestration
• Rust-based local servers (AI “brain” & HTTP API)
• Local data persistence (SFFS flat-file system + SQLite migrations)
• Background workers (image processing, OCR, parsing)
Top-Level Architecture Components
a. Electron Layer
• Renderer (app/src/renderer/*): Svelte components for Core, PDF, Resource, Settings
• Preload (app/src/preload/*): TypeScript bridge exposing safe IPC & service APIs
• Main (app/src/main/*): Bootstraps windows, manages menus, permissions, web requests, launches workers
b. Service Libraries (packages/services & packages/types)
• UI-side business logic for AI prompts, context management, IPC messaging, notebooks, tabs
c. Rust Servers
• packages/backend-server: Rust HTTP server exposing endpoints for embeddings, AI interactions, KV, messaging
• packages/backend: Rust library for AI “brain”, LLM clients, session/store management, worker handlers
d. Data Storage & Workers
• SFFS (Surf Flat File System): local open-format library storage
• SQLite migrations (packages/backend/migrations)
• Workers: imageProcessor.ts and Rust-spawned background tasks (OCR, parsing)
e. External Services
• LLM providers (OpenAI, local LLMs, cloud models)
• Web services (YouTube, webpages, RSS) via web-parser
• Browser context (via webContents)
Key Interactions & Data Flows
1. User clicks UI button → Renderer Svelte component
2. Renderer → Preload exposes IPC call or service method
3. Preload → Main process (via Electron’s IPC)
4. Main → Either:
• Directly invoke local worker (imageProcessor, OCR)
• HTTP call to local Rust server (backend-server)
5. Rust server → embeds & AI “brain” library (packages/backend) → persists to SQLite/SFFS
6. Rust server → returns JSON/stream to Main
7. Main → Preload (IPC response) → Renderer updates UI
Architectural Patterns & Principles
• Layered architecture (UI → Preload → Main → Backend → Data)
• Separation of concerns: UI vs. business logic vs. data store
• Local-first philosophy: all data and AI inference run locally when possible
• Monorepo with scope-based packages (services, types, core UI, Rust backends)
• Use of IPC for secure context bridging
• Worker threads & spawned Rust processes for CPU-bound tasks
Final Advice
• Keep details: mention workers (OCR, imageProcessor), migrations, service handlers
• Separation: UI, IPC, orchestration, AI backend, storage, external