# nyanbinaryninja/cpupuzzlegen architecture

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

- Interactive diagram: https://gitdiagram.com/nyanbinaryninja/cpupuzzlegen
- Repository: https://github.com/nyanbinaryninja/cpupuzzlegen

## Overview

1. **Overall shape**
   - This is a **browser-only, static JavaScript app**. The repository has a single `index.html`, one stylesheet, and a set of ES-style JS modules under `js/`.
   - There is **no backend, API layer, or persistent storage** visible in the repo. All puzzle generation and rendering happens client-side in the browser.

2. **Entry point and shell**
   - `index.html` is the application shell and likely bootstraps the UI.
   - `js/app.js` is the top-level orchestrator: it likely wires together the UI controls, active cipher/puzzle mode, and the various generators/renderers.

3. **Presentation layer**
   - `css/ui.css` owns the app’s visual layout and styling.
   - The UI appears to be a single-page tool with multiple panels/windows rather than a navigation-heavy site, given the presence of `window_manager.js`.

4. **Core orchestration**
   - `js/general/window_manager.js` likely manages panel visibility, modal/dialog behavior, or draggable/resizable windows.
   - `js/general/theme_manager.js` suggests the app supports switching visual themes without changing the underlying generation logic.
   - These modules sit above the content generators and below the top-level app bootstrap.

5. **Shared utility layer**
   - `js/general/input_filter.js` is likely a validation/sanitization layer for user-entered text or parameters.
   - `js/general/effects.js` probably handles visual effects such as animations, highlights, or transitions.
   - These utilities are cross-cutting concerns used by multiple parts of the app rather than a single puzzle type.

6. **Generation/rendering helpers**
   - `js/general/grid_maker.js` likely builds the structured grid layouts used by several puzzle types.
   - `js/general/flag_generator.js` suggests a specialized generator for flag-like outputs or flag-themed assets.
   - `js/general/gif_generator.js` indicates export or preview support for animated output, probably used when the app needs to package generated content visually.

7. **Cipher/puzzle modules**
   - `js/ciphers/` contains the domain-specific puzzle implementations:
     - `circuit.js`
     - `maze.js`
     - `pigpen.js`
     - `polybius.js`
     - `radar.js`
   - These look like **pluggable puzzle modes** or cipher styles, each likely producing its own grid, symbols, or transformed output while sharing the same app shell and utility layer.

8. **Data flow**
   - User input enters through the UI in `index.html`, is validated by `input_filter.js`, then routed by `app.js` to the selected cipher/generator module.
   - The chosen cipher module produces structured puzzle data or render-ready content.
   - Shared helpers such as `grid_maker.js`, `flag_generator.js`, and `gif_generator.js` convert that data into the final visual form shown in the browser.

9. **Separation of concerns**
   - The architecture is cleanly split into:
     - **shell/UI concerns**: HTML, CSS, window/theme management
     - **shared logic**: input filtering, effects, layout helpers
     - **domain logic**: cipher-specific generators
   - That separation makes it easy to add new puzzle types without rewriting the UI shell.

10. **Likely extensibility boundary**
   - New cipher modes would be added under `js/ciphers/` and registered through `app.js`.
   - New shared rendering behaviors would belong in `js/general/`.
   - This suggests the repo is organized as a **modular client-side generator framework**, not a monolithic script.

11. **What to show in an architecture diagram**
   - Draw one outer boundary for the **browser runtime**.
   - Inside it, separate **UI shell**, **shared utilities**, and **cipher modules**.
   - Show `app.js` as the central coordinator between UI input and generation modules.
   - Show `index.html` and `ui.css` as the presentation entry points feeding into the JS modules.

12. **Not present in the repo**
   - No server, database, build pipeline, or external service integration is visible from the tree.
   - The architecture appears intentionally lightweight and self-contained, which is important for understanding deployment: this is likely served as static files.

