# netmods/drapes-ui architecture

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

- Interactive diagram: https://gitdiagram.com/netmods/drapes-ui
- Repository: https://github.com/netmods/drapes-ui

## Overview

##### Project type and purpose
- This is a Next.js (React + TypeScript) “full-stack” UI library and demo site named Drapes-UI.
- It provides an interactive catalog of customizable, shader-driven canvas backgrounds, live previews, code-snippet generation, and a favorites system.
- It also includes a GitHub Action that programmatically generates and saves thumbnail images for each background.

##### File structure
- Top-level folders
– app/: Next.js App Router routes (/, /bg, /test).
– backgrounds/: One folder per background effect (config + React/TSX entry), plus two helper scripts (generate-code.ts, generate-index.ts).
– components/: Reusable UI and layout atoms/molecules (layout, navbar, palette, sliders, toggles, etc.).
– hooks/: Custom React hooks (local storage, media queries).
– lib/: Utilities (analytics, registry loader, GitHub integrations, types, helpers).
– actions/: Node script for GitHub Action (saveThumbnail.ts).
– public/: Static assets (videos, manifest, pre-generated thumbnails).
- Config and build files: next.config.ts, proxy.ts (dev proxy), tsconfig.json, postcss.config.mjs.
- Package and workspace management: package.json, pnpm-lock.yaml, pnpm-workspace.yaml.

##### README for additional insights
- Confirms the interactive preview and code-copy flows.
- Mentions zero external deps (pure canvas + WebGL).
- Describes the “favorites” system (likely persisted client-side).
- Describes the GitHub Action workflow for thumbnails.

