# hanshuebner/html-scrabble architecture

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

- Interactive diagram: https://gitdiagram.com/hanshuebner/html-scrabble
- Repository: https://github.com/hanshuebner/html-scrabble

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time web application.
- Frontend: static HTML/JavaScript/CSS assets under the `client/` folder implement the board UI, drag-and-drop, chat, audio cues, and game‐list pages.
- Backend: a Node.js server (`server.js`) provides HTTP endpoints, serves the static client files, manages game state, and handles real-time communication (likely via WebSockets or long polling).
- Persistence: in-memory game data flushed to disk via a simple “dirty” JSON log (see `db.js`), option to swap in Redis (`redis.js`).
- External integrations: SMTP (via nodemailer) for invitation emails, optional basic HTTP auth for the game list.

##### File Structure
- Top-level:
– `server.js`: entry point for the Node.js server
– `package.json`/`package-lock.json`: dependencies (express, nodemailer, dirty, maybe socket.io, etc.)
– `config-default.json`: default server settings (port, baseUrl, mailTransportConfig, gameListLogin).
– `db.js` & `redis.js`: persistence layers.
– `icebox.js` & `icebox-test.js`: custom lightweight test runner.
– `run.sh`, `run-tests.sh`, `makefile`: scripts for starting the server and running tests.
- `client/`:
– HTML pages (`game.html`, `games.html`, `make-game.html`)
– CSS (`common.css`, `game.css`, etc.)
– JavaScript libraries: MochiKit, jQuery, Underscore
– App logic: `game.js`, `games.js`, `make-game.js`, `ui.js`, `scrabble.js`, etc.
– Audio assets, images.
- No heavy build process, assets are served as-is.

##### Extract Architectural Patterns and Major Components
- Client-Server separation:
– Browser (UI)
– Node.js HTTP/WebSocket server
- Real-time messaging: bidirectional channel for moves and chat.
- Stateless vs. Stateful layers:
– Server holds game state in memory + logs to disk
– Persistence adapter (dirty JSON or Redis) behind a thin interface.
- External Services:
– SMTP for emails
– Optional HTTP Basic Auth protecting game list.

a. Main Components:
– Browser Client
· UI Layer: HTML/CSS/JS assets
· Game Engine: Scrabble board logic (drag/drop, tile placement, turn management)
· Chat and Notification handler
– Network Layer: HTTP (GET static, POST invites, game-list auth) + Real-time channel (WebSocket or long-polling)
– Node.js Server
· Router/HTTP server (Express or built-in)
· WebSocket/message broker (socket.io or custom)
· Game Logic module (move validation, turn rotation, scoring)
· Persistence Adapter (db.js for dirty JSON, redis.js if enabled)
· Email module (nodemailer)
– Storage
· In-memory objects
· Disk-backed JSON log (`data.db`)
· (Optional) Redis server
– External SMTP server

b. Relationships & Interactions:
1. Client loads HTML/CSS/JS over HTTP from Server.
2. Upon game creation/join, Client ↔ Server exchange via HTTP or WebSockets:
– “Create Game” request → Server stores new game state → Server responds with game key.
– “Make Move” or “Chat Message” → Server validates / broadcasts to all participants via real-time channel.
3. Server persists game events immediately to `data.db` (dirty JSON) and/or Redis.
4. Invitation flow: Server uses nodemailer → SMTP → recipient email client.
5. Optional: HTTP Basic Auth for game list URLs.

c. Architectural Patterns & Principles:
– Single server process handling both HTTP static assets and real-time messaging.
– Adapter pattern for persistence (swappable `db.js` or `redis.js`).
– Event-driven model: client actions emit events, server broadcasts events back.
– “Zero-effort deployment”: no heavyweight database server required by default.

d. Key Technologies & Libraries:
– Backend: Node.js, nodemailer, dirty (node-dirty), possibly socket.io
– Frontend: jQuery, MochiKit, Underscore, custom `scrabble.js`, CSS3 drag/drop
– Persistence: node-dirty JSON log, Redis (optional)
– Testing: custom Icebox test runner

