How haigpapa/storylines works
Project Type and Purpose
• STORYLINES is a single-page web application (SPA) built in React/TypeScript.
Top-Level Architectural Components
• Frontend SPA (React + React Three Fiber + Zustand + D3-Force + Rapier)
• Client-side Services Layer (API wrappers for Gemini embeddings, ChromaDB, OpenLibrary, Google Books, localStorage)
• Graph Engine (force simulation + clustering)
• State Management (Zustand store holding nodes/edges/camera state)
• Build & Deployment (Vite, Tailwind, ESLint, Vercel CI/CD workflows)
External Dependencies & Services
• Gemini 2.5 API (text → 768-d embeddings)
• ChromaDB vector store (persistence & k-NN lookup)
• HDBSCAN clustering algorithm (client-side or via WASM)
• OpenLibrary & Google Books REST APIs (book metadata)
Component Relationships & Data Flow
a. User interacts with SearchPanel or uploads documents in the UI.
b. The dataService orchestrates calls to:
• geminiService → getEmbedding(text)
• openLibraryService / googleBooksService → fetch metadata
c. storageService persists embeddings and metadata to ChromaDB via its REST/JS client.
d. Once embeddings are fetched, lib/graphEngine.ts builds a force simulation:
• Runs HDBSCAN on embeddings → clusterLabels
• Configures D3-Force (forceManyBody, forceLink weighted by cosine similarity) + Rapier for collision
e. Zustand store holds the live node & edge positions; React Three Fiber renders GraphCanvas from store.
f. DevJournal logs events during initialization for debugging.
Architectural Patterns & Principles
• Layered Separation:
• Presentation (React components)
• State (Zustand store)
• Domain Logic (graphEngine, clustering, physics)
• Services/API (dataService, geminiService, etc.)
• Declarative 3D: React Three Fiber treats the 3D scene as React components.
• Physics as Metaphor: D3-Force + Rapier engine emulate proximity = semantic similarity.
• Lazy & On-Demand: Embeddings computed only for nodes in view; incremental graph expansion.
• Immutable Data Flow: State updates in the store trigger React re-renders.