# aalorro/boxters architecture

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

- Interactive diagram: https://gitdiagram.com/aalorro/boxters
- Repository: https://github.com/aalorro/boxters
- Video tour (about a minute): https://gitdiagram.com/aalorro/boxters/video

## Overview

Boxters is a browser-based hex word puzzle. The player traces adjacent tiles to submit words; the game applies mode rules and objectives, scores the level, and saves progress locally with optional Firebase leaderboard and profile sync. The graph preserves the five modes, board sharing, profile transfer, and presentation/audio capabilities described in the README. Some connections rely on README or source-index references because relevant main.js sections were not excerpted; those excerpts do not establish every runtime call.

Main entry points: [`js/main.js`](https://github.com/aalorro/boxters/blob/main/js/main.js) (Game controller), [`js/levels.js`](https://github.com/aalorro/boxters/blob/main/js/levels.js) (Level generation), [`js/renderer.js`](https://github.com/aalorro/boxters/blob/main/js/renderer.js) (Canvas renderer), [`js/hex.js`](https://github.com/aalorro/boxters/blob/main/js/hex.js) (Hex geometry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Game flow"]
  node_app["Game controller<br/>[main.js]"]
  node_input["Pointer input<br/>[input.js]"]
  node_tracer["Word tracing<br/>[tracer.js]"]
end

subgraph group_rules["Board and rules"]
  node_board["Board state<br/>[board.js]"]
  node_levels["Level generation<br/>[levels.js]"]
  node_hex["Hex geometry<br/>[hex.js]"]
  node_dictionary[("Word dictionary<br/>[dictionary.js]")]
  node_boardwords["Board word list<br/>[common-words.js]"]
  node_objectives["Mode objectives<br/>[objectives.js]"]
  node_scoring["Scoring and stars<br/>[scoring.js]"]
  node_constants["Modes and settings<br/>[constants.js]"]
end

subgraph group_ui["Player experience"]
  node_renderer["Canvas renderer<br/>[renderer.js]"]
  node_particles["Visual effects<br/>[particles.js]"]
  node_audio["Sound effects<br/>[audio.js]"]
end

subgraph group_data["Progress and services"]
  node_local[("Browser storage")]
  node_firebase["Leaderboard and sync<br/>[firebase.js]"]
  node_firestore[("Firebase Firestore")]
  node_share["Shared board link<br/>[main.js]"]
  node_profile["Profile transfer<br/>[main.js]"]
end

node_player(("Player"))

node_player -->|"traces tiles"| node_input
node_input -->|"emits gestures"| node_app
node_app -->|"manages tracing"| node_tracer
node_app -->|"loads levels"| node_levels
node_levels -->|"builds boards"| node_board
node_levels -->|"uses coordinates"| node_hex
node_levels -->|"checks solvability"| node_dictionary
node_levels -->|"uses word list"| node_boardwords
node_board -->|"uses neighbors"| node_hex
node_app -->|"tracks objectives"| node_objectives
node_app -->|"calculates scores"| node_scoring
node_app -->|"updates display"| node_renderer
node_renderer -->|"maps board cells"| node_hex
node_app -->|"triggers effects"| node_particles
node_app -->|"plays sounds"| node_audio
node_renderer -->|"uses visual settings"| node_constants
node_particles -->|"uses colors"| node_constants
node_app -->|"uses game states"| node_constants
node_app -->|"persists progress"| node_local
node_app -->|"syncs profile"| node_firebase
node_firebase -->|"reads and writes"| node_firestore
node_app -->|"creates shared boards"| node_share
node_player -->|"shares board"| node_share
node_app -->|"exports and imports"| node_profile
node_player -->|"transfers progress"| node_profile

click node_app "https://github.com/aalorro/boxters/blob/main/js/main.js"
click node_input "https://github.com/aalorro/boxters/blob/main/js/input.js"
click node_tracer "https://github.com/aalorro/boxters/blob/main/js/tracer.js"
click node_board "https://github.com/aalorro/boxters/blob/main/js/board.js"
click node_levels "https://github.com/aalorro/boxters/blob/main/js/levels.js"
click node_hex "https://github.com/aalorro/boxters/blob/main/js/hex.js"
click node_dictionary "https://github.com/aalorro/boxters/blob/main/js/dictionary.js"
click node_boardwords "https://github.com/aalorro/boxters/blob/main/js/common-words.js"
click node_objectives "https://github.com/aalorro/boxters/blob/main/js/objectives.js"
click node_scoring "https://github.com/aalorro/boxters/blob/main/js/scoring.js"
click node_constants "https://github.com/aalorro/boxters/blob/main/js/constants.js"
click node_renderer "https://github.com/aalorro/boxters/blob/main/js/renderer.js"
click node_particles "https://github.com/aalorro/boxters/blob/main/js/particles.js"
click node_audio "https://github.com/aalorro/boxters/blob/main/js/audio.js"
click node_firebase "https://github.com/aalorro/boxters/blob/main/js/firebase.js"
click node_share "https://github.com/aalorro/boxters/blob/main/js/main.js"
click node_profile "https://github.com/aalorro/boxters/blob/main/js/main.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_app,node_input,node_tracer toneBlue
class node_board,node_levels,node_hex,node_dictionary,node_boardwords,node_objectives,node_scoring,node_constants toneAmber
class node_renderer,node_particles,node_audio toneMint
class node_local,node_firebase,node_firestore,node_share,node_profile toneRose
class node_player toneIndigo
```

## Components

### Game flow

- [Game controller](https://github.com/aalorro/boxters/blob/main/js/main.js): `js/main.js`
- [Pointer input](https://github.com/aalorro/boxters/blob/main/js/input.js): `js/input.js`
- [Word tracing](https://github.com/aalorro/boxters/blob/main/js/tracer.js): `js/tracer.js`

### Board and rules

- [Board state](https://github.com/aalorro/boxters/blob/main/js/board.js): `js/board.js`
- [Level generation](https://github.com/aalorro/boxters/blob/main/js/levels.js): `js/levels.js`
- [Hex geometry](https://github.com/aalorro/boxters/blob/main/js/hex.js): `js/hex.js`
- [Word dictionary](https://github.com/aalorro/boxters/blob/main/js/dictionary.js): `js/dictionary.js`
- [Board word list](https://github.com/aalorro/boxters/blob/main/js/common-words.js): `js/common-words.js`
- [Mode objectives](https://github.com/aalorro/boxters/blob/main/js/objectives.js): `js/objectives.js`
- [Scoring and stars](https://github.com/aalorro/boxters/blob/main/js/scoring.js): `js/scoring.js`
- [Modes and settings](https://github.com/aalorro/boxters/blob/main/js/constants.js): `js/constants.js`

### Player experience

- [Canvas renderer](https://github.com/aalorro/boxters/blob/main/js/renderer.js): `js/renderer.js`
- [Visual effects](https://github.com/aalorro/boxters/blob/main/js/particles.js): `js/particles.js`
- [Sound effects](https://github.com/aalorro/boxters/blob/main/js/audio.js): `js/audio.js`

### Progress and services

- **Browser storage**
- [Leaderboard and sync](https://github.com/aalorro/boxters/blob/main/js/firebase.js): `js/firebase.js`
- **Firebase Firestore**
- [Shared board link](https://github.com/aalorro/boxters/blob/main/js/main.js): `js/main.js`
- [Profile transfer](https://github.com/aalorro/boxters/blob/main/js/main.js): `js/main.js`

### Other components

- **Player**

## Connections

- Player → Pointer input: traces tiles (evidence: `README.md`)
- Pointer input → Game controller: emits gestures (evidence: `js/input.js`)
- Game controller → Word tracing: manages tracing (evidence: `js/main.js`)
- Game controller → Level generation: loads levels (evidence: `js/main.js`)
- Level generation → Board state: builds boards (evidence: `js/levels.js`)
- Level generation → Hex geometry: uses coordinates (evidence: `js/levels.js`)
- Level generation → Word dictionary: checks solvability (evidence: `js/levels.js`)
- Level generation → Board word list: uses word list (evidence: `js/levels.js`)
- Board state → Hex geometry: uses neighbors (evidence: `js/board.js`)
- Game controller → Mode objectives: tracks objectives (evidence: `js/main.js`)
- Game controller → Scoring and stars: calculates scores (evidence: `js/main.js`)
- Game controller → Canvas renderer: updates display (evidence: `js/main.js`)
- Canvas renderer → Hex geometry: maps board cells (evidence: `js/renderer.js`)
- Game controller → Visual effects: triggers effects (evidence: `js/main.js`)
- Game controller → Sound effects: plays sounds (evidence: `js/main.js`)
- Canvas renderer → Modes and settings: uses visual settings (evidence: `js/renderer.js`)
- Visual effects → Modes and settings: uses colors (evidence: `js/particles.js`)
- Game controller → Modes and settings: uses game states (evidence: `js/main.js`)
- Game controller → Browser storage: persists progress (evidence: `README.md`)
- Game controller → Leaderboard and sync: syncs profile (evidence: `js/main.js`)
- Leaderboard and sync → Firebase Firestore: reads and writes (evidence: `js/firebase.js`)
- Game controller → Shared board link: creates shared boards (evidence: `README.md`)
- Player → Shared board link: shares board (evidence: `README.md`)
- Game controller → Profile transfer: exports and imports (evidence: `README.md`)
- Player → Profile transfer: transfers progress (evidence: `README.md`)
