# ncase/trust architecture

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

- Interactive diagram: https://gitdiagram.com/ncase/trust
- Repository: https://github.com/ncase/trust

## Overview

##### Project type and purpose
- This is a static, client-side, interactive educational web application (“The Evolution of Trust”).
- It uses HTML/CSS/JavaScript to present a series of slides and simulations about trust and game theory, runs entirely in the browser, and requires no backend server logic.

##### File structure
– Top level:
- index.html: the single-page entry point
- css/: site-wide styles (balloon tooltips, slide layouts)
- js/: all JavaScript, subdivided into core UI modules, third-party libraries, simulation logic, and slide definitions
- assets/: static assets (JSON data for animations/simulations, sounds, splash/tournament graphics)
- notes/ and peeps/: optional supplemental HTML and CSS for footnotes and credits
- words.html: all interactive text content
– js/core/: custom UI widgets (Buttons, Sliders, Loader, Scratcher, etc.)
– js/lib/: dependencies (Howler.js for audio, MinPubSub for events, PIXI.js indirectly via Pegasus, Q for promises)
– js/sims/: game-theory simulations (Iterated Prisoner’s Dilemma, Tournament, Sandbox UI, Splash screen)
– js/slides/: slide-by-slide definitions invoking sims and core UI

##### README for additional insights
– Describes the project as public-domain, client-side only, with no server components
– Lists all open-source libraries and assets used
– Explains translation workflow but not runtime architecture

a. Main components
1. Entry Point (index.html + words.html + CSS)
2. Core UI Module Layer (js/core): reusable widgets, layout managers, PubSub glue
3. Simulation Layer (js/sims): game-theory models and controllers
4. Slide Layer (js/slides): configuration for each interactive slide
5. Third-Party Libraries (js/lib): Howler (audio), Q (promises), MinPubSub (event bus), Pegasus (XHR), Tween.js (animations)
6. Asset Store (assets/…): JSON data, images, audio files
7. Supplemental Pages (notes/, peeps/)
b. Relationships and data flow
– Browser loads index.html → CSS and js/lib → main.js
– main.js initializes Loader (core module) → loads JSON assets (via Pegasus)
– Core modules register on MinPubSub bus → orchestrate UI updates, audio playback (Howler), animations (Tween.js)
– Simulation controllers (js/sims) publish simulation events (e.g., payoff results) → UI modules subscribe and render results
– Slide modules pick which simulation and UI combo to invoke
c. Architectural patterns and principles
– Modular JavaScript: separation into core widgets, sims, and slide configs
– Publish/Subscribe (MinPubSub) for decoupling modules
– Data-driven initialization: JSON asset files drive machine visuals, coin flips, payoffs
– Single-Page Application pattern without routing or server calls
d. Key technologies and frameworks
– HTML5/CSS3 for layout and styling (Balloon.css for tooltips)
– Vanilla JavaScript modules for application logic
– Howler.js for audio management
– Tween.js for animation timing
– MinPubSub for in-app event bus
– Q for promise management
– Pegasus for XHR-based asset loading

