# tsenoner/protspace_d3 architecture

> Architecture diagram of the GitHub repository tsenoner/protspace_d3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsenoner/protspace_d3
- Repository: https://github.com/tsenoner/protspace_d3

## Overview

##### Project Type and Purpose
- ProtSpace is a monorepo (managed by Turborepo) that delivers a framework-agnostic set of web components for interactive protein‐space visualization, plus a React bridge and a Next.js demo app.

##### High-Level File Structure Analysis
- Root (monorepo)
– turbo.json, pnpm-workspace.yaml: orchestrate builds and scripts
– .changeset/: version and changelog management
– docs/: design specifications, migration guides, feature lists
– examples/: standalone Vite demos
- packages/
– react-bridge (@protspace/react): React wrappers and hooks around core components
- app/
– Next.js 14 demonstration app (uses React bridge & core)
- examples/
– scatterplot-vite: minimal Vite + core/components demo
- CI/CD and Storybook configurations

##### Key Components and Their Relationships
- Component Integration:
- React-bridge wraps core APIs and exposes hooks (useProtspaceData, onPointSelect).
- Next.js demo (app/) imports React-bridge (and through it core + utils).
- Examples import core & utils directly for framework-agnostic usage.
- Build & Dev Tools: pnpm + Turborepo handle parallel builds, caching, and filtering; Storybook serves core components in isolation.

