# haigpapa/storylines architecture

> Architecture diagram of the GitHub repository haigpapa/storylines, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haigpapa/storylines
- Repository: https://github.com/haigpapa/storylines

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point
    subgraph "Entry Point"
        direction TB
        Main["main.tsx"]:::frontend
        App["App.tsx"]:::frontend
        Index["index.html"]:::frontend
    end

    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        GraphCanvas["GraphCanvas"]:::frontend
        SearchPanel["SearchPanel"]:::frontend
        NodeInfoPanel["NodeInfoPanel"]:::frontend
        DevJournal["DevJournal"]:::frontend
        Toolbar["Toolbar"]:::frontend
        Legend["Legend"]:::frontend
    end

    %% State Layer
    subgraph "State Layer"
        direction TB
        Store["useGraphStore"]:::state
    end

    %% Engine Layer
    subgraph "Engine Layer"
        direction TB
        GraphEngine["graphEngine.ts"]:::engine
        ForceSim["Force Simulation\n(D3-Force + Rapier)"]:::engine
        Clustering["HDBSCAN Clustering"]:::engine
    end

    %% Services Layer
    subgraph "Services Layer"
        direction TB
        DataService["dataService.ts"]:::service
        GeminiService["geminiService.ts"]:::service
        OpenLibraryService["openLibraryService.ts"]:::service
        GoogleBooksService["googleBooksService.ts"]:::service
        StorageService["storageService.ts"]:::service
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        GeminiAPI["Gemini 2.5 API"]:::external
        ChromaDB["ChromaDB"]:::external
        OpenLibraryAPI["OpenLibrary API"]:::external
        GoogleBooksAPI["Google Books API"]:::external
    end

    %% Config & CI/CD
    subgraph "Config & Build" 
        direction TB
        Tailwind["tailwind.config.js"]:::config
        PostCSS["postcss.config.js"]:::config
        ViteConfig["vite.config.ts"]:::config
        ESLint["eslint.config.js"]:::config
        Vercel["vercel.json"]:::config
        GHDeploy[".github/workflows/deploy.yml"]:::config
        GHTest[".github/workflows/test.yml"]:::config
        Docs["DEPLOYMENT.md\nDEPLOYMENT_NOTES.md"]:::config
    end

    %% Connections
    Main --> App
    App --> GraphCanvas
    App --> SearchPanel
    App --> NodeInfoPanel
    App --> DevJournal
    App --> Toolbar
    App --> Legend

    GraphCanvas -->|"reads state"| Store
    SearchPanel -->|"dispatch search"| Store
    Toolbar -->|"controls simulation"| Store
    Legend -->|"toggles view"| Store
    NodeInfoPanel -->|"subscribes"| Store
    DevJournal -->|"logs events"| Store

    Store -->|"init simulation"| GraphEngine
    GraphEngine --> ForceSim
    GraphEngine --> Clustering
    ForceSim -->|"tick update"| Store
    Clustering -->|"cluster labels"| Store

    Store -->|"request data"| DataService
    DataService -->|"getEmbedding(text)"| GeminiService
    DataService -->|"fetchMetadata(isbn)"| OpenLibraryService
    DataService -->|"fetchMetadata(isbn)"| GoogleBooksService
    DataService -->|"persist embeddings"| StorageService

    GeminiService -->|"REST call"| GeminiAPI
    StorageService -->|"JS client"| ChromaDB
    OpenLibraryService -->|"REST call"| OpenLibraryAPI
    GoogleBooksService -->|"REST call"| GoogleBooksAPI

    %% click events
    click Main "https://github.com/haigpapa/storylines/blob/main/src/main.tsx"
    click App "https://github.com/haigpapa/storylines/blob/main/src/App.tsx"
    click GraphCanvas "https://github.com/haigpapa/storylines/blob/main/src/components/graph/GraphCanvas.tsx"
    click SearchPanel "https://github.com/haigpapa/storylines/blob/main/src/components/search/SearchPanel.tsx"
    click NodeInfoPanel "https://github.com/haigpapa/storylines/blob/main/src/components/nodes/NodeInfoPanel.tsx"
    click DevJournal "https://github.com/haigpapa/storylines/blob/main/src/components/journal/DevJournal.tsx"
    click Toolbar "https://github.com/haigpapa/storylines/blob/main/src/components/ui/Toolbar.tsx"
    click Legend "https://github.com/haigpapa/storylines/blob/main/src/components/ui/Legend.tsx"
    click Store "https://github.com/haigpapa/storylines/blob/main/src/store/useGraphStore.ts"
    click GraphEngine "https://github.com/haigpapa/storylines/blob/main/src/lib/graphEngine.ts"
    click DataService "https://github.com/haigpapa/storylines/blob/main/src/services/dataService.ts"
    click GeminiService "https://github.com/haigpapa/storylines/blob/main/src/services/geminiService.ts"
    click OpenLibraryService "https://github.com/haigpapa/storylines/blob/main/src/services/openLibraryService.ts"
    click GoogleBooksService "https://github.com/haigpapa/storylines/blob/main/src/services/googleBooksService.ts"
    click StorageService "https://github.com/haigpapa/storylines/blob/main/src/services/storageService.ts"
    click Tailwind "https://github.com/haigpapa/storylines/blob/main/tailwind.config.js"
    click PostCSS "https://github.com/haigpapa/storylines/blob/main/postcss.config.js"
    click ViteConfig "https://github.com/haigpapa/storylines/blob/main/vite.config.ts"
    click ESLint "https://github.com/haigpapa/storylines/blob/main/eslint.config.js"
    click Vercel "https://github.com/haigpapa/storylines/blob/main/vercel.json"
    click GHDeploy "https://github.com/haigpapa/storylines/blob/main/.github/workflows/deploy.yml"
    click GHTest "https://github.com/haigpapa/storylines/blob/main/.github/workflows/test.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#1E90FF,color:#000
    classDef state fill:#DFFFD0,stroke:#32CD32,color:#000
    classDef engine fill:#FFE8B0,stroke:#FF8C00,color:#000
    classDef service fill:#F0F0F0,stroke:#A9A9A9,color:#000
    classDef external fill:#FFD0D0,stroke:#FF0000,color:#000
    classDef config fill:#E8D0FF,stroke:#9400D3,color:#000
```
