# shuding/cobe architecture

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

- Interactive diagram: https://gitdiagram.com/shuding/cobe
- Repository: https://github.com/shuding/cobe

## Overview

##### Project type and purpose
- This is a JavaScript/TypeScript monorepo containing:
- A lightweight WebGL “globe” rendering library (“cobe”)
- A Next.js-based static documentation & demo website
- Purpose: provide a 5 KB globe-rendering library (with shaders, texture loader, animation loop) and a site with MDX-based docs, examples, and playground.

##### File structure
- Top-level files and directories:
- package.json, pnpm-lock.yaml, pnpm-workspace.yaml – monorepo configuration
- tsconfig.json – TypeScript definitions for the library
- scripts/build.js – build script (invokes glslx, bundles shaders into JS)
- src/ – library source:
– index.js / index.d.ts – public API (createGlobe)
– shader.frag – GLSL fragment shader
– texture.js – image/texture loader
- website/ – Next.js documentation site:
– pages/ – MDX pages for docs, showcases, playground
– theme.config.js, toColor.js – site theming & utilities
– next.config.js, package.json, pnpm-lock.yaml – site build config

##### README for additional insights
- Describes public API (`createGlobe(canvas, options)`) and parameters
- Mentions external dependencies: Phenomenon (animation loop), glslx (shader transpiler), world-map asset
- Shows usage examples for React, Vue3, Svelte, vanilla JS

a. Main components
1. Build Pipeline
– scripts/build.js
– glslx (shader → JS)
– bundler (rollup/webpack via package.json scripts)
2. Library Core
– src/index.js (public API)
– shader.frag (rendering logic)
– src/texture.js (texture loader)
– Phenomenon instance (animation frame manager)
3. Package Registry
– npm (published “cobe” package)
4. Documentation Website
– Next.js frontend
– MDX content (pages/docs, showcases, playground)
– React components, theme.config, toColor.js
5. End-Users
– Any web app (React/Vue/Svelte/vanilla) importing “cobe”
6. External Assets & Services
– World map SVG (imported at build time)
– Vercel (deployment of website)

b. Relationships and interactions
– Build Pipeline produces the “cobe” package → published to npm
– Website and external consumers pull “cobe” from npm
– Consumer app calls createGlobe() → initializes WebGL context → loads texture → compiles & runs shader code → hands control to Phenomenon for animation loop
– Website build statically generates pages (Next.js SSG/SSR) embedding live globe demos

c. Architectural patterns & design principles
– Monorepo / workspace to co-locate library and docs
– Clear separation of concerns:
- Build scripts vs. library runtime
- Library core vs. website consumer
– Plugin/extension points: users supply onRender callback, markers array
– Pipeline pattern: shader transpilation → bundling → package → consumption

