# rawgraphs/rawgraphs-app architecture

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

- Interactive diagram: https://gitdiagram.com/rawgraphs/rawgraphs-app
- Repository: https://github.com/rawgraphs/rawgraphs-app

## Overview

##### Project Type and Purpose
- RAWGraphs is a client-only, single-page web application (SPA) for creating SVG-based data visualizations on top of D3.js.
- There is no backend or server-side data storage: all data parsing, processing, and rendering happen in the browser.

##### Key Architectural Layers
a. Static Asset Layer (“public” folder)
– index.html, manifest.json, robots.txt
– Sample datasets served as TSV/CSV files under public/sample-datasets
b. Application Shell (Browser)
– React SPA bootstrapped in src/index.js
– Service Worker (src/serviceWorker.js) for asset caching & offline support
– Web Worker (src/worker/worker.js) for heavy or asynchronous layout computations
c. UI Component Layer (src/components)
– ChartSelector: choose visualization type
– DataLoader: supports UploadFile, URL fetch, SPARQL, Paste, LoadProject
– DataMapping: map raw rows to chart dimensions
– ChartPreview / ChartPreviewWithOptions: render D3 output into SVG
– Exporter / CopyToClipboardButton: export SVG or raw config
– Utility components: Modal, JsonViewer, DataTable/DataGrid, InlineColorPicker, etc.
d. Core Logic & Hooks (src/charts.js, src/hooks)
– charts.js: registry of built-in chart layouts
– useDataLoader, useDataLoaderUtils: parsing and validation
– useCustomCharts: loading user-defined layouts dynamically
– useWindowSize, useDebounce, etc. for UI responsiveness
e. Styling & Fonts (src/styles)
– SCSS modules for component styles, global index.scss
– Embedded IBM-Plex and Inter Web font assets

##### Visualizing Component Relationships & Data Flow
- At startup, index.html loads the JS bundle → React initializes App.js → Service Worker registers → Main UI renders → Web Worker spun up (optionally) for layout tasks.
- User triggers DataLoader → raw data passed to parsing hooks → structured dataset delivered to DataMapping → mapping result + user options sent to ChartOptions → ChartPreviewWithOptions requests layout from charts.js (or Web Worker) → returns SVG elements → displayed in UI.
- On “export,” Exporter serializes SVG or JSON and uses CopyToClipboardButton or triggers file download.

