# shapediver/appbuildersdk architecture

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

- Interactive diagram: https://gitdiagram.com/shapediver/appbuildersdk
- Repository: https://github.com/shapediver/appbuildersdk

## Overview

##### Project type and purpose
- A single-page React application (SPA) implemented in TypeScript.
- Serves as the front end (“App Builder”) for ShapeDiver: it loads a JSON “skeleton” from the ShapeDiver Platform, opens a 3D session, and renders containers, tabs, widgets and elements via React components.
- Supports theming via JSON files, and can be extended with custom widgets.

##### File structure
Top level:
- Configuration (.eslintrc.json, .prettierrc.json, tsconfig.json, vite.config.ts)
- Build scripts (scripts/build-appbuilder.sh)
- Public assets (public/*.json, robots.txt, manifest.json)
- `src/` – the entire React codebase
– Entry points: AppBuilderRoot.tsx, ExampleRoot.tsx, LibraryRoot.tsx
– Components: AppBuilderBase.tsx, ExampleBase.tsx, LibraryBase.tsx
– Pages: HomePage, example pages (ModelSelectPage, ViewPage, etc.)
– Hooks: custom hooks for ShapeDiver sessions, parameters, UI
– State stores via zustand (session, viewport, parameters/export)
– Instrumentation: plausible, sentry, webvitals
- package.json / pnpm-lock.yaml – dependencies: React, Vite, Mantine, zustand, ShapeDiver viewer API

##### README for additional insights
- The app fetches a JSON “AppBuilder” data output from the ShapeDiver Platform to define its skeleton.
- Two page templates (AppShell and grid) selectable by theme property.
- Session & viewport management, parameter & export management are encapsulated in zustand stores and custom hooks.
- Theming is handled via Mantine’s theme object, overridable by passing a JSON file with the `g` query parameter.
- Analytics & error monitoring via plausible and Sentry.

A. Browser / Client (in user’s browser)
– Loads index.html + JS bundle from Static Hosting (e.g., CDN / GitHub Pages / shapediver.com)
– Parses query parameters (`slug`, `ticket`, `modelViewUrl`, `g`)
– If `g` present, fetches theme/settings JSON (from public or external URL)
– Opens a session to the ShapeDiver Platform API (using ticket or slug)
– Retrieves the “AppBuilder” skeleton JSON from the data output endpoint
– Initializes zustand stores: session store, viewport store, parameters/export store
– Instantiates React components (via AppBuilderWidgetsComponent and TemplateSelector)
– Renders 3D viewer in viewport(s) and UI widgets (parameters, exports)
– Captures analytics and errors (plausible, Sentry)
B. Static Hosting / CDNs
– Serves index.html, JS/CSS bundles, public JSON assets (example configurations, themes)
C. ShapeDiver Platform Backend
– Authentication & session management endpoints
– Data output endpoint providing skeleton JSON
– ShapeDiver 3D Viewer library (imported by SPA)
D. Build & Deployment Pipeline
– Developer machine: run `pnpm start` (Vite dev server)
– CI/CD: `pnpm build` → dist folder → `pnpm run publish` drives deployment to `latest`, `staging`, etc.
– scripts/build-appbuilder.sh for specialized builds

##### Architectural patterns & design principles
- Modular component hierarchy: Root → Base components → Widgets → UI elements
- Separation of concerns via hooks + zustand stores for state management
- Theming via external JSON and Mantine’s useProps/useTheme
- Extensibility points: skeleton type definitions + validators → new widget properties
- Single source of truth for session, viewport, parameter state

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Deployment Pipeline
    subgraph "Build & Deployment"
        scripts_build["scripts/build-appbuilder.sh"]:::pipeline
        vite_config["vite.config.ts"]:::pipeline
        tsconfig["tsconfig.json"]:::pipeline
        eslint[".eslintrc.json"]:::pipeline
        prettier[".prettierrc.json"]:::pipeline
        dev_cmd["pnpm start (Vite dev)"]:::pipeline
        build_cmd["pnpm build → dist"]:::pipeline
        deploy_cmd["pnpm run publish"]:::pipeline
    end

    %% External Services
    subgraph "External Services"
        CDN["Static Hosting / CDN"]:::external
        SDAPI["ShapeDiver API"]:::external
        SDViewer["3D Viewer Library"]:::external
        plausible["Plausible Analytics"]:::external
        sentry["Sentry Error Monitoring"]:::external
        webvitals["Web Vitals"]:::external
    end

    %% Browser / SPA
    subgraph "Browser / SPA"
        direction TB
        index_html["index.html"]:::frontend
        vite_bundle["Vite JS/CSS Bundle"]:::frontend
        AppBuilderRoot["AppBuilderRoot"]:::frontend
        ExampleRoot["ExampleRoot"]:::frontend
        LibraryRoot["LibraryRoot"]:::frontend
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        AppBuilderBase["AppBuilderBase"]:::frontend
        TemplateSelector["TemplateSelector"]:::frontend
        AppShellTemplate["AppShell/Grid Template"]:::frontend
        ExampleBase["ExampleBase"]:::frontend
        LibraryBase["LibraryBase"]:::frontend
        HomePage["HomePage"]:::frontend
        ModelSelectPage["ModelSelectPage"]:::frontend
        ViewPage["ViewPage"]:::frontend
        MultipleViewportPage["MultipleViewportPage"]:::frontend
        ExamplePage["ExamplePage"]:::frontend
        AppBuilderStaticExamplePage["AppBuilderStaticExamplePage"]:::frontend
    end

    %% Widgets Pipeline
    subgraph "Widgets Pipeline"
        direction TB
        SkeletonJSON["Skeleton JSON"]:::frontend
        AppBuilderWidgets["AppBuilderWidgetsComponent"]:::frontend
        WidgetComp["Widget Components"]:::frontend
    end

    %% State Layer
    subgraph "State Layer"
        direction TB
        SessionStore["Session Store"]:::frontend
        ViewportStore["Viewport Store"]:::frontend
        ParamsStore["Parameters/Export Store"]:::frontend
        Hooks["Custom Hooks"]:::frontend
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        ThemeFetch["Theme JSON Fetch"]:::frontend
    end

    %% Connections
    CDN --> index_html
    index_html --> vite_bundle
    vite_bundle --> AppBuilderRoot
    vite_bundle --> ExampleRoot
    vite_bundle --> LibraryRoot

    AppBuilderRoot --> AppBuilderBase
    AppBuilderRoot --> SkeletonJSON
    AppBuilderRoot --> SessionStore
    AppBuilderRoot --> ViewportStore
    AppBuilderRoot --> ParamsStore
    AppBuilderRoot --> SDAPI
    AppBuilderRoot --> SDViewer
    AppBuilderRoot --> ThemeFetch
    AppBuilderRoot --> plausible
    AppBuilderRoot --> sentry
    AppBuilderRoot --> webvitals

    AppBuilderBase --> TemplateSelector
    TemplateSelector --> AppShellTemplate

    AppBuilderBase --> AppBuilderWidgets
    AppBuilderWidgets --> WidgetComp
    AppBuilderBase --> HomePage
    AppBuilderBase --> ModelSelectPage
    AppBuilderBase --> ViewPage
    AppBuilderBase --> MultipleViewportPage
    AppBuilderBase --> ExamplePage
    AppBuilderBase --> AppBuilderStaticExamplePage

    SkeletonJSON --> AppBuilderWidgets
    AppBuilderWidgets --> WidgetComp

    SessionStore --> AppBuilderWidgets
    ViewportStore --> AppBuilderWidgets
    ParamsStore --> AppBuilderWidgets
    Hooks --> SessionStore
    Hooks --> ViewportStore
    Hooks --> ParamsStore

    ThemeFetch --> AppBuilderBase

    SDAPI --> SkeletonJSON

    %% Click Events
    click AppBuilderRoot "https://github.com/shapediver/appbuildersdk/blob/development/src/AppBuilderRoot.tsx"
    click ExampleRoot "https://github.com/shapediver/appbuildersdk/blob/development/src/ExampleRoot.tsx"
    click LibraryRoot "https://github.com/shapediver/appbuildersdk/blob/development/src/LibraryRoot.tsx"
    click AppBuilderBase "https://github.com/shapediver/appbuildersdk/blob/development/src/AppBuilderBase.tsx"
    click ExampleBase "https://github.com/shapediver/appbuildersdk/blob/development/src/ExampleBase.tsx"
    click LibraryBase "https://github.com/shapediver/appbuildersdk/blob/development/src/LibraryBase.tsx"
    click HomePage "https://github.com/shapediver/appbuildersdk/blob/development/src/pages/HomePage.tsx"
    click ModelSelectPage "https://github.com/shapediver/appbuildersdk/blob/development/src/pages/examples/ModelSelectPage.tsx"
    click ViewPage "https://github.com/shapediver/appbuildersdk/blob/development/src/pages/examples/ViewPage.tsx"
    click MultipleViewportPage "https://github.com/shapediver/appbuildersdk/blob/development/src/pages/examples/MultipleViewportPage.tsx"
    click ExamplePage "https://github.com/shapediver/appbuildersdk/blob/development/src/pages/examples/ExamplePage.tsx"
    click AppBuilderStaticExamplePage "https://github.com/shapediver/appbuildersdk/blob/development/src/pages/examples/AppBuilderStaticExamplePage.tsx"
    click Hooks "https://github.com/shapediver/appbuildersdk/tree/development/src/hooks"
    click plausible "https://github.com/shapediver/appbuildersdk/blob/development/src/instruments/plausible.ts"
    click sentry "https://github.com/shapediver/appbuildersdk/blob/development/src/instruments/sentry.ts"
    click webvitals "https://github.com/shapediver/appbuildersdk/blob/development/src/instruments/webvitals.ts"
    click CDN "https://github.com/shapediver/appbuildersdk/tree/development/public"
    click scripts_build "https://github.com/shapediver/appbuildersdk/blob/development/scripts/build-appbuilder.sh"
    click vite_config "https://github.com/shapediver/appbuildersdk/blob/development/vite.config.ts"
    click tsconfig "https://github.com/shapediver/appbuildersdk/blob/development/tsconfig.json"
    click eslint "https://github.com/shapediver/appbuildersdk/blob/development/.eslintrc.json"
    click prettier "https://github.com/shapediver/appbuildersdk/blob/development/.prettierrc.json"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#2196F3
    classDef external fill:#C8E6C9,stroke:#388E3C
    classDef pipeline fill:#E0E0E0,stroke:#757575
```
