# importantseal/homebrew architecture

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

- Interactive diagram: https://gitdiagram.com/importantseal/homebrew
- Repository: https://github.com/importantseal/homebrew

## Overview

1. **Project shape**
   - This is a **browser-only game** with a static `index.html`, modular ES modules, and no runtime backend.
   - The main runtime layers are: **content/data**, **game logic**, **controller**, and **UI**.

2. **App entry and startup**
   - `js/app.js` is the top-level entry point.
   - It validates configured action/effect codes before gameplay starts, then hands off to the setup flow.
   - `js/setup.js` creates players and starts the game controller.

3. **Canonical game data**
   - `js/gameData.js` is the source of truth for cards, items, penalties, actions, and effects.
   - The repo strongly prefers **structured fields** on cards over text parsing, which keeps card resolution deterministic.
   - `js/logic/cardSchema.js` and `js/logic/penaltySchema.js` define the shape of those objects.

4. **Runtime state boundary**
   - `js/state.js` owns the mutable runtime state and reset behavior.
   - This is the central state object that the controller, UI, and logic modules read from and update.
   - `js/navigationGuard.js` helps prevent accidental navigation away from an active game.

5. **Core game logic**
   - `js/logic/` contains the rule engine: deck behavior, effects, penalties, item logic, randomization, and flow state.
   - `deck.js`, `effects.js`, `penalty.js`, `items.js`, and `objectCardCycle.js` model the rule primitives.
   - `flowMachine.js` plus `flowMachine.state.js`, `flowMachine.transitions.js`, `flowMachine.selectors.js`, and `flowMachine.constants.js` manage multi-step interaction state for card resolution.

6. **Game controller orchestration**
   - `js/game/controller.js` is the main orchestrator for each turn.
   - It deals cards, reacts to player input, updates state, and routes the current card into the correct resolution path.
   - `js/game/controller/helpers.js`, `effectsPanel.js`, `itemsController.js`, and `playerRemoval.js` are focused controller-side support modules.

7. **Card resolution is split into small flows**
   - `js/game/controller/cardHandlers.js` dispatches card clicks into specialized flows.
   - The flow modules separate the major outcomes:
     - `plainCardFlow.js`
     - `objectCardFlow.js`
     - `choiceFlow.js`
     - `penaltyFlow.js`
     - `penaltyFlowGroupQueue.js`
     - `penaltyFlowShare.js`
   - `guards.js` protects invalid transitions, so card interactions stay legal across modal steps and turn changes.

8. **Special actions and effect registries**
   - The `specialActionRegistry.*.js` files organize handlers by category: choice, effects, item, penalty, shared, simple, targeted, and general handlers.
   - `specialActions.js` and `specialActionSupport.js` provide shared execution logic for action/effect-driven cards.
   - This creates a clear boundary between **card data** and **how that card actually behaves**.

9. **UI layer and modal-driven interaction**
   - `js/ui/` is the rendering and interaction layer.
   - It includes dedicated components for cards, modals, dice, effects selection, items board, rules, settings, stats, timer, spin wheel, turn order, and background effects.
   - `uiFacade.js` acts as the UI integration point the controller can call without touching low-level DOM details directly.
   - CSS is similarly split by concern: layout, cards, modals, effects, history, responsive, etc.

10. **Feedback, history, and stats**
   - `js/cardHistory.js`, `js/stats.js`, and `js/statsLeaderboard.js` record gameplay outcomes and leaderboard-related data.
   - These feed the history/stats UI surfaces and support longer-running game progression across turns.
   - Sounds and visual effects live in `sounds/`, `images/`, and UI effect modules like `animations.js` and `dvdBouncer.js`.

11. **Testing and verification**
   - Tests are Node-based (`node:test`) and live in `tests/`.
   - `tests/domHarness.js` provides a lightweight DOM environment for UI-heavy tests.
   - The repo also includes repo-level verification scripts: linting, type checking of game-data contracts, import/asset verification, and test execution.

12. **Developer card injection path**
   - `js/dev/testCard.js` and related dev helpers let the game force a specific card or subcard for manual testing.
   - This is a deliberate debug boundary: it bypasses normal deck randomness so one card flow can be exercised repeatedly.

13. **Main data flow to diagram**
   - The clearest runtime path is:
     - `gameData` defines cards and actions
     - `setup` creates players
     - `state` holds the live game
     - `controller` deals turns and routes interactions
     - `logic/flowMachine` and `cardHandlers` resolve the chosen card
     - `ui` presents modals, choices, and feedback
     - `stats/history` record the result
   - That separation is the key architectural pattern in this repo.

