# davidfaure/3d-text-animation-codrops architecture

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

- Interactive diagram: https://gitdiagram.com/davidfaure/3d-text-animation-codrops
- Repository: https://github.com/davidfaure/3d-text-animation-codrops

## Overview

So the “system” here is not microservices/databases; it’s a **client-side rendering + animation pipeline**:
- HTML entry page(s)
- TS modules that construct/position text elements in 3D
- Scroll listener / requestAnimationFrame loop driving transforms
- CSS providing perspective, transforms, and styling
- Build tool (Vite) bundling TS/CSS into `/dist`

- **Runtime flow** (scroll → handler → compute rotation/positions → apply DOM/CSS transforms → render)
- **Build/deploy boundary** (src → dist via Vite)

##### File structure analysis (map folders to components)
Top-level:
- `src/` → the **authoring source** (TypeScript + feature CSS)
- `src/main.ts` → likely entrypoint selecting which demo to run / wiring events
- `src/circle/*` → double-circle effect module (`circle.ts`, `circle.css`)
- `src/tube/*` → tube effect module (`tube.ts`, `tube.css`)
- `index.html`, `index2.html`, `index3.html` → three pages (very likely one per demo)
- `css/base.css` → shared styling across pages (global styles, layout)
- `dist/` → built artifacts for deployment
- `dist/assets/main-*.css` → bundled output (from src + base css)
- `vite.config.js` → build configuration (entry points, assets, base path, etc.)
- `package.json` / `tsconfig.json` → tooling configuration

Architecturally, this indicates a **feature-per-folder** approach: each animation is its own module with paired TS + CSS.

##### “Pages / Entry points”
- `index.html`
- `index2.html`
- `index3.html`
Each is an entry that loads:
- global CSS (`css/base.css`)
- bundled JS (from `src/main.ts` via Vite)
- possibly chooses which effect to initialize (by page or DOM markers)

##### “Runtime orchestrator”
- `src/main.ts`
Responsibilities to represent:
- Detect which demo is active (by URL/page, DOM attributes, or container existence)
- Attach scroll listeners and/or rAF loop
- Manage resize events (often required for 3D layouts)

##### “Effect modules” (three independent feature components)
- Build DOM text segments / spans
- On scroll: compute rotation, apply `transform: rotateY/translateZ/...`
- **Double Circle Module** (`src/circle/circle.ts`, `.css`)
- Create two circular rings
- Scroll maps to ring rotations / offsets
- **Tube Module** (`src/tube/tube.ts`, `.css`)
- Wrap text around tube-like geometry
- Scroll maps to rotation and depth illusion

##### “Rendering layer” (browser primitives)
This is critical for this project:
- DOM (elements created/updated by TS)
- CSS 3D transforms (perspective, transform-style, translateZ, rotateX/Y)
- Browser rendering pipeline (layout/paint/compositing; transforms likely GPU-accelerated)

##### “Build & bundling system”
- Vite (`vite.config.js`)
- TypeScript compilation (`tsconfig.json`)
- Output: `dist/` with bundled CSS/JS assets

This is the deployment boundary: “Source” vs “Built site”.

##### Architectural patterns / principles to highlight
Even though it’s “just a demo”, it still has clear structure:

- **Event-driven animation**: scroll input drives updates (often via throttling/rAF).
- **Declarative styling + imperative positioning**: CSS defines 3D capabilities; TS computes geometry and applies transforms.
- **Build separation**: authoring (`src`) vs distributable (`dist`).

Two big lanes:
- **Build Time (Vite)**: inputs → bundling → dist
- **Runtime (Browser)**: page → main.ts → module → DOM/CSS → render

- Scroll event
- Normalize scroll progress
- Module computes transforms (angle/radius/positions)
- Apply transforms to N text segments
- Browser renders

This captures what matters most for this project: the animation pipeline.