##### Architectural Patterns & Principles
- Monorepo with clearly separated packages (core, utils, react-bridge)
- Publishable, versioned modules via Changesets
- Dependency inversion: core components depend only on utils; react-bridge depends on core; app depends on react-bridge
- Reusable, framework-agnostic design (Web Components via Lit)
- Demo and examples decoupled from core logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Tooling & CI/CD
    subgraph "Tooling & CI/CD"
        direction TB
        Turborepo["Turborepo<br/>(turbo.json)"]:::tool
        PNPM["pnpm Workspace<br/>(pnpm-workspace.yaml)"]:::tool
        Changesets["Changesets<br/>(.changeset)"]:::tool
        Storybook["Storybook"]:::tool
        Vitest["Vitest"]:::tool
        GitHub["GitHub Workflows"]:::tool
    end

    %% Monorepo Packages
    subgraph "Packages"
        direction TB
        Utils["@protspace/utils"]:::utils
        subgraph "Core Package<br/>(@protspace/core)"
            direction TB
            CoreEntry["Core Entry<br/>(src/index.ts)"]:::core
            Themes["Theming & Styles<br/>(styles/themes.ts)"]:::core
            subgraph "Components"
                direction TB
                Scatterplot["Scatterplot<br/>(scatterplot.ts)"]:::core
                Renderer["Renderer<br/>(renderer.ts)"]:::core
                Interaction["Interaction Handler<br/>(interaction-handler.ts)"]:::core
                Stories["Scatterplot Stories<br/>(scatterplot.stories.ts)"]:::core
                Legend["Legend Component<br/>(legend.ts)"]:::core
                DataLoader["Data-Loader"]:::core
            end
            StorybookCore[".storybook"]:::tool
        end
        ReactBridge["@protspace/react<br/>(React Bridge)"]:::bridge
    end

    %% Applications & Examples
    subgraph "Applications"
        direction TB
        NextApp["Next.js Demo App"]:::app
        ViteExample["Vite Example<br/>(scatterplot-vite)"]:::app
    end

    ExternalData["External Data Source<br/>(Apache Arrow files)"]:::external

    %% Relationships & Data Flow
    ExternalData -->|"arrow data"| Utils
    Utils -->|"parse() data"| DataLoader
    DataLoader -->|"render data"| Scatterplot
    DataLoader -->|"render data"| Legend

    Utils -->|"dependency"| CoreEntry
    CoreEntry --> Scatterplot
    CoreEntry --> Legend
    CoreEntry --> DataLoader
    CoreEntry --> Themes

    CoreEntry --> ReactBridge
    ReactBridge --> NextApp
    ReactBridge -->|"import via bridge"| NextApp

    CoreEntry --> ViteExample
    Utils --> ViteExample

    Turborepo -->|build/test orchestrator| Utils
    Turborepo --> CoreEntry
    Turborepo --> ReactBridge
    Turborepo --> NextApp
    Turborepo --> ViteExample

    PNPM --> Utils
    PNPM --> CoreEntry
    PNPM --> ReactBridge
    PNPM --> NextApp
    PNPM --> ViteExample

    Storybook --> CoreEntry
    Storybook --> Scatterplot
    Vitest --> Utils
    Vitest --> CoreEntry
    Changesets --> Utils
    Changesets --> CoreEntry
    Changesets --> ReactBridge

    GitHub -->|CI workflows| Turborepo
    GitHub --> PNPM
    GitHub --> Storybook
    GitHub --> Vitest

    %% Click Events
    click Utils "https://github.com/tsenoner/protspace_d3/tree/main/packages/utils"
    click Utils "https://github.com/tsenoner/protspace_d3/blob/main/packages/utils/src/index.ts"
    click Utils "https://github.com/tsenoner/protspace_d3/tree/main/packages/utils/src/visualization"
    click CoreEntry "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/src/index.ts"
    click Themes "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/src/styles/themes.ts"
    click Scatterplot "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/src/components/scatterplot/scatterplot.ts"
    click Renderer "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/src/components/scatterplot/renderer.ts"
    click Interaction "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/src/components/scatterplot/interaction-handler.ts"
    click Stories "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/src/components/scatterplot/scatterplot.stories.ts"
    click Legend "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/src/components/legend/legend.ts"
    click StorybookCore "https://github.com/tsenoner/protspace_d3/blob/main/packages/core/.storybook"
    click ReactBridge "https://github.com/tsenoner/protspace_d3/blob/main/packages/react-bridge/src/index.ts"
    click NextApp "https://github.com/tsenoner/protspace_d3/tree/main/app"
    click NextApp "https://github.com/tsenoner/protspace_d3/blob/main/app/next.config.ts"
    click NextApp "https://github.com/tsenoner/protspace_d3/blob/main/app/tsconfig.json"
    click NextApp "https://github.com/tsenoner/protspace_d3/blob/main/app/src/app/page.tsx"
    click NextApp "https://github.com/tsenoner/protspace_d3/blob/main/app/src/app/layout.tsx"
    click NextApp "https://github.com/tsenoner/protspace_d3/tree/main/app/public/data/example"
    click ViteExample "https://github.com/tsenoner/protspace_d3/tree/main/examples/scatterplot-vite"
    click ViteExample "https://github.com/tsenoner/protspace_d3/blob/main/examples/scatterplot-vite/vite.config.ts"
    click ViteExample "https://github.com/tsenoner/protspace_d3/blob/main/examples/scatterplot-vite/src/main.ts"
    click ViteExample "https://github.com/tsenoner/protspace_d3/blob/main/examples/scatterplot-vite/index.html"
    click Turborepo "https://github.com/tsenoner/protspace_d3/blob/main/turbo.json"
    click PNPM "https://github.com/tsenoner/protspace_d3/blob/main/pnpm-workspace.yaml"
    click Changesets "https://github.com/tsenoner/protspace_d3/blob/main/.changeset"
    click Storybook "https://github.com/tsenoner/protspace_d3/blob/main/package.json"
    click Vitest "https://github.com/tsenoner/protspace_d3/blob/main/vitest.config.ts"

    %% Styles
    classDef utils fill:#b3e5fc,stroke:#0288d1,color:#000
    classDef core fill:#bbdefb,stroke:#1976d2,color:#000
    classDef bridge fill:#b2dfdb,stroke:#00796b,color:#000
    classDef app fill:#ffe0b2,stroke:#ef6c00,color:#000
    classDef tool fill:#e0e0e0,stroke:#9e9e9e,color:#000
    classDef external fill:#f8bbd0,stroke:#c2185b,color:#000
```