##### Elements
- Blue for custom modules (core, sims, slides)
- Green for third-party libraries
- Orange for static assets
– Annotation of PubSub event flows and asset requests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    subgraph "Entry Point"
        EP1["index.html"]:::entry
        EP2["words.html"]:::entry
        EP3["css/balloon.css & css/slides.css"]:::entry
    end

    %% Core UI Module Layer
    subgraph "Core UI Module Layer"
        CU1["Background.js"]:::custom
        CU2["Button.js"]:::custom
        CU3["ImageBox.js"]:::custom
        CU4["IncDecNumber.js"]:::custom
        CU5["Loader.js"]:::custom
        CU6["PayoffsUI.js"]:::custom
        CU7["Scratcher.js"]:::custom
        CU8["SlideSelect.js"]:::custom
        CU9["Slider.js"]:::custom
        CU10["Slideshow.js"]:::custom
        CU11["TextBox.js"]:::custom
        CU12["Words.js"]:::custom
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        SIM1["Iterated.js"]:::custom
        SIM2["PD.js"]:::custom
        SIM3["SandboxUI.js"]:::custom
        SIM4["Splash.js"]:::custom
        SIM5["Tournament.js"]:::custom
    end

    %% Slide Layer
    subgraph "Slide Layer"
        SL1["0_Slides_Intro.js"]:::custom
        SL2["1_Slides_OneOff.js"]:::custom
        SL3["2_Slides_Iterated.js"]:::custom
        SL4["3_Slides_Tournament.js"]:::custom
        SL5["4_Slides_Evolution.js"]:::custom
        SL6["5_Slides_Distrust.js"]:::custom
        SL7["6_Slides_Noise.js"]:::custom
        SL8["7_Slides_Sandbox.js"]:::custom
        SL9["8_Slides_Conclusion.js"]:::custom
        SL10["9_Slides_Credits.js"]:::custom
        SL11["X_Slides_Feetnotes.js"]:::custom
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libraries"
        L1["howler.js"]:::third
        L2["minpubsub.src.js"]:::third
        L3["pegasus.js"]:::third
        L4["q.js"]:::third
        L5["helpers.js"]:::third
        L6["sharing.js"]:::third
    end

    %% Asset Store
    subgraph "Asset Store"
        A1["iterated_coin.json<br>iterated_machine.json<br>iterated_payoffs.json<br>iterated_peep.json"]:::asset
        A2["connection_flower.json<br>tournament_peep.json"]:::asset
        A3["connection.json<br>splash_peep.json"]:::asset
        A4["conclusion/*"]:::asset
        A5["evolution/*"]:::asset
        A6["sounds/*.mp3"]:::asset
        A7["ui/*"]:::asset
    end

    %% Supplemental Pages
    subgraph "Supplemental Pages"
        SP1["notes/"]:::entry
        SP2["peeps/"]:::entry
    end

    %% Initialization Flow
    EP1 -->|"loads CSS & JS"| L1 & L2 & L3 & L4 & L5 & L6
    EP1 -->|"loads Core UI"| CU5
    EP1 -->|"loads Slide Configs"| SL1
    EP1 -->|"loads Assets"| A1

    %% Loader triggers asset loading via Pegasus
    CU5 -->|"requests assets via Pegasus"| L3
    L3 -->|"fetches JSON assets"| A1 & A2 & A3 & A4 & A5 & A6 & A7

    %% PubSub Event Bus
    L2["minpubsub.src.js"]:::third -->|"provides event bus"| CU1 & CU2 & CU3 & CU4 & CU6 & CU7 & CU8 & CU9 & CU10 & CU11 & CU12
    SIM1 & SIM2 & SIM3 & SIM4 & SIM5 -->|"publish simulation events"| L2
    L2 -->|"triggers UI updates"| CU6

    %% Slide modules invoking sims and UI
    SL1 & SL2 & SL3 & SL4 & SL5 & SL6 & SL7 & SL8 & SL9 & SL10 & SL11 -->|"invoke simulations"| SIM1 & SIM2 & SIM3 & SIM4 & SIM5
    SL1 & SL2 & SL3 & SL4 & SL5 & SL6 & SL7 & SL8 & SL9 & SL10 & SL11 -->|"invoke UI widgets"| CU1 & CU2 & CU3 & CU4 & CU6 & CU7 & CU8 & CU9 & CU10 & CU11 & CU12

    %% Click Events
    click EP1 "https://github.com/ncase/trust/blob/gh-pages/index.html"
    click EP2 "https://github.com/ncase/trust/blob/gh-pages/words.html"
    click EP3 "https://github.com/ncase/trust/tree/gh-pages/css/"
    click CU1 "https://github.com/ncase/trust/blob/gh-pages/js/core/Background.js"
    click CU2 "https://github.com/ncase/trust/blob/gh-pages/js/core/Button.js"
    click CU3 "https://github.com/ncase/trust/blob/gh-pages/js/core/ImageBox.js"
    click CU4 "https://github.com/ncase/trust/blob/gh-pages/js/core/IncDecNumber.js"
    click CU5 "https://github.com/ncase/trust/blob/gh-pages/js/core/Loader.js"
    click CU6 "https://github.com/ncase/trust/blob/gh-pages/js/core/PayoffsUI.js"
    click CU7 "https://github.com/ncase/trust/blob/gh-pages/js/core/Scratcher.js"
    click CU8 "https://github.com/ncase/trust/blob/gh-pages/js/core/SlideSelect.js"
    click CU9 "https://github.com/ncase/trust/blob/gh-pages/js/core/Slider.js"
    click CU10 "https://github.com/ncase/trust/blob/gh-pages/js/core/Slideshow.js"
    click CU11 "https://github.com/ncase/trust/blob/gh-pages/js/core/TextBox.js"
    click CU12 "https://github.com/ncase/trust/blob/gh-pages/js/core/Words.js"
    click SIM1 "https://github.com/ncase/trust/blob/gh-pages/js/sims/Iterated.js"
    click SIM2 "https://github.com/ncase/trust/blob/gh-pages/js/sims/PD.js"
    click SIM3 "https://github.com/ncase/trust/blob/gh-pages/js/sims/SandboxUI.js"
    click SIM4 "https://github.com/ncase/trust/blob/gh-pages/js/sims/Splash.js"
    click SIM5 "https://github.com/ncase/trust/blob/gh-pages/js/sims/Tournament.js"
    click SL1 "https://github.com/ncase/trust/blob/gh-pages/js/slides/0_Slides_Intro.js"
    click SL2 "https://github.com/ncase/trust/blob/gh-pages/js/slides/1_Slides_OneOff.js"
    click SL3 "https://github.com/ncase/trust/blob/gh-pages/js/slides/2_Slides_Iterated.js"
    click SL4 "https://github.com/ncase/trust/blob/gh-pages/js/slides/3_Slides_Tournament.js"
    click SL5 "https://github.com/ncase/trust/blob/gh-pages/js/slides/4_Slides_Evolution.js"
    click SL6 "https://github.com/ncase/trust/blob/gh-pages/js/slides/5_Slides_Distrust.js"
    click SL7 "https://github.com/ncase/trust/blob/gh-pages/js/slides/6_Slides_Noise.js"
    click SL8 "https://github.com/ncase/trust/blob/gh-pages/js/slides/7_Slides_Sandbox.js"
    click SL9 "https://github.com/ncase/trust/blob/gh-pages/js/slides/8_Slides_Conclusion.js"
    click SL10 "https://github.com/ncase/trust/blob/gh-pages/js/slides/9_Slides_Credits.js"
    click SL11 "https://github.com/ncase/trust/blob/gh-pages/js/slides/X_Slides_Feetnotes.js"
    click L1 "https://github.com/ncase/trust/blob/gh-pages/js/lib/howler.js"
    click L2 "https://github.com/ncase/trust/blob/gh-pages/js/lib/minpubsub.src.js"
    click L3 "https://github.com/ncase/trust/blob/gh-pages/js/lib/pegasus.js"
    click L4 "https://github.com/ncase/trust/blob/gh-pages/js/lib/q.js"
    click L5 "https://github.com/ncase/trust/blob/gh-pages/js/lib/helpers.js"
    click L6 "https://github.com/ncase/trust/blob/gh-pages/js/lib/sharing.js"

    %% Styles
    classDef entry fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef custom fill:#e0f7fa,stroke:#01579b,color:#01579b
    classDef third fill:#dcedc8,stroke:#33691e,color:#33691e
    classDef asset fill:#ffe0b2,stroke:#e65100,color:#e65100
```