##### Architectural Patterns & Principles
- Component-driven UI (React) with isolated, reusable modules.
- Hooks for cross-cutting logic (data parsing, custom chart loading, sizing).
- SPA with clear separation of concerns: static assets vs. UI vs. processing engine vs. export utilities.
- Client-only data privacy: zero backend, no network calls except optional URL/SPARQL fetch.
- Extensibility: dynamic loading of user-provided chart layouts via import_export scripts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Static Assets Layer
    subgraph "Static Asset Layer"
        direction TB
        indexHTML["index.html"]:::static
        manifest["manifest.json"]:::static
        robots["robots.txt"]:::static
        sampleDatasets(("Sample Datasets")):::static
    end

    %% Browser Boundary
    subgraph "Browser"
        direction TB

        %% Service Worker Lane
        subgraph "Service Worker" 
            direction TB
            SW["Service Worker"]:::worker
        end

        %% Web Worker Lane
        subgraph "Web Worker"
            direction TB
            WW["Web Worker"]:::worker
        end

        %% UI Thread Lane
        subgraph "UI Thread"
            direction TB
            ReactEntry["src/index.js"]:::ui
            ChartSelector["ChartSelector"]:::ui
            DataLoader["DataLoader"]:::ui
            UploadFile["UploadFile Loader"]:::ui
            UrlFetch["UrlFetch Loader"]:::ui
            SparqlFetch["SparqlFetch Loader"]:::ui
            Paste["Paste Loader"]:::ui
            LoadProject["LoadProject Loader"]:::ui
            DataMapping["DataMapping"]:::ui
            ChartOptions["ChartOptions"]:::ui
            ChartPreviewWithOptions["ChartPreviewWithOptions"]:::ui
            Exporter["Exporter"]:::ui
            CopyClipboard["CopyToClipboardButton"]:::ui
        end

        %% Core Logic & Hooks Layer
        subgraph "Core Logic & Hooks"
            direction TB
            ChartsJS["charts.js"]:::processing
            useDataLoader["useDataLoader"]:::processing
            Parser["parser.js"]:::processing
            Stack["stack.js"]:::processing
            useCustomCharts["useCustomCharts"]:::processing
            useWindowSize["useWindowSize"]:::processing
            useDebounce["useDebounce"]:::processing
        end
    end

    %% External Library
    D3["D3.js"]:::external

    %% File System / Clipboard
    FileSystem(("File System / Clipboard")):::external

    %% Static Assets -> Browser
    indexHTML --> ReactEntry
    manifest --> ReactEntry
    robots --> ReactEntry
    sampleDatasets --> ReactEntry

    %% Service Worker registration
    ReactEntry --> SW

    %% Web Worker setup
    ReactEntry --> WW

    %% UI Thread flow
    ReactEntry --> ChartSelector
    ChartSelector --> DataLoader
    DataLoader --> UploadFile
    DataLoader --> UrlFetch
    DataLoader --> SparqlFetch
    DataLoader --> Paste
    DataLoader --> LoadProject
    DataLoader --> useDataLoader
    useDataLoader --> Parser
    useDataLoader --> Stack
    useDataLoader --> DataMapping
    DataMapping --> ChartOptions
    ChartOptions --> ChartPreviewWithOptions

    %% Chart rendering uses charts.js and Web Worker
    ChartPreviewWithOptions --> ChartsJS
    ChartPreviewWithOptions --> D3
    ChartPreviewWithOptions -.-> WW
    WW -.-> ChartsJS

    %% Hooks usage
    DataLoader --> useCustomCharts
    ChartSelector --> useCustomCharts
    ChartPreviewWithOptions --> useWindowSize
    ChartPreviewWithOptions --> useDebounce

    %% Export flow
    ChartPreviewWithOptions --> Exporter
    Exporter --> CopyClipboard
    Exporter --> FileSystem
    CopyClipboard --> FileSystem

    %% Links to component mapping
    click indexHTML "https://github.com/rawgraphs/rawgraphs-app/blob/master/public/index.html"
    click manifest "https://github.com/rawgraphs/rawgraphs-app/blob/master/public/manifest.json"
    click robots "https://github.com/rawgraphs/rawgraphs-app/blob/master/public/robots.txt"
    click sampleDatasets "https://github.com/rawgraphs/rawgraphs-app/tree/master/public/sample-datasets/"
    click ReactEntry "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/index.js"
    click SW "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/serviceWorker.js"
    click WW "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/worker/index.js"
    click UploadFile "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/DataLoader/loaders/UploadFile.js"
    click UrlFetch "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/DataLoader/loaders/UrlFetch.js"
    click SparqlFetch "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/DataLoader/loaders/SparqlFetch.js"
    click Paste "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/DataLoader/loaders/Paste.js"
    click LoadProject "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/DataLoader/loaders/LoadProject.js"
    click DataLoader "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/DataLoader/DataLoader.js"
    click ChartSelector "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/ChartSelector/ChartSelector.js"
    click DataMapping "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/DataMapping/DataMapping.js"
    click ChartOptions "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/ChartOptions/ChartOptions.js"
    click ChartPreviewWithOptions "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/ChartPreviewWIthOptions/ChartPreviewWithOptions.js"
    click Exporter "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/Exporter/Exporter.js"
    click CopyClipboard "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/components/CopyToClipboardButton/CopyToClipboardButton.js"
    click ChartsJS "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/charts.js"
    click useDataLoader "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/hooks/useDataLoader.js"
    click Parser "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/hooks/useDataLoaderUtils/parser.js"
    click Stack "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/hooks/useDataLoaderUtils/stack.js"
    click useCustomCharts "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/hooks/useCustomCharts.js"
    click useWindowSize "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/hooks/useWindowSize.js"
    click useDebounce "https://github.com/rawgraphs/rawgraphs-app/blob/master/src/hooks/useDebounce.js"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef processing fill:#d4edda,stroke:#155724,color:#155724
    classDef worker fill:#fff3cd,stroke:#856404,color:#856404
    classDef static fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f1f1f1,stroke:#888,color:#333
```
