# reality404studio/emotion-sculpture architecture

> Architecture diagram of the GitHub repository reality404studio/emotion-sculpture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reality404studio/emotion-sculpture
- Repository: https://github.com/reality404studio/emotion-sculpture

## Overview

#### Purpose and Entry Points
Emotion Trophy is a Vite-delivered, browser-only 3D experience that records viewer reactions during a video as a deterministic glass trophy and optionally commits its hash to Solana devnet. The HTML shell and UI start at `index.html`; application orchestration, render loop, phase transitions, and mint flow live in `src/main.js`.

#### Application Orchestrator and Phases
`src/main.js` coordinates scene setup, UI state, camera choreography, the three-minute session lifecycle, casting, completion, comparison, and minting. `src/cinematic.js` supplies camera/visual timing behavior for the foundry-to-finished-trophy presentation. `src/style.css` defines the interface layer around the WebGL scene.

Control flow is phase-oriented: enter foundry → collect emotional input into an open mould → cast automatically or on request → expose the cooled trophy and rotation interaction → optionally commit its deterministic record.

#### Input and Emotion Interpretation
`src/input.js` maps keyboard and on-screen gestures into distinct interaction semantics: rapid tapping, single taps, and holds. `src/emotions.js` converts those events into the three emotional material types and their intensity dynamics. This is an intentional boundary: gesture recognition produces emotion events; trophy generation consumes the resulting ordered material history rather than raw DOM input.

#### Deterministic Session Record
`src/session.js` owns the session data model, persistence, ordered input history, and SHA-256 sculpture hash. `src/noise.js` provides seeded deterministic placement and flow variation, avoiding `Math.random()`. The seed plus input index/history must reproduce bead placement, ribbon flow, color order, and the committed hash. `src/seed-data.js` supplies a precomputed rival session/sculpture for the comparison view.

#### Trophy Generation and Rendering
`src/trophy.js` is the visual core. During collection it creates a bounded set of temporary colored glass beads in a mould. At casting, bead records become deterministic color seeds for an internal ribbon field/texture atlas; bead meshes are removed rather than retained in the final object. A fixed trophy silhouette and physical glass rendering preserve a calm outer form while internal ribbons encode chronology, placement, clear gaps, and color quantity.

`src/atmosphere.js` provides surrounding scene ambience, while `src/polyfills.js` supports browser/runtime compatibility needed by the client bundle.

#### On-Chain Boundary
`src/onchain.js` isolates blockchain behavior behind an `OnChainAdapter`. The mock implementation supports the experience without wallet or network access. The devnet implementation generates an ephemeral keypair, requests SOL, and submits a Solana Memo transaction containing the sculpture hash and match reference, returning transaction/explorer state to the UI.

The renderer and sculpture pipeline do not depend on Solana; chain commitment is an optional post-cast persistence layer.

#### Runtime and Verification
The runtime is Vite, vanilla JavaScript, three.js/WebGL, and `@solana/web3.js`, configured by `package.json` and `vite.config.js`. The only material external services are the embedded video provider and Solana devnet RPC/Memo program. Determinism and audio behavior have dedicated executable checks in `scripts/verify-determinism.mjs` and `scripts/verify-sound.mjs`.