Optionally:
Internal steps: “create segments → position in 3D → update on scroll”.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Diagram 1: High-level Architecture (Build + Runtime)
  %% =========================================================

  subgraph "Build Time (Authoring -> Bundled Site)"
    direction TB

    subgraph "Source Inputs"
      direction TB
      P1["index.html"]:::doc
      P2["index2.html"]:::doc
      P3["index3.html"]:::doc

      BC["base.css (global styles)"]:::css

      subgraph "TypeScript Runtime Modules (src/)"
        direction TB
        MAIN["main.ts (orchestrator)"]:::ts

        subgraph "Cylinder Feature"
          direction TB
          CYTS["cylinder.ts"]:::ts
          CYCSS["cylinder.css"]:::css
        end

        subgraph "Double Circle Feature"
          direction TB
          CITS["circle.ts"]:::ts
          CICSS["circle.css"]:::css
        end

        subgraph "Tube Feature"
          direction TB
          TBTS["tube.ts"]:::ts
          TBCSS["tube.css"]:::css
        end
      end

      subgraph "Tooling Config"
        direction TB
        VCFG["vite.config.js"]:::tool
        TSCFG["tsconfig.json"]:::tool
        PKG["package.json"]:::tool
      end
    end

    VITE["Vite Build (bundle/minify/compile)"]:::tool
    DIST[("dist/ (deployable site)")]:::artifact
    OUTCSS["dist/assets/main-*.css (bundled CSS)"]:::artifact

    %% Build-time flows
    P1 -->|"entry->bundle"| VITE
    P2 -->|"entry->bundle"| VITE
    P3 -->|"entry->bundle"| VITE
    MAIN -->|"compile+bundle"| VITE
    CYTS -->|"compile+bundle"| VITE
    CITS -->|"compile+bundle"| VITE
    TBTS -->|"compile+bundle"| VITE

    BC -->|"bundle"| VITE
    CYCSS -->|"bundle"| VITE
    CICSS -->|"bundle"| VITE
    TBCSS -->|"bundle"| VITE

    VCFG -->|"configure"| VITE
    TSCFG -->|"tssettings"| VITE
    PKG -->|"scripts+deps"| VITE

    VITE -->|"emit"| DIST
    VITE -->|"emit"| OUTCSS
  end

  subgraph "Runtime (Browser Animation Pipeline)"
    direction TB

    USER["User"]:::external
    SCR["Scroll input"]:::input
    RSZ["Resize input"]:::input

    subgraph "Page Load (Entry HTML)"
      direction TB
      R_P1["index.html"]:::doc
      R_P2["index2.html"]:::doc
      R_P3["index3.html"]:::doc
      R_BC["base.css"]:::css
      BUNDLE["Bundled JS/CSS (from Vite)"]:::artifact
    end

    BROWSER["Browser Runtime"]:::platform

    subgraph "Orchestration + Feature Modules"
      direction TB
      R_MAIN["main.ts (detect demo + init + wire events)"]:::ts

      subgraph "Effects (self-contained: TS + CSS)"
        direction TB
        R_CYL["Cylinder (cylinder.ts)"]:::ts
        R_CIR["Double Circle (circle.ts)"]:::ts
        R_TUBE["Tube (tube.ts)"]:::ts

        R_CYCSS["cylinder.css"]:::css
        R_CICSS["circle.css"]:::css
        R_TBCSS["tube.css"]:::css
      end
    end

    subgraph "Rendering Layer (Platform Primitives)"
      direction TB
      DOM["DOM (text segments/elements)"]:::platform
      CSS3D["CSS 3D Transforms (perspective/rotate/translateZ)"]:::platform
      COMP["Compositor/GPU (layout/paint/composite)"]:::platform
      OUT["Visual Output (3D text scroll animation)"]:::external
    end

    %% Runtime flows
    USER -->|"interacts"| SCR
    USER -->|"interacts"| RSZ

    R_P1 -->|"loads"| BUNDLE
    R_P2 -->|"loads"| BUNDLE
    R_P3 -->|"loads"| BUNDLE
    R_P1 -->|"loads"| R_BC
    R_P2 -->|"loads"| R_BC
    R_P3 -->|"loads"| R_BC

    BUNDLE -->|"executes"| BROWSER
    BROWSER -->|"runs"| R_MAIN

    R_MAIN -->|"imports/initializes"| R_CYL
    R_MAIN -->|"imports/initializes"| R_CIR
    R_MAIN -->|"imports/initializes"| R_TUBE

    SCR -->|"scrollprogress/delta"| R_MAIN
    RSZ -->|"viewportdims"| R_MAIN

    R_MAIN -->|"bindscroll/rAF->update()"| R_CYL
    R_MAIN -->|"bindscroll/rAF->update()"| R_CIR
    R_MAIN -->|"bindscroll/rAF->update()"| R_TUBE

    R_BC -->|"sharedstyles"| DOM
    R_CYCSS -->|"featurestyles"| DOM
    R_CICSS -->|"featurestyles"| DOM
    R_TBCSS -->|"featurestyles"| DOM

    R_CYL -->|"create+positionsegments"| DOM
    R_CIR -->|"create+positionsegments"| DOM
    R_TUBE -->|"create+positionsegments"| DOM

    R_CYL -->|"writesstyle.transform/CSSvars"| CSS3D
    R_CIR -->|"writesstyle.transform/CSSvars"| CSS3D
    R_TUBE -->|"writesstyle.transform/CSSvars"| CSS3D

    DOM -->|"elements"| CSS3D
    CSS3D -->|"3Drendering"| COMP
    COMP -->|"paint/composite"| OUT
  end

  %% =========================================================
  %% Diagram 2: Runtime Sequence / Per-scroll tick data flow
  %% =========================================================
  subgraph "Per-Scroll Tick (Animation Data Flow)"
    direction TB

    INP["Scroll event / rAF tick"]:::input
    NORM["Normalize scroll -> progress"]:::ts
    PICK["main.ts selects active effect (by page/DOM markers)"]:::ts
    COMP1["Effect compute(): angle/offset/radius/phase"]:::ts
    APPLY["Apply transforms: style.transform or CSS variables"]:::ts
    RDOM["DOM nodes (N text segments)"]:::platform
    RENDER["Browser compositor renders frame"]:::platform

    INP -->|"delta/position"| NORM
    NORM -->|"progress"| PICK
    PICK -->|"call update()"| COMP1
    COMP1 -->|"transform params"| APPLY
    APPLY -->|"write to elements"| RDOM
    RDOM -->|"transform layers"| RENDER
  end

  %% =========================================================
  %% Click events (from component_mapping)
  %% =========================================================
  click P1 "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/index.html"
  click P2 "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/index2.html"
  click P3 "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/index3.html"
  click MAIN "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/main.ts"
  click CYTS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/cylinder/cylinder.ts"
  click CYCSS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/cylinder/cylinder.css"
  click CITS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/circle/circle.ts"
  click CICSS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/circle/circle.css"
  click TBTS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/tube/tube.ts"
  click TBCSS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/tube/tube.css"
  click BC "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/css/base.css"
  click VCFG "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/vite.config.js"
  click TSCFG "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/tsconfig.json"
  click PKG "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/package.json"
  click DIST "https://github.com/davidfaure/3d-text-animation-codrops/tree/master/dist/"
  click OUTCSS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/dist/assets/main-lTwiz9sR.css"
  click R_P1 "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/index.html"
  click R_P2 "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/index2.html"
  click R_P3 "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/index3.html"
  click R_MAIN "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/main.ts"
  click R_CYL "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/cylinder/cylinder.ts"
  click R_CIR "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/circle/circle.ts"
  click R_TUBE "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/tube/tube.ts"
  click R_BC "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/css/base.css"
  click R_CYCSS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/cylinder/cylinder.css"
  click R_CICSS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/circle/circle.css"
  click R_TBCSS "https://github.com/davidfaure/3d-text-animation-codrops/blob/master/src/tube/tube.css"

  %% =========================================================
  %% Styles (color + shapes)
  %% =========================================================
  classDef ts fill:#1f77b4,stroke:#0b3d91,stroke-width:1.5px,color:#ffffff
  classDef css fill:#2ca02c,stroke:#156d15,stroke-width:1.5px,color:#ffffff
  classDef tool fill:#ff7f0e,stroke:#a84f00,stroke-width:1.5px,color:#ffffff
  classDef platform fill:#9aa0a6,stroke:#5f6368,stroke-width:1.5px,color:#111111
  classDef doc fill:#e6f2ff,stroke:#3a7bd5,stroke-width:1.5px,color:#0b1f3a
  classDef artifact fill:#ffd7b5,stroke:#cc6b00,stroke-width:1.5px,color:#3b1e00
  classDef input fill:#f6d6e8,stroke:#b01264,stroke-width:1.5px,color:#3b0a22
  classDef external fill:#ffffff,stroke:#333333,stroke-width:1.5px,color:#111111
```
