# steve245270533/gallery architecture

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

- Interactive diagram: https://gitdiagram.com/steve245270533/gallery
- Repository: https://github.com/steve245270533/gallery

## Overview

##### Project Type and Purpose
- This is a browser-based, single-page 3D interactive “digital gallery” demo built on Three.js and WebGL.
- It uses Blender-exported `.glb` scene files, position-based audio, custom collision detection, raycasting for interactions, and a virtual joystick for mobile.
- No backend services—fully front-end, served via Vite/PNPM, with a GitHub Actions deploy pipeline.

##### File Structure and Extract Main Components
A. Build & Deployment Layer
- package.json, pnpm-lock.yaml, tsconfig.json/node, vite.config.ts → dependency and build config
- .github/workflows/deploy.yml → CI/CD pipeline for deployment
B. Public/Static Hosting Layer
- index.html, public/ocean & public/universe → two themed build outputs with their own HTML/CSS/JS bundles
C. Application Code (src/)
1. Constants.ts → global resource URLs and event names
2. core/ → wraps Three.js primitives (Scene, Camera, Renderer)
3. loader/ → unified loader for GLB models, textures, audio
4. assets/ → raw media (audio clips, 3D models, textures)
5. environment/ → scene graph construction (floor, walls, lighting, mirror reflector)
6. character/ → avatar model, animations, movement mesh
7. controlManage/ → input abstraction (keyboard, mouse drag, virtual joystick)
8. rayCasterControls/ → raycaster logic for detecting interactions with paintings
9. ui/ + css3DRenderer/ → on-screen HUD, loading screens, detail windows, virtual joystick via CSS3DRenderer
10. audio/ → three.js positional audio source management
11. world/ → orchestrator that instantiates and ties together core, environment, character, controls, loader, UI, audio, and raycasting
12. utils/Emitter.ts → central event bus; typeAssert.ts → safety checks

##### Relationships & Data Flow
- main.ts → creates World instance
- World → calls Loader to fetch all assets → on load complete spawns Environment, Character, UI, Audio, Controls, Raycaster
- Controls emit movement events via Emitter → Character updates position → Core’s render loop re-draws scene
- RayCaster listens to pointer events → issues “object selected” events → UI displays details
- CSS3DRenderer layer overlays DOM UI elements into WebGL canvas
- Build artifacts are output to public/ocean and public/universe folders, then deployed via GitHub Actions