Main entry points: [`js/game/controller.js`](https://github.com/importantseal/homebrew/blob/main/js/game/controller.js) (Controller), [`js/ui/uiFacade.js`](https://github.com/importantseal/homebrew/blob/main/js/ui/uiFacade.js) (UI facade), [`js/game/controller/cardHandlers.js`](https://github.com/importantseal/homebrew/blob/main/js/game/controller/cardHandlers.js) (Card handlers), [`js/game/controller/specialActions.js`](https://github.com/importantseal/homebrew/blob/main/js/game/controller/specialActions.js) (Special actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap & data"]
  node_js_app["App<br/>entry<br/>[app.js]"]
  node_js_setup["Setup<br/>bootstrap<br/>[setup.js]"]
  node_js_game_data[("Game data<br/>content<br/>[gameData.js]")]
  node_js_card_schema["Card schema<br/>[cardSchema.js]"]
  node_js_penalty_schema["Penalty schema<br/>[penaltySchema.js]"]
  node_js_dev_test_card["Test card<br/>dev hook<br/>[testCard.js]"]
end

subgraph group_runtime["Game logic"]
  node_js_state[("State<br/>[state.js]")]
  node_js_navigation_guard["Nav guard<br/>browser guard<br/>[navigationGuard.js]"]
  node_js_deck["Deck<br/>rule engine<br/>[deck.js]"]
  node_js_effects["Effects<br/>rules<br/>[effects.js]"]
  node_js_items["Items<br/>rules<br/>[items.js]"]
  node_js_penalty["Penalties<br/>rules<br/>[penalty.js]"]
  node_js_flow_machine{{"Flow machine<br/>fsm<br/>[flowMachine.js]"}}
  node_js_special_actions["Special actions<br/>action engine<br/>[specialActions.js]"]
end

subgraph group_controller["Orchestration"]
  node_js_controller["Controller<br/>orchestrator<br/>[controller.js]"]
  node_js_card_handlers["Card handlers<br/>router<br/>[cardHandlers.js]"]
end

subgraph group_ui["UI & feedback"]
  node_js_ui_facade["UI facade<br/>ui bridge<br/>[uiFacade.js]"]
  node_js_cards_ui["Cards UI<br/>view<br/>[cards.js]"]
  node_js_card_modal["Card modal<br/>[cardActionModal.js]"]
  node_js_effect_pick_ui["Effect picker<br/>interaction ui"]
  node_js_history["History<br/>telemetry<br/>[cardHistory.js]"]
  node_js_stats["Stats<br/>telemetry<br/>[stats.js]"]
  node_js_leaderboard["Leaderboard<br/>telemetry"]
end

node_js_app -->|"validate"| node_js_game_data
node_js_app -->|"start"| node_js_setup
node_js_setup -->|"init"| node_js_state
node_js_setup -->|"launch"| node_js_controller
node_js_game_data -->|"conforms to"| node_js_card_schema
node_js_game_data -->|"conforms to"| node_js_penalty_schema
node_js_dev_test_card -.->|"override"| node_js_game_data
node_js_controller -->|"read/write"| node_js_state
node_js_controller -->|"deal"| node_js_deck
node_js_controller -->|"route"| node_js_card_handlers
node_js_controller -->|"execute"| node_js_special_actions
node_js_controller -->|"render"| node_js_ui_facade
node_js_controller -->|"record"| node_js_history
node_js_controller -->|"update"| node_js_stats
node_js_controller -->|"protect"| node_js_navigation_guard
node_js_card_handlers -->|"advance"| node_js_flow_machine
node_js_card_handlers -->|"apply"| node_js_effects
node_js_card_handlers -->|"resolve"| node_js_penalty
node_js_card_handlers -->|"use"| node_js_items
node_js_flow_machine -->|"track"| node_js_state
node_js_special_actions -->|"dispatch"| node_js_effects
node_js_special_actions -->|"dispatch"| node_js_items
node_js_special_actions -->|"dispatch"| node_js_penalty
node_js_ui_facade -->|"compose"| node_js_cards_ui
node_js_ui_facade -->|"open"| node_js_card_modal
node_js_ui_facade -->|"choose"| node_js_effect_pick_ui
node_js_ui_facade -->|"show"| node_js_history
node_js_ui_facade -->|"show"| node_js_stats
node_js_stats -->|"aggregate"| node_js_leaderboard

click node_js_app "https://github.com/importantseal/homebrew/blob/main/js/app.js"
click node_js_setup "https://github.com/importantseal/homebrew/blob/main/js/setup.js"
click node_js_game_data "https://github.com/importantseal/homebrew/blob/main/js/gameData.js"
click node_js_card_schema "https://github.com/importantseal/homebrew/blob/main/js/logic/cardSchema.js"
click node_js_penalty_schema "https://github.com/importantseal/homebrew/blob/main/js/logic/penaltySchema.js"
click node_js_dev_test_card "https://github.com/importantseal/homebrew/blob/main/js/dev/testCard.js"
click node_js_state "https://github.com/importantseal/homebrew/blob/main/js/state.js"
click node_js_navigation_guard "https://github.com/importantseal/homebrew/blob/main/js/navigationGuard.js"
click node_js_deck "https://github.com/importantseal/homebrew/blob/main/js/logic/deck.js"
click node_js_effects "https://github.com/importantseal/homebrew/blob/main/js/logic/effects.js"
click node_js_items "https://github.com/importantseal/homebrew/blob/main/js/logic/items.js"
click node_js_penalty "https://github.com/importantseal/homebrew/blob/main/js/logic/penalty.js"
click node_js_flow_machine "https://github.com/importantseal/homebrew/blob/main/js/logic/flowMachine.js"
click node_js_special_actions "https://github.com/importantseal/homebrew/blob/main/js/game/controller/specialActions.js"
click node_js_controller "https://github.com/importantseal/homebrew/blob/main/js/game/controller.js"
click node_js_card_handlers "https://github.com/importantseal/homebrew/blob/main/js/game/controller/cardHandlers.js"
click node_js_ui_facade "https://github.com/importantseal/homebrew/blob/main/js/ui/uiFacade.js"
click node_js_cards_ui "https://github.com/importantseal/homebrew/blob/main/js/ui/cards.js"
click node_js_card_modal "https://github.com/importantseal/homebrew/blob/main/js/ui/cardActionModal.js"
click node_js_effect_pick_ui "https://github.com/importantseal/homebrew/blob/main/js/ui/effectSelectionUi.js"
click node_js_history "https://github.com/importantseal/homebrew/blob/main/js/cardHistory.js"
click node_js_stats "https://github.com/importantseal/homebrew/blob/main/js/stats.js"
click node_js_leaderboard "https://github.com/importantseal/homebrew/blob/main/js/statsLeaderboard.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_js_app,node_js_setup,node_js_game_data,node_js_card_schema,node_js_penalty_schema,node_js_dev_test_card toneBlue
class node_js_state,node_js_navigation_guard,node_js_deck,node_js_effects,node_js_items,node_js_penalty,node_js_flow_machine,node_js_special_actions toneAmber
class node_js_controller,node_js_card_handlers toneMint
class node_js_ui_facade,node_js_cards_ui,node_js_card_modal,node_js_effect_pick_ui,node_js_history,node_js_stats,node_js_leaderboard toneRose
```

## Components

### Bootstrap & data

Entry point, setup, canonical card data, and schema boundaries.

- [App](https://github.com/importantseal/homebrew/blob/main/js/app.js): entry · Browser entry point that validates configuration and starts the game. · `js/app.js`
- [Setup](https://github.com/importantseal/homebrew/blob/main/js/setup.js): bootstrap · Creates players and hands off into the controller. · `js/setup.js`
- [Game data](https://github.com/importantseal/homebrew/blob/main/js/gameData.js): content · Source of truth for cards, items, penalties, actions, and effects. · `js/gameData.js`
- [Card schema](https://github.com/importantseal/homebrew/blob/main/js/logic/cardSchema.js): schema · Defines the structured card shape used by the engine. · `js/logic/cardSchema.js`
- [Penalty schema](https://github.com/importantseal/homebrew/blob/main/js/logic/penaltySchema.js): schema · Defines the structured penalty shape used by the engine. · `js/logic/penaltySchema.js`
- [Test card](https://github.com/importantseal/homebrew/blob/main/js/dev/testCard.js): dev hook · Forces a specific card or subcard for deterministic manual testing. · `js/dev/testCard.js`

### Game logic

Mutable state and rule-engine modules that resolve gameplay.

- [State](https://github.com/importantseal/homebrew/blob/main/js/state.js): runtime state · Central mutable game state and reset behavior. · `js/state.js`
- [Nav guard](https://github.com/importantseal/homebrew/blob/main/js/navigationGuard.js): browser guard · Prevents accidental navigation away from an active game. · `js/navigationGuard.js`
- [Deck](https://github.com/importantseal/homebrew/blob/main/js/logic/deck.js): rule engine · Deck and draw behavior for gameplay flow. · `js/logic/deck.js`
- [Effects](https://github.com/importantseal/homebrew/blob/main/js/logic/effects.js): rules · Effect resolution and effect-driven game behavior. · `js/logic/effects.js`
- [Items](https://github.com/importantseal/homebrew/blob/main/js/logic/items.js): rules · Item logic and item-driven interactions. · `js/logic/items.js`
- [Penalties](https://github.com/importantseal/homebrew/blob/main/js/logic/penalty.js): rules · Penalty resolution and shared penalty behavior. · `js/logic/penalty.js`
- [Flow machine](https://github.com/importantseal/homebrew/blob/main/js/logic/flowMachine.js): fsm · Multi-step interaction state for card resolution. · `js/logic/flowMachine.js`
- [Special actions](https://github.com/importantseal/homebrew/blob/main/js/game/controller/specialActions.js): action engine · Runs structured action and effect handlers separate from card data. · `js/game/controller/specialActions.js`

### Orchestration

Turn controller and card-resolution routing.

- [Controller](https://github.com/importantseal/homebrew/blob/main/js/game/controller.js): orchestrator · Main per-turn orchestrator that deals cards and routes resolution. · `js/game/controller.js`
- [Card handlers](https://github.com/importantseal/homebrew/blob/main/js/game/controller/cardHandlers.js): router · Dispatches card clicks into specialized resolution flows. · `js/game/controller/cardHandlers.js`

### UI & feedback

Rendering, interaction surfaces, history, and stats.

- [UI facade](https://github.com/importantseal/homebrew/blob/main/js/ui/uiFacade.js): ui bridge · Integration point for controller-driven UI updates. · `js/ui/uiFacade.js`
- [Cards UI](https://github.com/importantseal/homebrew/blob/main/js/ui/cards.js): view · Card rendering and card-centric interaction surfaces. · `js/ui/cards.js`
- [Card modal](https://github.com/importantseal/homebrew/blob/main/js/ui/cardActionModal.js): modal · Primary modal used for card choices and resolution steps. · `js/ui/cardActionModal.js`
- [Effect picker](https://github.com/importantseal/homebrew/blob/main/js/ui/effectSelectionUi.js): interaction ui · UI for selecting effects during gameplay. · `js/ui/effectSelectionUi.js`
- [History](https://github.com/importantseal/homebrew/blob/main/js/cardHistory.js): telemetry · Records gameplay outcomes and turn history. · `js/cardHistory.js`
- [Stats](https://github.com/importantseal/homebrew/blob/main/js/stats.js): telemetry · Tracks game stats across play sessions. · `js/stats.js`
- [Leaderboard](https://github.com/importantseal/homebrew/blob/main/js/statsLeaderboard.js): telemetry · Aggregates leaderboard-oriented stats. · `js/statsLeaderboard.js`

## Connections

- App → Game data: validate · App checks configured action/effect codes before play starts.
- App → Setup: start · App hands off startup to setup.
- Setup → State: init · Setup seeds the live game state.
- Setup → Controller: launch · Setup starts the game controller.
- Game data → Card schema: conforms to · Game data uses the canonical card schema.
- Game data → Penalty schema: conforms to · Penalty data follows the penalty schema.
- Test card → Game data: override · Dev injection can bypass normal deck selection.
- Controller → State: read/write · Controller coordinates the authoritative runtime state.
- Controller → Deck: deal · Controller draws and distributes cards.
- Controller → Card handlers: route · Controller delegates card interactions to the handler router.
- Controller → Special actions: execute · Controller runs action/effect-driven behavior.
- Controller → UI facade: render · Controller updates the UI through the facade.
- Controller → History: record · Controller logs outcomes to history.
- Controller → Stats: update · Controller feeds gameplay stats.
- Controller → Nav guard: protect · Controller participates in active-game navigation protection.
- Card handlers → Flow machine: advance · Handlers drive the multi-step resolution machine.
- Card handlers → Effects: apply · Handlers invoke effect-specific logic when needed.
- Card handlers → Penalties: resolve · Handlers route penalty outcomes into penalty logic.
- Card handlers → Items: use · Handlers coordinate item-triggered flows.
- Flow machine → State: track · Flow machine stores interaction state in the runtime boundary.
- Special actions → Effects: dispatch · Special actions fan out into effect behavior.
- Special actions → Items: dispatch · Special actions can trigger item behavior.
- Special actions → Penalties: dispatch · Special actions can trigger penalty behavior.
- UI facade → Cards UI: compose · Facade coordinates card rendering.
- UI facade → Card modal: open · Facade opens modal-driven card interactions.
- UI facade → Effect picker: choose · Facade surfaces effect selection UI.
- UI facade → History: show · Facade feeds history displays.
- UI facade → Stats: show · Facade feeds stats displays.
- Stats → Leaderboard: aggregate · Stats flow into leaderboard summaries.