d. Relevant technologies & frameworks
– Node.js, pnpm workspace
– glslx (GLSL to JS transpiler)
– Phenomenon (animation manager)
– WebGL (fragment shader, texture sampling)
– Next.js + MDX (docs site)
– Vercel for hosting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        BP_Script["scripts/build.js"]:::build
        BP_gslx["glslx (Shader Transpiler)"]:::build
        BP_Bundler["Bundler (rollup/webpack)"]:::build
        BP_PkgCfg["package.json"]:::build
    end
    BP_Script -->|"transpiles shaders"| BP_gslx
    BP_Script -->|"bundles code"| BP_Bundler
    BP_Bundler -->|"uses config"| BP_PkgCfg
    BP_Bundler -->|"publishes|npm Registry"| NPM[(npm Registry)]:::external

    %% Monorepo Config
    MonorepoCfg["pnpm-workspace.yaml"]:::build
    MonorepoCfg --> BP_Script

    %% Documentation Website
    subgraph "Documentation Website"
        WS_Config["website/next.config.js"]:::website
        WS_Pkg["website/package.json"]:::website
        WS_MdxDocs["website/pages/docs"]:::website
        WS_Showcases["website/pages/docs/showcases"]:::website
        WS_Play["website/pages/playground.mdx"]:::website
        WS_Home["website/pages/index.mdx & meta.json"]:::website
        WS_Styles["website/pages/styles.css"]:::website
        WS_Theme["website/theme.config.js"]:::website
        WS_Color["website/toColor.js"]:::website
    end
    WS_Pkg -->|"installs dependencies"| NPM
    WS_Config --> WS_Pkg
    WS_Pkg -->|"imports cobe"| NPM
    WS_Pkg -->|"builds site"| WS_MdxDocs
    WS_Pkg --> WS_Showcases
    WS_Pkg --> WS_Play
    WS_Pkg --> WS_Home
    WS_Pkg --> WS_Styles
    WS_Pkg --> WS_Theme
    WS_Pkg --> WS_Color
    WS_Pkg -->|"deploys"| Vercel((Vercel)):::external

    %% Library Core Runtime
    subgraph "Library Core Runtime"
        LC_API["src/index.js (createGlobe)"]:::runtime
        LC_DTS["src/index.d.ts"]:::runtime
        LC_Shader["src/shader.frag"]:::runtime
        LC_Texture["src/texture.js"]:::runtime
        LC_Pheno["Phenomenon (Animation Loop)"]:::runtime
        WebGL["WebGL Context"]:::runtime
    end

    %% Consumer Interaction
    Consumer["External App (React/Vue/Svelte/Vanilla)"]:::external
    Consumer -->|"imports cobe"| NPM
    Consumer -->|"calls createGlobe()"| LC_API
    LC_API -->|"initializes"| WebGL
    WebGL -->|"compiles shader"| LC_Shader
    WebGL -->|"loads texture"| LC_Texture
    LC_Shader -->|"hands control"| LC_Pheno
    LC_Texture --> LC_Pheno

    %% Website Demo Embedding
    WS_MdxDocs -->|"embeds createGlobe demos"| LC_API

    %% External Assets
    MapAsset["world-map.svg"]:::external
    BP_Script -->|"includes asset"| MapAsset
    LC_Texture -->|"loads asset"| MapAsset

    %% External Services
    Vercel -->|"hosts site"| Website((Documentation Website)):::external

    %% Click Events
    click BP_Script "https://github.com/shuding/cobe/blob/main/scripts/build.js"
    click BP_PkgCfg "https://github.com/shuding/cobe/blob/main/package.json"
    click MonorepoCfg "https://github.com/shuding/cobe/blob/main/pnpm-workspace.yaml"
    click LC_API "https://github.com/shuding/cobe/blob/main/src/index.js"
    click LC_DTS "https://github.com/shuding/cobe/blob/main/src/index.d.ts"
    click LC_Shader "https://github.com/shuding/cobe/blob/main/src/shader.frag"
    click LC_Texture "https://github.com/shuding/cobe/blob/main/src/texture.js"
    click WS_Config "https://github.com/shuding/cobe/blob/main/website/next.config.js"
    click WS_Pkg "https://github.com/shuding/cobe/blob/main/website/package.json"
    click WS_MdxDocs "https://github.com/shuding/cobe/tree/main/website/pages/docs"
    click WS_Showcases "https://github.com/shuding/cobe/tree/main/website/pages/docs/showcases"
    click WS_Play "https://github.com/shuding/cobe/blob/main/website/pages/playground.mdx"
    click WS_Home "https://github.com/shuding/cobe/blob/main/website/pages/index.mdx"
    click WS_Home "https://github.com/shuding/cobe/blob/main/website/pages/meta.json"
    click WS_Styles "https://github.com/shuding/cobe/blob/main/website/pages/styles.css"
    click WS_Theme "https://github.com/shuding/cobe/blob/main/website/theme.config.js"
    click WS_Color "https://github.com/shuding/cobe/blob/main/website/toColor.js"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px
    classDef runtime fill:#bbf,stroke:#333,stroke-width:1px
    classDef website fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffd,stroke:#333,stroke-width:1px
```