##### Elements
- Asset delivery (HTTP GET)
- Game-move & chat messages (WebSocket)
- Persistence writes (DB adapter → JSON log/Redis)
- Email dispatch (Server → SMTP)
- Frontend components (blue)
- Backend modules (green)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Browser (Client)"
    direction TB
    GameHTML["game.html"]:::frontend
    GamesHTML["games.html"]:::frontend
    MakeGameHTML["make-game.html"]:::frontend
    CommonCSS["common.css"]:::frontend
    GameCSS["game.css"]:::frontend
    PageCSS["page.css"]:::frontend
    JQUICSS["jquery-ui.css"]:::frontend
    UIThemeCSS["ui.theme.css"]:::frontend
    MochiKit["MochiKit Lib"]:::frontend
    jQuery["jquery-1.7.2.js"]:::frontend
    Underscore["underscore.js"]:::frontend
    BrowserDetect["browserDetect.js"]:::frontend
    jQueryPlugins["jquery-*.js"]:::frontend
    ScrabbleJS["scrabble.js"]:::frontend
    GameJS["game.js"]:::frontend
    GamesJS["games.js"]:::frontend
    MakeGameJS["make-game.js"]:::frontend
    UIJS["ui.js"]:::frontend
  end

  subgraph "Node.js Server"
    direction TB
    Server["server.js"]:::backend
    Config["config-default.json"]:::backend
    Router["HTTP/WebSocket Server"]:::backend
    GameLogic["Game Logic Module"]:::backend
    PersistenceAdapter["Persistence Adapter"]:::backend
    EmailModule["Email Module"]:::backend
  end

  subgraph "Persistence"
    direction TB
    InMemory["In-memory Game State"]:::datastore
    JSONLog["Dirty JSON Log (data.db)"]:::datastore
    RedisDB["Redis (optional)"]:::datastore
  end

  External["SMTP Service"]:::external

  %% Connections
  GameHTML -->|HTTP GET| Server
  GamesHTML -->|HTTP GET| Server
  MakeGameHTML -->|HTTP GET| Server
  CommonCSS -->|HTTP GET| Server
  GameCSS -->|HTTP GET| Server
  PageCSS -->|HTTP GET| Server
  JQUICSS -->|HTTP GET| Server
  UIThemeCSS -->|HTTP GET| Server
  MochiKit -->|HTTP GET| Server
  jQuery -->|HTTP GET| Server
  Underscore -->|HTTP GET| Server
  BrowserDetect -->|HTTP GET| Server
  jQueryPlugins -->|HTTP GET| Server
  ScrabbleJS -->|WS/HTTP| Router
  GameJS -->|WS/HTTP| Router
  GamesJS -->|HTTP| Server
  MakeGameJS -->|HTTP| Server
  UIJS -->|WS/HTTP| Router

  Server -->|loads| Config
  Server -->|routes to| Router
  Router -->|calls| GameLogic
  GameLogic -->|uses| PersistenceAdapter
  PersistenceAdapter -->|writes| JSONLog
  PersistenceAdapter -->|writes| RedisDB
  PersistenceAdapter -->|holds| InMemory
  Server -->|sends email via| EmailModule
  EmailModule -->|SMTP| External

  %% Click Events
  click GameHTML "https://github.com/hanshuebner/html-scrabble/blob/master/client/game.html"
  click GamesHTML "https://github.com/hanshuebner/html-scrabble/blob/master/client/games.html"
  click MakeGameHTML "https://github.com/hanshuebner/html-scrabble/blob/master/client/make-game.html"
  click CommonCSS "https://github.com/hanshuebner/html-scrabble/blob/master/client/css/common.css"
  click GameCSS "https://github.com/hanshuebner/html-scrabble/blob/master/client/css/game.css"
  click PageCSS "https://github.com/hanshuebner/html-scrabble/blob/master/client/css/page.css"
  click JQUICSS "https://github.com/hanshuebner/html-scrabble/blob/master/client/css/jquery-ui.css"
  click UIThemeCSS "https://github.com/hanshuebner/html-scrabble/blob/master/client/css/ui.theme.css"
  click MochiKit "https://github.com/hanshuebner/html-scrabble/tree/master/client/javascript/MochiKit/"
  click jQuery "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/jquery-1.7.2.js"
  click Underscore "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/underscore.js"
  click BrowserDetect "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/browserDetect.js"
  click jQueryPlugins "https://github.com/hanshuebner/html-scrabble/tree/master/client/javascript/"
  click ScrabbleJS "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/scrabble.js"
  click GameJS "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/game.js"
  click GamesJS "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/games.js"
  click MakeGameJS "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/make-game.js"
  click UIJS "https://github.com/hanshuebner/html-scrabble/blob/master/client/javascript/ui.js"
  click Server "https://github.com/hanshuebner/html-scrabble/blob/master/server.js"
  click Config "https://github.com/hanshuebner/html-scrabble/blob/master/config-default.json"
  click PersistenceAdapter "https://github.com/hanshuebner/html-scrabble/blob/master/db.js"
  click PersistenceAdapter "https://github.com/hanshuebner/html-scrabble/blob/master/redis.js"
  click JSONLog "https://github.com/hanshuebner/html-scrabble/blob/master/data.db"
  click InMemory "https://github.com/hanshuebner/html-scrabble/blob/master/db.js"
  click RedisDB "https://github.com/hanshuebner/html-scrabble/blob/master/redis.js"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
  classDef backend fill:#DFFFE0,stroke:#28a745,color:#22863a
  classDef datastore fill:#FFEFD5,stroke:#d2691e,color:#8b4513
  classDef external fill:#F0F0F0,stroke:#6a737d,color:#586069
```
