# pasionfruit/quackisland architecture

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

- Interactive diagram: https://gitdiagram.com/pasionfruit/quackisland
- Repository: https://github.com/pasionfruit/quackisland

## Overview

Quack Island is a browser-based 3D social island with shared lobbies and party-selected games. The main user flow is to enter the world, create or join a lobby, explore together, then follow the host into a round. The README also describes a volcano board-race foundation and Garden Goofs, whose playable rules are explicitly unfinished; the minigame catalogue is largely planned, with Zombie Tag identified as the first built game. Edges reflect documented behavior and sampled imports; several subsystem paths identify enclosing modules because their implementation was not sampled.

Main entry points: [`src/App.tsx`](https://github.com/pasionfruit/quackisland/blob/main/src/App.tsx) (Application shell), [`src/modules/10-party/index.ts`](https://github.com/pasionfruit/quackisland/blob/main/src/modules/10-party/index.ts) (Party state and games), [`src/app/World.tsx`](https://github.com/pasionfruit/quackisland/blob/main/src/app/World.tsx) (World scene), [`src/modules/09-net/index.ts`](https://github.com/pasionfruit/quackisland/blob/main/src/modules/09-net/index.ts) (Lobby networking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_world["Island world"]
  node_worldview["World scene<br/>[World.tsx]"]
  node_core["World clock and canvas<br/>[index.ts]"]
  node_terrain["Terrain and island<br/>[index.ts]"]
  node_movement["Player movement<br/>[index.ts]"]
  node_environment["Water, sky, shore<br/>[index.ts]"]
  node_footprints["Footprints<br/>[index.ts]"]
end

subgraph group_social["Lobby and party"]
  node_lobbyui["Lobby popup<br/>[LobbyPopup.tsx]"]
  node_partyui["Party controls<br/>[PartyPanel.tsx]"]
  node_party["Party state and games<br/>[index.ts]"]
  node_scoreboard["Lobby scoreboard<br/>[Scoreboard.tsx]"]
end

subgraph group_games["Games and rounds"]
  node_minigames["Minigame catalogue and rounds<br/>[index.ts]"]
  node_zombie["Zombie Tag<br/>[index.ts]"]
  node_garden["Garden Goofs<br/>[index.ts]"]
  node_volcano["Volcano board<br/>[island.ts]"]
end

subgraph group_shared["Shared runtime"]
  node_network["Lobby networking<br/>[index.ts]"]
  node_relay["WebSocket relay<br/>[relay.mjs]"]
end

subgraph group_audio["Audio and interface"]
  node_app["Application shell<br/>[App.tsx]"]
  node_music["Music player<br/>[index.ts]"]
  node_cues["Spatial sound cues<br/>[index.ts]"]
  node_settings["World settings<br/>[Settings.tsx]"]
end

node_player(("Player"))

node_player -->|"opens"| node_app
node_app -->|"renders"| node_worldview
node_app -->|"mounts canvas"| node_core
node_worldview -->|"uses world runtime"| node_core
node_worldview -->|"renders terrain"| node_terrain
node_worldview -->|"renders player"| node_movement
node_worldview -->|"renders environment"| node_environment
node_worldview -->|"renders trails"| node_footprints
node_app -->|"renders"| node_lobbyui
node_app -->|"renders"| node_partyui
node_app -->|"reads party state"| node_party
node_lobbyui -->|"creates or joins"| node_party
node_partyui -->|"selects party game"| node_party
node_party -->|"shares party state"| node_network
node_network -->|"connects by WebSocket"| node_relay
node_network -->|"reads player colour"| node_movement
node_app -->|"renders and syncs"| node_minigames
node_app -->|"renders screen"| node_garden
node_party -->|"starts selected round"| node_minigames
node_party -->|"starts selected game"| node_garden
node_minigames -->|"hosts playable game"| node_zombie
node_party -->|"provides party island"| node_volcano
node_app -->|"renders player"| node_music
node_app -->|"renders settings"| node_settings
node_app -->|"renders"| node_scoreboard
node_app -.->|"uses sound cues"| node_cues
node_network -.->|"shares nearby tracks"| node_footprints

click node_app "https://github.com/pasionfruit/quackisland/blob/main/src/App.tsx"
click node_worldview "https://github.com/pasionfruit/quackisland/blob/main/src/app/World.tsx"
click node_core "https://github.com/pasionfruit/quackisland/blob/main/src/modules/00-core/index.ts"
click node_terrain "https://github.com/pasionfruit/quackisland/blob/main/src/modules/01-terrain/index.ts"
click node_movement "https://github.com/pasionfruit/quackisland/blob/main/src/modules/02-player/index.ts"
click node_environment "https://github.com/pasionfruit/quackisland/blob/main/src/modules/04-water/index.ts"
click node_footprints "https://github.com/pasionfruit/quackisland/blob/main/src/modules/03-footprints/index.ts"
click node_lobbyui "https://github.com/pasionfruit/quackisland/blob/main/src/app/LobbyPopup.tsx"
click node_partyui "https://github.com/pasionfruit/quackisland/blob/main/src/app/PartyPanel.tsx"
click node_party "https://github.com/pasionfruit/quackisland/blob/main/src/modules/10-party/index.ts"
click node_network "https://github.com/pasionfruit/quackisland/blob/main/src/modules/09-net/index.ts"
click node_relay "https://github.com/pasionfruit/quackisland/blob/main/server/relay.mjs"
click node_minigames "https://github.com/pasionfruit/quackisland/blob/main/src/modules/15-minigames/index.ts"
click node_zombie "https://github.com/pasionfruit/quackisland/blob/main/src/modules/16-zombie-tag/index.ts"
click node_garden "https://github.com/pasionfruit/quackisland/blob/main/src/modules/14-garden/index.ts"
click node_volcano "https://github.com/pasionfruit/quackisland/blob/main/src/modules/10-party/internal/island.ts"
click node_music "https://github.com/pasionfruit/quackisland/blob/main/src/modules/05-music/index.ts"
click node_cues "https://github.com/pasionfruit/quackisland/blob/main/src/modules/08-audio/index.ts"
click node_settings "https://github.com/pasionfruit/quackisland/blob/main/src/app/Settings.tsx"
click node_scoreboard "https://github.com/pasionfruit/quackisland/blob/main/src/app/Scoreboard.tsx"

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_worldview,node_core,node_terrain,node_movement,node_environment,node_footprints toneBlue
class node_lobbyui,node_partyui,node_party,node_scoreboard toneAmber
class node_minigames,node_zombie,node_garden,node_volcano toneMint
class node_network,node_relay toneRose
class node_app,node_music,node_cues,node_settings,node_player toneIndigo
```

## Components

### Island world

- [World scene](https://github.com/pasionfruit/quackisland/blob/main/src/app/World.tsx): `src/app/World.tsx`
- [World clock and canvas](https://github.com/pasionfruit/quackisland/blob/main/src/modules/00-core/index.ts): `src/modules/00-core/index.ts`
- [Terrain and island](https://github.com/pasionfruit/quackisland/blob/main/src/modules/01-terrain/index.ts): `src/modules/01-terrain/index.ts`
- [Player movement](https://github.com/pasionfruit/quackisland/blob/main/src/modules/02-player/index.ts): `src/modules/02-player/index.ts`
- [Water, sky, shore](https://github.com/pasionfruit/quackisland/blob/main/src/modules/04-water/index.ts): `src/modules/04-water/index.ts`
- [Footprints](https://github.com/pasionfruit/quackisland/blob/main/src/modules/03-footprints/index.ts): `src/modules/03-footprints/index.ts`

### Lobby and party

- [Lobby popup](https://github.com/pasionfruit/quackisland/blob/main/src/app/LobbyPopup.tsx): `src/app/LobbyPopup.tsx`
- [Party controls](https://github.com/pasionfruit/quackisland/blob/main/src/app/PartyPanel.tsx): `src/app/PartyPanel.tsx`
- [Party state and games](https://github.com/pasionfruit/quackisland/blob/main/src/modules/10-party/index.ts): `src/modules/10-party/index.ts`
- [Lobby scoreboard](https://github.com/pasionfruit/quackisland/blob/main/src/app/Scoreboard.tsx): `src/app/Scoreboard.tsx`

### Games and rounds

- [Minigame catalogue and rounds](https://github.com/pasionfruit/quackisland/blob/main/src/modules/15-minigames/index.ts): `src/modules/15-minigames/index.ts`
- [Zombie Tag](https://github.com/pasionfruit/quackisland/blob/main/src/modules/16-zombie-tag/index.ts): `src/modules/16-zombie-tag/index.ts`
- [Garden Goofs](https://github.com/pasionfruit/quackisland/blob/main/src/modules/14-garden/index.ts): `src/modules/14-garden/index.ts`
- [Volcano board](https://github.com/pasionfruit/quackisland/blob/main/src/modules/10-party/internal/island.ts): `src/modules/10-party/internal/island.ts`

### Shared runtime

- [Lobby networking](https://github.com/pasionfruit/quackisland/blob/main/src/modules/09-net/index.ts): `src/modules/09-net/index.ts`
- [WebSocket relay](https://github.com/pasionfruit/quackisland/blob/main/server/relay.mjs): `server/relay.mjs`

### Audio and interface

- [Application shell](https://github.com/pasionfruit/quackisland/blob/main/src/App.tsx): `src/App.tsx`
- [Music player](https://github.com/pasionfruit/quackisland/blob/main/src/modules/05-music/index.ts): `src/modules/05-music/index.ts`
- [Spatial sound cues](https://github.com/pasionfruit/quackisland/blob/main/src/modules/08-audio/index.ts): `src/modules/08-audio/index.ts`
- [World settings](https://github.com/pasionfruit/quackisland/blob/main/src/app/Settings.tsx): `src/app/Settings.tsx`

### Other components

- **Player**

## Connections

- Player → Application shell: opens
- Application shell → World scene: renders
- Application shell → World clock and canvas: mounts canvas
- World scene → World clock and canvas: uses world runtime
- World scene → Terrain and island: renders terrain
- World scene → Player movement: renders player
- World scene → Water, sky, shore: renders environment
- World scene → Footprints: renders trails
- Application shell → Lobby popup: renders
- Application shell → Party controls: renders
- Application shell → Party state and games: reads party state
- Lobby popup → Party state and games: creates or joins
- Party controls → Party state and games: selects party game
- Party state and games → Lobby networking: shares party state
- Lobby networking → WebSocket relay: connects by WebSocket
- Lobby networking → Player movement: reads player colour
- Application shell → Minigame catalogue and rounds: renders and syncs
- Application shell → Garden Goofs: renders screen
- Party state and games → Minigame catalogue and rounds: starts selected round
- Party state and games → Garden Goofs: starts selected game
- Minigame catalogue and rounds → Zombie Tag: hosts playable game
- Party state and games → Volcano board: provides party island
- Application shell → Music player: renders player
- Application shell → World settings: renders settings
- Application shell → Lobby scoreboard: renders
- Application shell → Spatial sound cues: uses sound cues
- Lobby networking → Footprints: shares nearby tracks