# jimzical/jyrocity architecture

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

- Interactive diagram: https://gitdiagram.com/jimzical/jyrocity
- Repository: https://github.com/jimzical/jyrocity

## Overview

1. **What this repo is**
   - A small real-time browser game built around a **Node.js server**, **Three.js** rendering in the browser, and **WebSockets** for live phone-to-game control.
   - It is not a traditional multi-page app with backend data storage; the main architecture is a **three-party interaction**: desktop browser, phone browser, and server relay.

2. **Primary runtime boundary**
   - **`server.js`** is the central backend process.
   - It likely serves the HTML pages, static JS/assets, and maintains the WebSocket channel that connects the phone controller to the game client.
   - There’s no sign of a database or external API dependency; state is probably kept in memory and is session-based.

3. **Client roles**
   - **`views/index.html`**: landing page / entry point for the desktop or host.
   - **`views/game.html`**: the actual game display, where the 3D scene runs.
   - **`views/phone.html`**: mobile controller UI, used after scanning the QR code.
   - These are distinct browser surfaces with different responsibilities rather than a single SPA.

4. **Game rendering subsystem**
   - **`public/game.js`** is the main 3D/game logic.
   - It uses **Three.js** to render the flight scene described in the README as a Wii Resort “Island Flyover” style experience.
   - The game client consumes live control input and maps it to camera motion / flight behavior.

5. **Phone controller subsystem**
   - **`public/phone.js`** handles the mobile-side input capture.
   - The README states it uses the phone’s **gyroscope** as the control source, so this file likely reads orientation/motion events and sends them over the network.
   - The phone acts like an external controller rather than rendering the game itself.

6. **QR / pairing flow**
   - **`public/qr.js`** likely generates or displays the QR code that encodes the phone URL.
   - This is the pairing boundary between the host page and the controller page.
   - The QR code is the user-facing mechanism to join the phone to the current session.

7. **Real-time data flow**
   - The control path is: **phone gyroscope input → phone browser JS → WebSocket → server → game browser JS → camera movement**.
   - This is the core architectural loop and the main reason WebSockets matter here: it needs low-latency, bidirectional updates.
   - The server likely acts as a relay/broker rather than an authoritative game engine.

8. **Static assets and 3D content**
   - The **`public/models/imaginary_city_i`** folder contains glTF assets (`scene.gltf`, `scene.bin`, textures, license), indicating the city environment is loaded as a 3D model asset package.
   - **`public/skybox`** and **`public/floor`** provide environment geometry/sky visuals.
   - These assets are loaded by the browser game client, not processed server-side.

9. **Deployment / exposure layer**
   - The project expects **ngrok** for public access, which matters because phones on another device/network need to reach the local server.
   - The batch scripts under **`scripts/`** and **`runner.bat`** automate starting the server and ngrok, suggesting a Windows-oriented developer workflow.
   - So the operational topology is local Node server tunneled to the internet for mobile access.

10. **System boundaries to diagram**
   - Separate the architecture into:
     - **Node server**: HTTP/static hosting + WebSocket coordination
     - **Desktop game browser**: Three.js scene and flight camera
     - **Phone browser**: gyroscope input UI
     - **Static asset layer**: HTML, JS, models, textures, skybox
     - **Tunnel/exposure layer**: ngrok
   - The important dependency is not a database or backend service, but the **real-time message path** between controller and game.

11. **State and synchronization**
   - The application appears to synchronize only interactive control state, not persistent gameplay state.
   - Any pairing/session state is likely transient and managed in memory by the server.
   - That makes the architecture lightweight, with the server primarily coordinating connections rather than storing content.

12. **How to think about it in one sentence**
   - This repository is a **browser-based 3D flight demo where a phone acts as a live gyro controller, connected through a Node/WebSocket relay and deployed via ngrok for cross-device access**.