Main entry points: [`js/app.js`](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/app.js) (app.js), [`js/general/grid_maker.js`](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/grid_maker.js) (Grid maker), [`index.html`](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/index.html) (index.html), [`js/ciphers/circuit.js`](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/circuit.js) (Circuit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser runtime"]
end

subgraph group_presentation["Presentation layer"]
  node_index_html["index.html<br/>shell entry<br/>[index.html]"]
  node_ui_css["ui.css<br/>styles<br/>[ui.css]"]
end

subgraph group_core["Core orchestration"]
  node_app_js["app.js<br/>orchestrator<br/>[app.js]"]
  node_window_manager["Window mgr<br/>ui manager<br/>[window_manager.js]"]
  node_theme_manager["Theme mgr<br/>ui manager<br/>[theme_manager.js]"]
  node_input_filter["Input filter<br/>validation<br/>[input_filter.js]"]
  node_effects["Effects<br/>[effects.js]"]
  node_grid_maker["Grid maker<br/>layout helper<br/>[grid_maker.js]"]
  node_flag_generator["Flag generator<br/>output helper<br/>[flag_generator.js]"]
  node_gif_generator["GIF generator<br/>export helper<br/>[gif_generator.js]"]
end

subgraph group_ciphers["Cipher modules"]
  node_circuit{{"Circuit<br/>cipher mode<br/>[circuit.js]"}}
  node_maze{{"Maze<br/>cipher mode<br/>[maze.js]"}}
  node_pigpen{{"Pigpen<br/>cipher mode<br/>[pigpen.js]"}}
  node_polybius{{"Polybius<br/>cipher mode<br/>[polybius.js]"}}
  node_radar{{"Radar<br/>cipher mode<br/>[radar.js]"}}
end

node_index_html -->|"bootstraps"| node_app_js
node_index_html -->|"styles"| node_ui_css
node_app_js -->|"controls"| node_window_manager
node_app_js -->|"themes"| node_theme_manager
node_app_js -->|"validates"| node_input_filter
node_app_js -->|"effects"| node_effects
node_app_js -->|"builds"| node_grid_maker
node_app_js -->|"renders"| node_flag_generator
node_app_js -->|"exports"| node_gif_generator
node_app_js -->|"selects"| node_circuit
node_app_js -->|"selects"| node_maze
node_app_js -->|"selects"| node_pigpen
node_app_js -->|"selects"| node_polybius
node_app_js -->|"selects"| node_radar
node_circuit -.->|"uses"| node_grid_maker
node_maze -.->|"uses"| node_grid_maker
node_pigpen -.->|"uses"| node_grid_maker
node_polybius -.->|"uses"| node_grid_maker
node_radar -.->|"uses"| node_grid_maker

click node_index_html "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/index.html"
click node_ui_css "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/css/ui.css"
click node_app_js "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/app.js"
click node_window_manager "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/window_manager.js"
click node_theme_manager "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/theme_manager.js"
click node_input_filter "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/input_filter.js"
click node_effects "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/effects.js"
click node_grid_maker "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/grid_maker.js"
click node_flag_generator "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/flag_generator.js"
click node_gif_generator "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/gif_generator.js"
click node_circuit "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/circuit.js"
click node_maze "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/maze.js"
click node_pigpen "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/pigpen.js"
click node_polybius "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/polybius.js"
click node_radar "https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/radar.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_index_html,node_ui_css toneAmber
class node_app_js,node_window_manager,node_theme_manager,node_input_filter,node_effects,node_grid_maker,node_flag_generator,node_gif_generator toneMint
class node_circuit,node_maze,node_pigpen,node_polybius,node_radar toneRose
```

## Components

### Presentation layer

HTML and CSS entry points for the app shell

- [index.html](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/index.html): shell entry · Application shell and bootstrap entry point · `index.html`
- [ui.css](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/css/ui.css): styles · Global visual layout and styling · `css/ui.css`

### Core orchestration

Top-level app coordination and shared UI/runtime managers

- [app.js](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/app.js): orchestrator · Top-level wiring for UI, modes, and generation · `js/app.js`
- [Window mgr](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/window_manager.js): ui manager · Controls panels, windows, and visibility · `js/general/window_manager.js`
- [Theme mgr](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/theme_manager.js): ui manager · Switches visual themes and presentation state · `js/general/theme_manager.js`
- [Input filter](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/input_filter.js): validation · Sanitizes and validates user input · `js/general/input_filter.js`
- [Effects](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/effects.js): ui effects · Visual feedback, highlights, and transitions · `js/general/effects.js`
- [Grid maker](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/grid_maker.js): layout helper · Builds structured grid layouts for puzzles · `js/general/grid_maker.js`
- [Flag generator](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/flag_generator.js): output helper · Generates flag-like visual outputs or assets · `js/general/flag_generator.js`
- [GIF generator](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/general/gif_generator.js): export helper · Creates animated previews or exports · `js/general/gif_generator.js`

### Cipher modules

Pluggable puzzle and cipher implementations

- [Circuit](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/circuit.js): cipher mode · Circuit-themed puzzle implementation · `js/ciphers/circuit.js`
- [Maze](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/maze.js): cipher mode · Maze-style puzzle implementation · `js/ciphers/maze.js`
- [Pigpen](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/pigpen.js): cipher mode · Pigpen-symbol puzzle implementation · `js/ciphers/pigpen.js`
- [Polybius](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/polybius.js): cipher mode · Polybius-square puzzle implementation · `js/ciphers/polybius.js`
- [Radar](https://github.com/nyanbinaryninja/cpupuzzlegen/blob/main/js/ciphers/radar.js): cipher mode · Radar-themed puzzle implementation · `js/ciphers/radar.js`

## Connections

- index.html → app.js: bootstraps · Loads the application orchestrator
- index.html → ui.css: styles · Applies the visual shell styling
- app.js → Window mgr: controls · Coordinates panel and window behavior
- app.js → Theme mgr: themes · Delegates visual theme switching
- app.js → Input filter: validates · Normalizes user-entered values
- app.js → Effects: effects · Triggers UI feedback and transitions
- app.js → Grid maker: builds · Uses grid layout helpers for puzzle construction
- app.js → Flag generator: renders · Uses flag-style rendering helpers when needed
- app.js → GIF generator: exports · Uses animated output helpers when needed
- app.js → Circuit: selects · Routes to the chosen cipher mode
- app.js → Maze: selects · Routes to the chosen cipher mode
- app.js → Pigpen: selects · Routes to the chosen cipher mode
- app.js → Polybius: selects · Routes to the chosen cipher mode
- app.js → Radar: selects · Routes to the chosen cipher mode
- Circuit → Grid maker: uses · Produces structured puzzle layouts
- Maze → Grid maker: uses · Produces structured puzzle layouts
- Pigpen → Grid maker: uses · Produces structured puzzle layouts
- Polybius → Grid maker: uses · Produces structured puzzle layouts
- Radar → Grid maker: uses · Produces structured puzzle layouts