##### Main components
a. Next.js Server / Build Pipeline
– App Router handing SSR/SSG endpoints (app/page.tsx, app/bg/page.tsx, app/test/*.tsx).
– Dynamic import via lib/registry.ts of background modules.
– Static file serving from public/.
– proxy.ts for any dev-time API proxy routes.
– GitHub Action runner that invokes actions/saveThumbnail.ts on CI.
b. Browser Client (React)
– UI components (components/ui and components/layout).
– Canvas Background Engine (dynamically loaded from backgrounds/*).
– Control Panel & Code Snippet Generator components.
– State management via hooks/use-local-storage and hook state (favorites, settings).
– Analytics events via lib/analytics.ts.
c. Background Registry & Modules
– backgrounds/registry.config.ts    ← maps effect names to config + component.
– backgrounds/*/config.ts + index.tsx defining each shader/canvas effect.
d. Persistence & Assets
– localStorage in the browser for favorites.
– public/thumbnails & public/data assets.
e. CI/CD / GitHub Action
– actions/saveThumbnail.ts runs headless to snapshot each background.
– Commits updated thumbnails back to the repo.

##### Relationships and interactions
- Browser → HTTP GET → Next.js Server → SSR/SSG pages + JSON listing (registry).
- On page load, Next.js injects the list of available backgrounds (via registry).
- User selects an effect → React loads the TSX module (code-split import) → initializes Canvas/GL.
- Control UI ↔ Canvas Engine: user changes settings → immediate re-render in the canvas.
- “Copy Code” action reads from registry + user settings → displays snippet.
- Favorites toggled → update via use-local-storage hook → persisted in browser storage.
- Analytics events fired client-side → POST to analytics endpoint (could be a 3rd-party or custom serverless function).
- On CI, GitHub Action checks out code → runs saveThumbnail.ts → uses headless Canvas to snapshot each background → updates public/thumbnails → commits.

##### Architectural patterns & design principles
- Module registry pattern for pluggable backgrounds.
- Atomic design in UI (atoms, molecules, layouts).
- Separation of concerns:
– UI logic in components/,
– Effect definitions in backgrounds/,
– Utility logic in lib/,
– Build/CI logic in actions/.
- SSR/SSG for marketing and SEO (Next.js App Router).
- Client-side hydration and code-splitting for performance.
- Hook-based state management, local persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Client
    subgraph "Browser Client"
        UI[("UI Components")]:::client
        Canvas(("Canvas Engine")):::canvas
        ControlPanel[("Control Panel & Code Snippet Generator")]:::client
        LocalStorage[(Local Storage)]:::storage
        Analytics[("Analytics Utility")]:::client
    end

    %% Server / Build Pipeline
    subgraph "Next.js Server / Build"
        Router[("App Router\n(app/page.tsx, app/bg/page.tsx,\napp/test/page.tsx, app/layout.tsx)")]:::server
        LibRegistry[("Registry Loader\nlib/registry.ts")]:::server
        Proxy[("Dev Proxy\nproxy.ts")]:::server
        Config[("Next Config\nnext.config.ts")]:::server
        PublicAssets[/"Static Assets & Thumbnails\npublic/*"/]:::assets
    end

    %% Background Modules
    subgraph "Background Modules"
        BGRegistry[("Background Registry\nbackgrounds/registry.config.ts")]:::server
        BGModules[("Background Effect Modules\nbackgrounds/*/config.ts\nbackgrounds/*/index.tsx")]:::server
        HelperScripts[("Helper Scripts\ngenerate-code.ts\ngenerate-index.ts")]:::server
    end

    %% CI/CD / GitHub Action
    subgraph "CI/CD / GitHub Action"
        Action[/"saveThumbnail.ts"/]:::ci
    end

    %% Interactions
    UI -->|"HTTP GET /, /bg"| Router
    Router -->|"import registry"| LibRegistry
    LibRegistry --> BGRegistry
    BGRegistry --> BGModules
    Router -->|"serve static"| PublicAssets
    UI -->|"dynamic import('effect')"| BGModules
    UI -->|"render"| Canvas
    ControlPanel -->|"update settings"| Canvas
    ControlPanel -->|"generate snippet"| BGRegistry
    UI -->|"toggle favorite"| LocalStorage
    UI -->|"POST analytics"| Analytics
    %% CI Flow
    Action -->|"snapshot effects"| BGModules
    Action -->|"write thumbnails"| PublicAssets

    %% Click Events
    click Router "https://github.com/netmods/drapes-ui/blob/master/app/page.tsx"
    click Router "https://github.com/netmods/drapes-ui/blob/master/app/bg/page.tsx"
    click Router "https://github.com/netmods/drapes-ui/blob/master/app/test/page.tsx"
    click Router "https://github.com/netmods/drapes-ui/blob/master/app/layout.tsx"
    click Proxy "https://github.com/netmods/drapes-ui/blob/master/proxy.ts"
    click Config "https://github.com/netmods/drapes-ui/blob/master/next.config.ts"
    click LibRegistry "https://github.com/netmods/drapes-ui/blob/master/lib/registry.ts"
    click BGRegistry "https://github.com/netmods/drapes-ui/blob/master/backgrounds/registry.config.ts"
    click HelperScripts "https://github.com/netmods/drapes-ui/blob/master/backgrounds/generate-code.ts"
    click HelperScripts "https://github.com/netmods/drapes-ui/blob/master/backgrounds/generate-index.ts"
    click UI "https://github.com/netmods/drapes-ui/tree/master/components/ui"
    click ControlPanel "https://github.com/netmods/drapes-ui/blob/master/app/bg/components/index.ts"
    click LocalStorage "https://github.com/netmods/drapes-ui/blob/master/hooks/use-local-storage.ts"
    click Analytics "https://github.com/netmods/drapes-ui/blob/master/lib/analytics.ts"
    click Action "https://github.com/netmods/drapes-ui/blob/master/actions/saveThumbnail.ts"
    click PublicAssets "https://github.com/netmods/drapes-ui/tree/master/public/thumbnails"

    %% Styles
    classDef server fill:#DCEEFB,stroke:#0366D6,stroke-width:1px
    classDef client fill:#E6FFFA,stroke:#02735E,stroke-width:1px
    classDef canvas fill:#FFF4E6,stroke:#D97706,stroke-width:1px
    classDef storage fill:#F3E8FF,stroke:#7C3AED,stroke-width:1px
    classDef assets fill:#FEF3C7,stroke:#A16207,stroke-width:1px
    classDef ci fill:#F5F5F5,stroke:#6B7280,stroke-width:1px
```