##### Architectural Patterns & Principles
- Modular separation by domain: core, loader, environment, character, controls, UI, audio
- Event-driven internal communication via Emitter (publish/subscribe)
- Single responsibility per module (loader only loads, controlManage only handles input)
- Orchestration layer (world/) as a composition root
- Separation between WebGL components (three.js) and DOM UI (css3DRenderer)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deploy Layer
    subgraph "Build & Deploy"
        direction TB
        PJSON["package.json"]:::build
        LOCK["pnpm-lock.yaml"]:::build
        TSC1["tsconfig.json"]:::build
        TSC2["tsconfig.node.json"]:::build
        VITE["vite.config.ts"]:::build
        CI[".github/workflows/deploy.yml"]:::build
        BUNDLER["Vite Bundler"]:::build
    end

    PJSON --> BUNDLER
    LOCK --> BUNDLER
    TSC1 --> BUNDLER
    TSC2 --> BUNDLER
    VITE --> BUNDLER
    CI --> BUNDLER

    %% Public/Static Hosting Layer
    subgraph "Public/Static Hosting"
        direction TB
        subgraph "Ocean Build Output"
            OHTML["index.html"]:::build
            OJS["app.8a40a444.js"]:::build
            OCSS["style.1e10c2a6.css"]:::build
        end
        subgraph "Universe Build Output"
            UHTML["index.html"]:::build
            UJS["app.b683c321.js"]:::build
            UCSS["style.0f63042c.css"]:::build
            UASSETS["assets/"]:::build
        end
    end

    BUNDLER --> OHTML
    BUNDLER --> OJS
    BUNDLER --> OCSS
    BUNDLER --> UHTML
    BUNDLER --> UJS
    BUNDLER --> UCSS
    BUNDLER --> UASSETS

    %% Frontend SPA Layer
    subgraph "Frontend SPA"
        direction TB

        ENTRY["src/main.ts"]:::service

        subgraph "Core Engine (Three.js)"
            Core["src/core/index.ts"]:::engine
        end

        subgraph "Asset Management"
            Loader["src/loader/index.ts"]:::service
            subgraph Assets["Assets"]
                Model1["scene_collision.glb"]:::service
                Model2["scene_desk_obj.glb"]:::service
                AudioFile["我记得.m4a"]:::service
                Boards["boards/"]:::service
            end
        end

        subgraph "Scene Composition"
            Env["src/environment/index.ts"]:::engine
            Reflector["src/lib/Reflector.ts"]:::engine
        end

        subgraph "User Representation"
            Character["src/character/index.ts"]:::domain
            Control["src/controlManage/index.ts"]:::domain
        end

        subgraph "Interaction Subsystem"
            Raycast["src/rayCasterControls/index.ts"]:::domain
            Emitter["src/utils/Emitter.ts"]:::service
            TypeAssert["src/utils/typeAssert.ts"]:::service
        end

        subgraph "UI Subsystem"
            UI["src/ui/index.ts"]:::ui
            UICSS["src/ui/ui.css"]:::ui
            CSS3D["src/css3DRenderer/index.ts"]:::ui
        end

        subgraph "Audio Subsystem"
            Audio["src/audio/index.ts"]:::domain
        end

        World["src/world/index.ts"]:::service

        %% Data / Control Flow
        ENTRY -->|boots| World
        World -->|loads assets| Loader
        Loader -->|fetches| Model1
        Loader -->|fetches| Model2
        Loader -->|fetches| AudioFile
        Loader -->|loads boards| Boards
        World --> Env
        World --> Character
        World --> Control
        World --> Raycast
        World --> UI
        World --> Audio
        World --> Core

        Control -->|emits input| Emitter
        Emitter -->|moves| Character
        Emitter -->|notifies| Raycast

        Raycast -->|select event| Emitter
        Emitter -->|show detail| UI

        Core -->|render loop| Env
        Core -->|render loop| Character
        Core -->|render loop| CSS3D
        Core -->|process audio| Audio
    end

    %% Click Events
    click PJSON "https://github.com/steve245270533/gallery/blob/master/package.json"
    click LOCK "https://github.com/steve245270533/gallery/blob/master/pnpm-lock.yaml"
    click TSC1 "https://github.com/steve245270533/gallery/blob/master/tsconfig.json"
    click TSC2 "https://github.com/steve245270533/gallery/blob/master/tsconfig.node.json"
    click VITE "https://github.com/steve245270533/gallery/blob/master/vite.config.ts"
    click CI "https://github.com/steve245270533/gallery/blob/master/.github/workflows/deploy.yml"
    click OHTML "https://github.com/steve245270533/gallery/blob/master/public/ocean/index.html"
    click OJS "https://github.com/steve245270533/gallery/blob/master/public/ocean/app.8a40a444.js"
    click OCSS "https://github.com/steve245270533/gallery/blob/master/public/ocean/style.1e10c2a6.css"
    click UHTML "https://github.com/steve245270533/gallery/blob/master/public/universe/index.html"
    click UJS "https://github.com/steve245270533/gallery/blob/master/public/universe/app.b683c321.js"
    click UCSS "https://github.com/steve245270533/gallery/blob/master/public/universe/style.0f63042c.css"
    click UASSETS "https://github.com/steve245270533/gallery/tree/master/public/universe/assets/"
    click ENTRY "https://github.com/steve245270533/gallery/blob/master/src/main.ts"
    click Core "https://github.com/steve245270533/gallery/blob/master/src/core/index.ts"
    click Loader "https://github.com/steve245270533/gallery/blob/master/src/loader/index.ts"
    click Model1 "https://github.com/steve245270533/gallery/blob/master/src/assets/models/scene_collision.glb"
    click Model2 "https://github.com/steve245270533/gallery/blob/master/src/assets/models/scene_desk_obj.glb"
    click AudioFile "https://github.com/steve245270533/gallery/blob/master/src/assets/audio/我记得.m4a"
    click Boards "https://github.com/steve245270533/gallery/tree/master/src/assets/boards/"
    click Env "https://github.com/steve245270533/gallery/blob/master/src/environment/index.ts"
    click Reflector "https://github.com/steve245270533/gallery/blob/master/src/lib/Reflector.ts"
    click Character "https://github.com/steve245270533/gallery/blob/master/src/character/index.ts"
    click Control "https://github.com/steve245270533/gallery/blob/master/src/controlManage/index.ts"
    click Raycast "https://github.com/steve245270533/gallery/blob/master/src/rayCasterControls/index.ts"
    click Emitter "https://github.com/steve245270533/gallery/blob/master/src/utils/Emitter.ts"
    click TypeAssert "https://github.com/steve245270533/gallery/blob/master/src/utils/typeAssert.ts"
    click UI "https://github.com/steve245270533/gallery/blob/master/src/ui/index.ts"
    click UICSS "https://github.com/steve245270533/gallery/blob/master/src/ui/ui.css"
    click CSS3D "https://github.com/steve245270533/gallery/blob/master/src/css3DRenderer/index.ts"
    click Audio "https://github.com/steve245270533/gallery/blob/master/src/audio/index.ts"
    click World "https://github.com/steve245270533/gallery/blob/master/src/world/index.ts"

    %% Styles
    classDef build fill:#cccccc,stroke:#333,stroke-width:1px
    classDef engine fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef domain fill:#90EE90,stroke:#333,stroke-width:1px
    classDef service fill:#FFD700,stroke:#333,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
```