Main entry points: [`src/main.js`](https://github.com/reality404studio/emotion-sculpture/blob/main/src/main.js) (App orchestrator), [`src/session.js`](https://github.com/reality404studio/emotion-sculpture/blob/main/src/session.js) (Session record), [`src/trophy.js`](https://github.com/reality404studio/emotion-sculpture/blob/main/src/trophy.js) (Trophy generator), [`src/onchain.js`](https://github.com/reality404studio/emotion-sculpture/blob/main/src/onchain.js) (OnChain adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Browser Experience"]
  node_html["HTML shell<br/>entry<br/>[index.html]"]
  node_main["App orchestrator<br/>[main.js]"]
  node_ui["Interface styles<br/>stylesheet<br/>[style.css]"]
  node_cinematic["Camera choreography<br/>visual timing<br/>[cinematic.js]"]
  node_input["Gesture recognition<br/>input adapter<br/>[input.js]"]
  node_atmosphere["Scene ambience<br/>three.js scene<br/>[atmosphere.js]"]
  node_polyfills["Runtime compatibility<br/>polyfills<br/>[polyfills.js]"]
end

subgraph group_pipeline["Deterministic Trophy Pipeline"]
  node_emotions["Emotion mapping<br/>domain logic<br/>[emotions.js]"]
  node_session["Session record<br/>deterministic model<br/>[session.js]"]
  node_noise["Seeded variation<br/>deterministic utility<br/>[noise.js]"]
  node_trophy["Trophy generator<br/>three.js visual core<br/>[trophy.js]"]
  node_rival["Rival session<br/>seed data<br/>[seed-data.js]"]
end

subgraph group_chain["Optional Chain Commitment"]
  node_onchain{{"OnChain adapter<br/>blockchain boundary<br/>[onchain.js]"}}
  node_solana[("Solana devnet<br/>RPC and Memo program")]
end

node_video["Embedded video provider<br/>external media"]
node_vite["Vite client runtime<br/>build runtime<br/>[vite.config.js]"]
node_package["Dependencies<br/>package manifest<br/>[package.json]"]
node_determinism_check["Determinism check<br/>executable verification"]
node_sound_check["Sound check<br/>executable verification<br/>[verify-sound.mjs]"]

node_html -->|"starts"| node_main
node_ui -->|"styles UI"| node_main
node_vite -->|"delivers"| node_main
node_package -.->|"configures dependencies"| node_vite
node_polyfills -->|"supports runtime"| node_main
node_main -->|"captures interactions"| node_input
node_input -->|"gesture events"| node_emotions
node_emotions -->|"ordered material history"| node_session
node_session -->|"seed and history"| node_trophy
node_noise -->|"seeded placement and flow"| node_trophy
node_main -->|"collection and cast phases"| node_trophy
node_cinematic -->|"phase timing"| node_main
node_atmosphere -->|"scene ambience"| node_main
node_video -->|"session media"| node_main
node_rival -->|"comparison view"| node_main
node_session -->|"sculpture hash and match"| node_onchain
node_main -->|"optional mint request"| node_onchain
node_onchain -->|"devnet Memo transaction"| node_solana
node_determinism_check -.->|"verifies reproducibility"| node_session
node_determinism_check -.->|"verifies generated sculpture"| node_trophy
node_sound_check -.->|"verifies audio behavior"| node_main

click node_html "https://github.com/reality404studio/emotion-sculpture/blob/main/index.html"
click node_main "https://github.com/reality404studio/emotion-sculpture/blob/main/src/main.js"
click node_ui "https://github.com/reality404studio/emotion-sculpture/blob/main/src/style.css"
click node_cinematic "https://github.com/reality404studio/emotion-sculpture/blob/main/src/cinematic.js"
click node_input "https://github.com/reality404studio/emotion-sculpture/blob/main/src/input.js"
click node_emotions "https://github.com/reality404studio/emotion-sculpture/blob/main/src/emotions.js"
click node_session "https://github.com/reality404studio/emotion-sculpture/blob/main/src/session.js"
click node_noise "https://github.com/reality404studio/emotion-sculpture/blob/main/src/noise.js"
click node_trophy "https://github.com/reality404studio/emotion-sculpture/blob/main/src/trophy.js"
click node_atmosphere "https://github.com/reality404studio/emotion-sculpture/blob/main/src/atmosphere.js"
click node_rival "https://github.com/reality404studio/emotion-sculpture/blob/main/src/seed-data.js"
click node_polyfills "https://github.com/reality404studio/emotion-sculpture/blob/main/src/polyfills.js"
click node_onchain "https://github.com/reality404studio/emotion-sculpture/blob/main/src/onchain.js"
click node_vite "https://github.com/reality404studio/emotion-sculpture/blob/main/vite.config.js"
click node_package "https://github.com/reality404studio/emotion-sculpture/blob/main/package.json"
click node_determinism_check "https://github.com/reality404studio/emotion-sculpture/blob/main/scripts/verify-determinism.mjs"
click node_sound_check "https://github.com/reality404studio/emotion-sculpture/blob/main/scripts/verify-sound.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_html,node_main,node_ui,node_cinematic,node_input,node_atmosphere,node_polyfills toneBlue
class node_emotions,node_session,node_noise,node_trophy,node_rival toneAmber
class node_onchain,node_solana toneMint
class node_video,node_vite,node_package,node_determinism_check,node_sound_check toneNeutral
```

## Components

### Browser Experience

- [HTML shell](https://github.com/reality404studio/emotion-sculpture/blob/main/index.html): entry · `index.html`
- [App orchestrator](https://github.com/reality404studio/emotion-sculpture/blob/main/src/main.js): application · Owns phases, render loop, UI, casting, comparison, and minting. · `src/main.js`
- [Interface styles](https://github.com/reality404studio/emotion-sculpture/blob/main/src/style.css): stylesheet · `src/style.css`
- [Camera choreography](https://github.com/reality404studio/emotion-sculpture/blob/main/src/cinematic.js): visual timing · `src/cinematic.js`
- [Gesture recognition](https://github.com/reality404studio/emotion-sculpture/blob/main/src/input.js): input adapter · Distinguishes rapid taps, taps, and holds. · `src/input.js`
- [Scene ambience](https://github.com/reality404studio/emotion-sculpture/blob/main/src/atmosphere.js): three.js scene · `src/atmosphere.js`
- [Runtime compatibility](https://github.com/reality404studio/emotion-sculpture/blob/main/src/polyfills.js): polyfills · `src/polyfills.js`

### Deterministic Trophy Pipeline

- [Emotion mapping](https://github.com/reality404studio/emotion-sculpture/blob/main/src/emotions.js): domain logic · Converts gestures into material events and intensities. · `src/emotions.js`
- [Session record](https://github.com/reality404studio/emotion-sculpture/blob/main/src/session.js): deterministic model · Persists ordered inputs and computes the sculpture SHA-256 hash. · `src/session.js`
- [Seeded variation](https://github.com/reality404studio/emotion-sculpture/blob/main/src/noise.js): deterministic utility · Reproducible placement and flow variation without random values. · `src/noise.js`
- [Trophy generator](https://github.com/reality404studio/emotion-sculpture/blob/main/src/trophy.js): three.js visual core · Turns material history into temporary beads and final internal glass ribbons. · `src/trophy.js`
- [Rival session](https://github.com/reality404studio/emotion-sculpture/blob/main/src/seed-data.js): seed data · Precomputed comparison sculpture. · `src/seed-data.js`

### Optional Chain Commitment

- [OnChain adapter](https://github.com/reality404studio/emotion-sculpture/blob/main/src/onchain.js): blockchain boundary · Selects mock or devnet commitment without coupling rendering to Solana. · `src/onchain.js`
- **Solana devnet**: RPC and Memo program · Receives hash and match reference in a Memo transaction.

### Other components

- **Embedded video provider**: external media
- [Vite client runtime](https://github.com/reality404studio/emotion-sculpture/blob/main/vite.config.js): build runtime · `vite.config.js`
- [Dependencies](https://github.com/reality404studio/emotion-sculpture/blob/main/package.json): package manifest · Provides Vite, three.js, and Solana web3. · `package.json`
- [Determinism check](https://github.com/reality404studio/emotion-sculpture/blob/main/scripts/verify-determinism.mjs): executable verification · `scripts/verify-determinism.mjs`
- [Sound check](https://github.com/reality404studio/emotion-sculpture/blob/main/scripts/verify-sound.mjs): executable verification · `scripts/verify-sound.mjs`

## Connections

- HTML shell → App orchestrator: starts
- Interface styles → App orchestrator: styles UI
- Vite client runtime → App orchestrator: delivers
- Dependencies → Vite client runtime: configures dependencies
- Runtime compatibility → App orchestrator: supports runtime
- App orchestrator → Gesture recognition: captures interactions
- Gesture recognition → Emotion mapping: gesture events
- Emotion mapping → Session record: ordered material history
- Session record → Trophy generator: seed and history
- Seeded variation → Trophy generator: seeded placement and flow
- App orchestrator → Trophy generator: collection and cast phases
- Camera choreography → App orchestrator: phase timing
- Scene ambience → App orchestrator: scene ambience
- Embedded video provider → App orchestrator: session media
- Rival session → App orchestrator: comparison view
- Session record → OnChain adapter: sculpture hash and match
- App orchestrator → OnChain adapter: optional mint request
- OnChain adapter → Solana devnet: devnet Memo transaction
- Determinism check → Session record: verifies reproducibility
- Determinism check → Trophy generator: verifies generated sculpture
- Sound check → App orchestrator: verifies audio behavior