# larryq/halloween architecture

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

- Interactive diagram: https://gitdiagram.com/larryq/halloween
- Repository: https://github.com/larryq/halloween

## Overview

##### Project type and purpose
- This is a single-page, front-end 3D web application built as a “Halloween challenge” using Three.js and React (TSX), bundled by Vite.
- Its goal is to render a spooky scene in the browser by loading and positioning GLB models (ghost, pumpkin, fish, tombstone, etc.) from the public folder.

##### File structure
- Top level:
- index.html → the static HTML entry point
- package.json, vite.config.ts → Vite configuration and scripts
- README.md, .gitignore, tsconfig*.json → documentation and TypeScript setup
- public/ → static assets (GLB models) served verbatim
- src/ → application source code
- main.tsx → React root renderer bootstrapping the app
- App.tsx + App.css → primary React component containing Three.js scene setup
- assets/ → (if any) additional local images or shaders
- theatre-project-state.json → optional animation state definitions for Theatre.js integration
- No backend, purely client-side.

##### Key insights from README
- Confirms it’s a ThreeJs-Journey challenge—focus on client-side 3D rendering.
- No external microservices or databases.

a. Main components
1. Browser & React UI Layer
2. Vite Dev/Build Server (local development & production bundling)
3. Three.js Rendering Engine
4. GLTFLoader / Asset Loader
5. Public Assets Storage (GLB files)
6. Theatre.js (optional animation manager)
b. Relationships & interactions
– Browser loads index.html → pulls in bundled JS/CSS from Vite output
– React (main.tsx → App.tsx) initializes Three.js renderer & scene
– GLTFLoader fetches each .glb model via HTTP(S) from the public folder
– Loaded models are added to the Three.js scene graph
– Theatre.js (if used) injects animation state into scene objects
– Render loop executes in browser’s requestAnimationFrame
c. Architectural patterns & principles
– SPA (Single-Page Application)
– Component-based UI (React components separate scene setup vs. UI controls)
– Module bundling & hot-reload via Vite
– Asset separation: public folder for static models, src for code
d. Relevant technologies
– React (TSX) for UI orchestration
– Three.js for WebGL 3D rendering
– Vite for fast dev server and optimized production builds
– TypeScript for type safety
– GLTFLoader (three/examples/jsm/loaders) for model loading
– Theatre.js for timeline-based animations (optional)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Environment"
        subgraph "Vite Configuration"
            VITE_CFG["vite.config.ts"]:::dev
            PKG["package.json"]:::dev
            PKGLOCK["package-lock.json"]:::dev
        end
        VITE_SERVER["Vite Dev Server"]:::dev
        VITE_CFG --> VITE_SERVER
        PKG --> VITE_SERVER
        PKGLOCK --> VITE_SERVER

        subgraph "TypeScript Configuration & Env"
            TS1["tsconfig.json"]:::config
            TS2["tsconfig.app.json"]:::config
            TS3["tsconfig.node.json"]:::config
            VENV["src/vite-env.d.ts"]:::config
        end

        README["README.md"]:::doc
        ASSETS_DIR["src/assets"]:::storage

        subgraph "Source Code"
            Main["src/main.tsx"]:::source
            AppTSX["src/App.tsx"]:::source
            AppCSS["src/App.css"]:::source
            IndexCSS["src/index.css"]:::source
            Theatre1["src/Demo Project.theatre-project-state.json"]:::source
            Theatre2["src/._Demo Project.theatre-project-state.json"]:::source
        end
    end

    VITE_SERVER -->|"bundles"| BUNDLE["bundle.js"]:::artifact

    subgraph "Browser Runtime"
        HTML["index.html"]:::entry
        ReactUI["React App"]:::runtime
        Three["Three.js Engine"]:::module
        Loader["GLTFLoader (Asset Loader)"]:::module
        Theatre["Theatre.js (Animation Manager)"]:::module
        RenderLoop["Render Loop (rAF)"]:::module
        subgraph "Public Assets Storage"
            Ghost["ghost.glb"]:::storage
            Pumpkin["pumpkin.glb"]:::storage
            Tombstone["tombstone.glb"]:::storage
            Fish["fish.glb"]:::storage
        end
    end

    BUNDLE -->|"loaded by"| HTML
    HTML -->|"bootstraps"| ReactUI
    ReactUI -->|"initializes"| Three
    Three -->|"sets up"| RenderLoop
    Three -->|"uses"| Loader
    Loader -->|"fetches via HTTP"| Ghost
    Loader -->|"fetches via HTTP"| Pumpkin
    Loader -->|"fetches via HTTP"| Tombstone
    Loader -->|"fetches via HTTP"| Fish
    ReactUI -->|"injects animations"| Theatre

    click VITE_CFG "https://github.com/larryq/halloween/blob/main/vite.config.ts"
    click PKG "https://github.com/larryq/halloween/blob/main/package.json"
    click PKGLOCK "https://github.com/larryq/halloween/blob/main/package-lock.json"
    click TS1 "https://github.com/larryq/halloween/blob/main/tsconfig.json"
    click TS2 "https://github.com/larryq/halloween/blob/main/tsconfig.app.json"
    click TS3 "https://github.com/larryq/halloween/blob/main/tsconfig.node.json"
    click VENV "https://github.com/larryq/halloween/blob/main/src/vite-env.d.ts"
    click README "https://github.com/larryq/halloween/blob/main/README.md"
    click ASSETS_DIR "https://github.com/larryq/halloween/tree/main/src/assets"
    click Main "https://github.com/larryq/halloween/blob/main/src/main.tsx"
    click AppTSX "https://github.com/larryq/halloween/blob/main/src/App.tsx"
    click AppCSS "https://github.com/larryq/halloween/blob/main/src/App.css"
    click IndexCSS "https://github.com/larryq/halloween/blob/main/src/index.css"
    click Theatre1 "https://github.com/larryq/halloween/blob/main/src/Demo Project.theatre-project-state.json"
    click Theatre2 "https://github.com/larryq/halloween/blob/main/src/._Demo Project.theatre-project-state.json"
    click Ghost "https://github.com/larryq/halloween/blob/main/public/ghost.glb"
    click Pumpkin "https://github.com/larryq/halloween/blob/main/public/pumpkin.glb"
    click Tombstone "https://github.com/larryq/halloween/blob/main/public/tombstone.glb"
    click Fish "https://github.com/larryq/halloween/blob/main/public/fish.glb"

    classDef dev fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef doc fill:#d5f5e3,stroke:#333,stroke-width:1px
    classDef storage fill:#f5b7b1,stroke:#333,stroke-width:1px
    classDef source fill:#aed6f1,stroke:#333,stroke-width:1px
    classDef artifact fill:#d7bde2,stroke:#333,stroke-width:1px
    classDef entry fill:#fadbd8,stroke:#333,stroke-width:1px
    classDef runtime fill:#d6eaf8,stroke:#333,stroke-width:1px
    classDef module fill:#a3e4d7,stroke:#333,stroke-width:1px
```