Main entry points: [`server.js`](https://github.com/jimzical/jyrocity/blob/main/server.js) (Server), [`public/game.js`](https://github.com/jimzical/jyrocity/blob/main/public/game.js) (Game logic), [`runner.bat`](https://github.com/jimzical/jyrocity/blob/main/runner.bat) (Runner), [`scripts/ngrokRunner.bat`](https://github.com/jimzical/jyrocity/blob/main/scripts/ngrokRunner.bat) (Ngrok run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_server_js["Server<br/>Node.js relay<br/>[server.js]"]
end

subgraph group_browser["Browser surfaces"]
  node_index_html["Home page<br/>host page<br/>[index.html]"]
  node_game_html["Game page<br/>game view<br/>[game.html]"]
  node_phone_html["Phone page<br/>controller view<br/>[phone.html]"]
end

subgraph group_client["Client logic"]
  node_game_js["Game logic<br/>Three.js client<br/>[game.js]"]
  node_phone_js["Phone input<br/>gyro controller<br/>[phone.js]"]
  node_qr_js["QR pairing<br/>pairing UI<br/>[qr.js]"]
end

subgraph group_assets["Assets"]
  node_city_model[("City model<br/>glTF asset<br/>[scene.gltf]")]
  node_city_bin[("Model data<br/>binary mesh<br/>[scene.bin]")]
  node_city_textures["Textures<br/>texture set"]
  node_skybox["Skybox<br/>scene art"]
  node_floor["Floor<br/>scene art"]
end

subgraph group_ops["Operations"]
  node_runner_bat["Runner<br/>launch script<br/>[runner.bat]"]
  node_server_runner["Server run<br/>batch script<br/>[serverRunner.bat]"]
  node_website_runner["Website run<br/>batch script<br/>[websiteRunner.bat]"]
  node_ngrok_runner["Ngrok run<br/>batch script<br/>[ngrokRunner.bat]"]
  node_ngrok_url["Ngrok URL<br/>batch script<br/>[ngrokUrl.bat]"]
end

node_server_js -->|"serves"| node_index_html
node_server_js -->|"serves"| node_game_html
node_server_js -->|"serves"| node_phone_html
node_server_js -->|"streams"| node_game_js
node_server_js -->|"streams"| node_phone_js
node_index_html -->|"uses"| node_qr_js
node_game_html -->|"loads"| node_game_js
node_phone_html -->|"loads"| node_phone_js
node_game_js -->|"loads"| node_city_model
node_game_js -->|"loads"| node_city_bin
node_game_js -->|"loads"| node_city_textures
node_game_js -->|"uses"| node_skybox
node_game_js -->|"uses"| node_floor
node_phone_js -->|"sends input"| node_server_js
node_qr_js -->|"points to"| node_phone_html
node_runner_bat -->|"invokes"| node_server_runner
node_runner_bat -->|"invokes"| node_ngrok_runner
node_runner_bat -->|"invokes"| node_website_runner
node_ngrok_runner -->|"uses"| node_ngrok_url
node_ngrok_runner -->|"exposes"| node_server_js

click node_server_js "https://github.com/jimzical/jyrocity/blob/main/server.js"
click node_index_html "https://github.com/jimzical/jyrocity/blob/main/views/index.html"
click node_game_html "https://github.com/jimzical/jyrocity/blob/main/views/game.html"
click node_phone_html "https://github.com/jimzical/jyrocity/blob/main/views/phone.html"
click node_game_js "https://github.com/jimzical/jyrocity/blob/main/public/game.js"
click node_phone_js "https://github.com/jimzical/jyrocity/blob/main/public/phone.js"
click node_qr_js "https://github.com/jimzical/jyrocity/blob/main/public/qr.js"
click node_city_model "https://github.com/jimzical/jyrocity/blob/main/public/models/imaginary_city_i/scene.gltf"
click node_city_bin "https://github.com/jimzical/jyrocity/blob/main/public/models/imaginary_city_i/scene.bin"
click node_city_textures "https://github.com/jimzical/jyrocity/tree/main/public/models/imaginary_city_i/textures"
click node_skybox "https://github.com/jimzical/jyrocity/tree/main/public/skybox"
click node_floor "https://github.com/jimzical/jyrocity/tree/main/public/floor"
click node_runner_bat "https://github.com/jimzical/jyrocity/blob/main/runner.bat"
click node_server_runner "https://github.com/jimzical/jyrocity/blob/main/scripts/serverRunner.bat"
click node_website_runner "https://github.com/jimzical/jyrocity/blob/main/scripts/websiteRunner.bat"
click node_ngrok_runner "https://github.com/jimzical/jyrocity/blob/main/scripts/ngrokRunner.bat"
click node_ngrok_url "https://github.com/jimzical/jyrocity/blob/main/scripts/ngrokUrl.bat"

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_server_js toneBlue
class node_index_html,node_game_html,node_phone_html toneAmber
class node_game_js,node_phone_js,node_qr_js toneMint
class node_city_model,node_city_bin,node_city_textures,node_skybox,node_floor toneRose
class node_runner_bat,node_server_runner,node_website_runner,node_ngrok_runner,node_ngrok_url toneIndigo
```

## Components

### Backend

Node server and real-time session coordination

- [Server](https://github.com/jimzical/jyrocity/blob/main/server.js): Node.js relay · HTTP hosting and WebSocket coordination for paired devices · `server.js`

### Browser surfaces

Desktop host, game view, and phone controller pages

- [Home page](https://github.com/jimzical/jyrocity/blob/main/views/index.html): host page · Entry surface for the desktop host session · `views/index.html`
- [Game page](https://github.com/jimzical/jyrocity/blob/main/views/game.html): game view · Desktop browser surface that renders the 3D flight scene · `views/game.html`
- [Phone page](https://github.com/jimzical/jyrocity/blob/main/views/phone.html): controller view · Mobile browser surface used to join and steer the session · `views/phone.html`

### Client logic

Browser-side game, controller, and QR modules

- [Game logic](https://github.com/jimzical/jyrocity/blob/main/public/game.js): Three.js client · Main 3D scene, camera motion, and live control application · `public/game.js`
- [Phone input](https://github.com/jimzical/jyrocity/blob/main/public/phone.js): gyro controller · Captures motion input from the phone and sends control updates · `public/phone.js`
- [QR pairing](https://github.com/jimzical/jyrocity/blob/main/public/qr.js): pairing UI · Generates or displays the code used to connect the phone to the host · `public/qr.js`

### Assets

3D environment and static scene resources

- [City model](https://github.com/jimzical/jyrocity/blob/main/public/models/imaginary_city_i/scene.gltf): glTF asset · Imaginary city environment package loaded by the game client · `public/models/imaginary_city_i/scene.gltf`
- [Model data](https://github.com/jimzical/jyrocity/blob/main/public/models/imaginary_city_i/scene.bin): binary mesh · Mesh and geometry payload for the city environment · `public/models/imaginary_city_i/scene.bin`
- [Textures](https://github.com/jimzical/jyrocity/tree/main/public/models/imaginary_city_i/textures): texture set · Image assets for the city model surfaces · `public/models/imaginary_city_i/textures`
- [Skybox](https://github.com/jimzical/jyrocity/tree/main/public/skybox): scene art · Background sky visuals for the flight scene · `public/skybox`
- [Floor](https://github.com/jimzical/jyrocity/tree/main/public/floor): scene art · Ground or horizon geometry for the scene · `public/floor`

### Operations

Local run scripts and tunnel exposure

- [Runner](https://github.com/jimzical/jyrocity/blob/main/runner.bat): launch script · Convenience entry point for starting the local app and tunnel flow · `runner.bat`
- [Server run](https://github.com/jimzical/jyrocity/blob/main/scripts/serverRunner.bat): batch script · Starts the Node server during local development · `scripts/serverRunner.bat`
- [Website run](https://github.com/jimzical/jyrocity/blob/main/scripts/websiteRunner.bat): batch script · Starts the browser-facing website workflow · `scripts/websiteRunner.bat`
- [Ngrok run](https://github.com/jimzical/jyrocity/blob/main/scripts/ngrokRunner.bat): batch script · Starts the public tunnel used for phone access · `scripts/ngrokRunner.bat`
- [Ngrok URL](https://github.com/jimzical/jyrocity/blob/main/scripts/ngrokUrl.bat): batch script · Helper for retrieving or managing the public tunnel address · `scripts/ngrokUrl.bat`

## Connections

- Server → Home page: serves · Hosts the landing page for the desktop session
- Server → Game page: serves · Hosts the game display page
- Server → Phone page: serves · Hosts the mobile controller page
- Server → Game logic: streams · Relays control state to the game client over WebSockets
- Server → Phone input: streams · Receives controller updates from the phone client
- Home page → QR pairing: uses · The host page exposes pairing via QR code
- Game page → Game logic: loads · Bootstraps the browser game runtime
- Phone page → Phone input: loads · Bootstraps the mobile controller runtime
- Game logic → City model: loads · Imports the 3D scene model
- Game logic → Model data: loads · Uses mesh and geometry data for rendering
- Game logic → Textures: loads · Uses texture assets for the model
- Game logic → Skybox: uses · Renders the background environment
- Game logic → Floor: uses · Renders ground or horizon geometry
- Phone input → Server: sends input · Pushes gyroscope-derived control data to the relay
- QR pairing → Phone page: points to · Encodes the controller join surface
- Runner → Server run: invokes · Coordinates the development startup flow
- Runner → Ngrok run: invokes · Brings up the public tunnel for external devices
- Runner → Website run: invokes · Starts the browser-facing site workflow
- Ngrok run → Ngrok URL: uses · Resolves the tunnel address for sharing
- Ngrok run → Server: exposes · Publishes the local server to remote phones
