# pranavcm24032/pykachugo_v3.4 architecture

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

- Interactive diagram: https://gitdiagram.com/pranavcm24032/pykachugo_v3.4
- Repository: https://github.com/pranavcm24032/pykachugo_v3.4

## Overview

Pykachu Go is a mobile-first, browser-based team puzzle hunt. Players register, scan or enter a start key, solve language-specific coding riddles, and follow unlocked locations through a branching puzzle graph; hints and penalties shape play, while solves and team progress sync to Google Sheets. The graph preserves the documented admin dashboard, QR scanning, meme rewards, anti-cheat monitoring, and offline PWA shell. The principal flow is documented in the README; source excerpts additionally show scanner gating, game progression, Sheets buffering, and worker caching. Unsampled subsystem links are omitted where ownership is not established.

Main entry points: [`js/game.js`](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/game.js) (Registration and Puzzles), [`index.html`](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/index.html) (Player App), [`js/google-sheets.js`](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/google-sheets.js) (Sheets Telemetry Client), [`js/data-loader.js`](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/data-loader.js) (Game Data Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_player_flow["Player Game Flow"]
  node_player_app["Player App<br/>[index.html]"]
  node_bootstrap["App Bootstrap<br/>[main.js]"]
  node_game["Registration and Puzzles<br/>[game.js]"]
  node_scanner["QR Scanner<br/>[scanner.js]"]
  node_screens["Screen Flow<br/>[screens.js]"]
  node_puzzle_data["Puzzle Graph<br/>[puzzle.json]"]
  node_team_data["Team Roster<br/>[teams.json]"]
  node_data_loader["Game Data Loader<br/>[data-loader.js]"]
  node_custom_select["Registration Selects<br/>[custom-select.js]"]
  node_camera["Device Camera"]
end

subgraph group_game_features["Game Features"]
  node_hints["Hints and Penalties<br/>[hint.js]"]
  node_penalty["Tab Penalties<br/>[penalty.js]"]
  node_security["Anti-cheat Blackout<br/>[security.js]"]
  node_meme["Meme Player<br/>[meme.js]"]
  node_meme_data["Meme Settings<br/>[meme.json]"]
  node_audio["Sound System<br/>[audio.js]"]
  node_youtube["YouTube Player API"]
end

subgraph group_state_telemetry["State and Telemetry"]
  node_local_state["Browser Game State<br/>[state.js]"]
  node_notepad["Puzzle Event Notebook<br/>[notepad.js]"]
  node_sheets_client["Sheets Telemetry Client<br/>[google-sheets.js]"]
  node_rate_limiter["Request Limiter<br/>[rate-limiter.js]"]
  node_sheets_backend["Sheets Backend"]
  node_workbook[("Google Sheets Workbook")]
  node_browser_storage[("Local Storage")]
end

subgraph group_operations["Admin and Offline"]
  node_admin["Admin Dashboard<br/>[admin.html]"]
  node_service_worker["Offline PWA Shell<br/>[service-worker.js]"]
end

node_player(("Player"))

node_player -->|"opens"| node_player_app
node_player_app -->|"runs"| node_bootstrap
node_bootstrap -->|"loads data"| node_data_loader
node_data_loader -->|"loads"| node_puzzle_data
node_data_loader -->|"loads"| node_team_data
node_data_loader -->|"loads"| node_meme_data
node_player -->|"registers"| node_game
node_game -->|"opens scanner"| node_scanner
node_camera -->|"provides video"| node_scanner
node_scanner -->|"submits code"| node_game
node_game -->|"checks progression"| node_puzzle_data
node_game -->|"shows steps"| node_screens
node_game -->|"offers hints"| node_hints
node_hints -->|"starts penalty"| node_penalty
node_game -->|"monitors play"| node_security
node_scanner -->|"opens reward"| node_meme
node_meme -->|"plays clip"| node_youtube
node_meme -->|"reads settings"| node_meme_data
node_game -->|"records events"| node_notepad
node_notepad -->|"flushes on solve"| node_sheets_client
node_game -->|"syncs team state"| node_sheets_client
node_sheets_client -->|"limits requests"| node_rate_limiter
node_sheets_client -->|"posts telemetry"| node_sheets_backend
node_sheets_backend -->|"reads and writes"| node_workbook
node_admin -->|"tracks teams"| node_workbook
node_game -->|"persists progress"| node_local_state
node_sheets_client -->|"buffers requests"| node_local_state
node_service_worker -->|"caches shell"| node_player_app
node_player_app -.->|"uses registration controls"| node_custom_select
node_player_app -.->|"plays effects"| node_audio

click node_player_app "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/index.html"
click node_bootstrap "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/main.js"
click node_game "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/game.js"
click node_scanner "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/scanner.js"
click node_screens "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/screens.js"
click node_puzzle_data "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/data/puzzle.json"
click node_team_data "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/data/teams.json"
click node_data_loader "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/data-loader.js"
click node_custom_select "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/custom-select.js"
click node_hints "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/hint.js"
click node_penalty "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/penalty.js"
click node_security "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/security.js"
click node_meme "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/meme.js"
click node_meme_data "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/data/meme.json"
click node_audio "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/audio.js"
click node_local_state "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/state.js"
click node_notepad "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/notepad.js"
click node_sheets_client "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/google-sheets.js"
click node_rate_limiter "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/rate-limiter.js"
click node_sheets_backend "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/scripts/GoogleAppsScript.gs"
click node_admin "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/admin.html"
click node_service_worker "https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/service-worker.js"

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_player_app,node_bootstrap,node_game,node_scanner,node_screens,node_puzzle_data,node_team_data,node_data_loader,node_custom_select,node_camera toneBlue
class node_hints,node_penalty,node_security,node_meme,node_meme_data,node_audio,node_youtube toneAmber
class node_local_state,node_notepad,node_sheets_client,node_rate_limiter,node_sheets_backend,node_workbook,node_browser_storage toneMint
class node_admin,node_service_worker toneRose
class node_player toneIndigo
```

## Components

### Player Game Flow

- [Player App](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/index.html): `index.html`
- [App Bootstrap](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/main.js): `js/main.js`
- [Registration and Puzzles](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/game.js): `js/game.js`
- [QR Scanner](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/scanner.js): `js/scanner.js`
- [Screen Flow](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/screens.js): `js/screens.js`
- [Puzzle Graph](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/data/puzzle.json): `data/puzzle.json`
- [Team Roster](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/data/teams.json): `data/teams.json`
- [Game Data Loader](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/data-loader.js): `js/data-loader.js`
- [Registration Selects](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/custom-select.js): `js/custom-select.js`
- **Device Camera**

### Game Features

- [Hints and Penalties](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/hint.js): `js/hint.js`
- [Tab Penalties](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/penalty.js): `js/penalty.js`
- [Anti-cheat Blackout](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/security.js): `js/security.js`
- [Meme Player](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/meme.js): `js/meme.js`
- [Meme Settings](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/data/meme.json): `data/meme.json`
- [Sound System](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/audio.js): `js/audio.js`
- **YouTube Player API**

### State and Telemetry

- [Browser Game State](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/state.js): `js/state.js`
- [Puzzle Event Notebook](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/notepad.js): `js/notepad.js`
- [Sheets Telemetry Client](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/google-sheets.js): `js/google-sheets.js`
- [Request Limiter](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/js/rate-limiter.js): `js/rate-limiter.js`
- [Sheets Backend](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/scripts/GoogleAppsScript.gs): `scripts/GoogleAppsScript.gs`
- **Google Sheets Workbook**
- **Local Storage**

### Admin and Offline

- [Admin Dashboard](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/admin.html): `admin.html`
- [Offline PWA Shell](https://github.com/pranavcm24032/pykachugo_v3.4/blob/main/service-worker.js): `service-worker.js`

### Other components

- **Player**

## Connections

- Player → Player App: opens (evidence: `README.md`)
- Player App → App Bootstrap: runs (evidence: `README.md`)
- App Bootstrap → Game Data Loader: loads data (evidence: `README.md`)
- Game Data Loader → Puzzle Graph: loads (evidence: `README.md`)
- Game Data Loader → Team Roster: loads (evidence: `README.md`)
- Game Data Loader → Meme Settings: loads (evidence: `README.md`)
- Player → Registration and Puzzles: registers (evidence: `README.md`)
- Registration and Puzzles → QR Scanner: opens scanner (evidence: `README.md`)
- Device Camera → QR Scanner: provides video (evidence: `README.md`)
- QR Scanner → Registration and Puzzles: submits code (evidence: `js/scanner.js`)
- Registration and Puzzles → Puzzle Graph: checks progression (evidence: `README.md`)
- Registration and Puzzles → Screen Flow: shows steps (evidence: `README.md`)
- Registration and Puzzles → Hints and Penalties: offers hints (evidence: `README.md`)
- Hints and Penalties → Tab Penalties: starts penalty (evidence: `README.md`)
- Registration and Puzzles → Anti-cheat Blackout: monitors play (evidence: `README.md`)
- QR Scanner → Meme Player: opens reward (evidence: `README.md`)
- Meme Player → YouTube Player API: plays clip (evidence: `README.md`)
- Meme Player → Meme Settings: reads settings (evidence: `README.md`)
- Registration and Puzzles → Puzzle Event Notebook: records events (evidence: `README.md`)
- Puzzle Event Notebook → Sheets Telemetry Client: flushes on solve (evidence: `README.md`)
- Registration and Puzzles → Sheets Telemetry Client: syncs team state (evidence: `js/game.js`)
- Sheets Telemetry Client → Request Limiter: limits requests (evidence: `js/google-sheets.js`)
- Sheets Telemetry Client → Sheets Backend: posts telemetry (evidence: `README.md`)
- Sheets Backend → Google Sheets Workbook: reads and writes (evidence: `README.md`)
- Admin Dashboard → Google Sheets Workbook: tracks teams (evidence: `README.md`)
- Registration and Puzzles → Browser Game State: persists progress (evidence: `README.md`)
- Sheets Telemetry Client → Browser Game State: buffers requests (evidence: `js/google-sheets.js`)
- Offline PWA Shell → Player App: caches shell (evidence: `service-worker.js`)
- Player App → Registration Selects: uses registration controls
- Player App → Sound System: plays effects