# penguinmod/penguinmod-blocks architecture

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

- Interactive diagram: https://gitdiagram.com/penguinmod/penguinmod-blocks
- Repository: https://github.com/penguinmod/penguinmod-blocks

## Overview

PenguinMod-Blocks is a visual-programming editor library with vertical Scratch-style blocks and a horizontal, icon-oriented grammar. An embedding application presents the editor to users, who assemble connected blocks into programs; the README positions the library as an interface layer used with a virtual machine, rather than as a code generator. The tree also shows block-category definitions, drag/connection behavior, and localization conversion. Source excerpts confirm the dragger-to-insertion-marker relationship and the shim entry points; other runtime relationships are kept out where the supplied evidence does not establish them.

Main entry points: [`i18n/common.py`](https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/common.py) (Translation helpers), [`shim/vertical.js`](https://github.com/penguinmod/penguinmod-blocks/blob/develop/shim/vertical.js) (Vertical entry), [`shim/horizontal.js`](https://github.com/penguinmod/penguinmod-blocks/blob/develop/shim/horizontal.js) (Horizontal entry), [`core/insertion_marker_manager.js`](https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/insertion_marker_manager.js) (Insertion markers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Editor runtime"]
  node_vertical["Vertical entry<br/>[vertical.js]"]
  node_horizontal["Horizontal entry<br/>[horizontal.js]"]
  node_workspace["Workspace<br/>[workspace.js]"]
  node_block["Block model<br/>[block.js]"]
  node_render["Block rendering<br/>[block_render.js]"]
end

subgraph group_interaction["Block interaction"]
  node_drag["Block dragging<br/>[block_dragger.js]"]
  node_insertion["Insertion markers"]
  node_connections["Connections<br/>[connection.js]"]
end

subgraph group_grammars["Block grammars"]
  node_verticalblocks["Vertical categories<br/>[control.js]"]
  node_toolbox["Default toolbox<br/>[default_toolbox.js]"]
  node_commonblocks["Shared blocks<br/>[math.js]"]
end

subgraph group_localization["Localization"]
  node_messages["Message catalogs<br/>[messages.js]"]
  node_scratchmessages["Scratch messages<br/>[scratch_msgs.js]"]
  node_i18ncommon["Translation helpers<br/>[common.py]"]
  node_xliff["XLIFF converter<br/>[xliff_to_json.py]"]
  node_jsjson["Message extractor<br/>[js_to_json.py]"]
  node_jsonjs["Message generator<br/>[create_messages.py]"]
end

node_creator(("Editor user"))
node_embedding["Embedding app"]

node_creator -->|"uses editor"| node_embedding
node_embedding -.->|"loads vertical"| node_vertical
node_embedding -.->|"loads horizontal"| node_horizontal
node_vertical -->|"imports messages"| node_scratchmessages
node_horizontal -->|"imports messages"| node_scratchmessages
node_drag -->|"creates manager"| node_insertion
node_insertion -->|"connects blocks"| node_connections
node_xliff -->|"uses helpers"| node_i18ncommon
node_jsjson -->|"writes via"| node_i18ncommon
node_jsonjs -->|"uses helpers"| node_i18ncommon

click node_vertical "https://github.com/penguinmod/penguinmod-blocks/blob/develop/shim/vertical.js"
click node_horizontal "https://github.com/penguinmod/penguinmod-blocks/blob/develop/shim/horizontal.js"
click node_workspace "https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/workspace.js"
click node_block "https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/block.js"
click node_render "https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/block_render.js"
click node_drag "https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/block_dragger.js"
click node_insertion "https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/insertion_marker_manager.js"
click node_connections "https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/connection.js"
click node_verticalblocks "https://github.com/penguinmod/penguinmod-blocks/blob/develop/blocks_vertical/control.js"
click node_toolbox "https://github.com/penguinmod/penguinmod-blocks/blob/develop/blocks_vertical/default_toolbox.js"
click node_commonblocks "https://github.com/penguinmod/penguinmod-blocks/blob/develop/blocks_common/math.js"
click node_messages "https://github.com/penguinmod/penguinmod-blocks/blob/develop/msg/messages.js"
click node_scratchmessages "https://github.com/penguinmod/penguinmod-blocks/blob/develop/msg/scratch_msgs.js"
click node_i18ncommon "https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/common.py"
click node_xliff "https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/xliff_to_json.py"
click node_jsjson "https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/js_to_json.py"
click node_jsonjs "https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/create_messages.py"

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_vertical,node_horizontal,node_workspace,node_block,node_render,node_creator toneBlue
class node_drag,node_insertion,node_connections toneAmber
class node_verticalblocks,node_toolbox,node_commonblocks toneMint
class node_messages,node_scratchmessages,node_i18ncommon,node_xliff,node_jsjson,node_jsonjs toneRose
class node_embedding toneIndigo
```

## Components

### Editor runtime

- [Vertical entry](https://github.com/penguinmod/penguinmod-blocks/blob/develop/shim/vertical.js): `shim/vertical.js`
- [Horizontal entry](https://github.com/penguinmod/penguinmod-blocks/blob/develop/shim/horizontal.js): `shim/horizontal.js`
- [Workspace](https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/workspace.js): `core/workspace.js`
- [Block model](https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/block.js): `core/block.js`
- [Block rendering](https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/block_render.js): `core/block_render.js`

### Block interaction

- [Block dragging](https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/block_dragger.js): `core/block_dragger.js`
- [Insertion markers](https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/insertion_marker_manager.js): `core/insertion_marker_manager.js`
- [Connections](https://github.com/penguinmod/penguinmod-blocks/blob/develop/core/connection.js): `core/connection.js`

### Block grammars

- [Vertical categories](https://github.com/penguinmod/penguinmod-blocks/blob/develop/blocks_vertical/control.js): `blocks_vertical/control.js`
- [Default toolbox](https://github.com/penguinmod/penguinmod-blocks/blob/develop/blocks_vertical/default_toolbox.js): `blocks_vertical/default_toolbox.js`
- [Shared blocks](https://github.com/penguinmod/penguinmod-blocks/blob/develop/blocks_common/math.js): `blocks_common/math.js`

### Localization

- [Message catalogs](https://github.com/penguinmod/penguinmod-blocks/blob/develop/msg/messages.js): `msg/messages.js`
- [Scratch messages](https://github.com/penguinmod/penguinmod-blocks/blob/develop/msg/scratch_msgs.js): `msg/scratch_msgs.js`
- [Translation helpers](https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/common.py): `i18n/common.py`
- [XLIFF converter](https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/xliff_to_json.py): `i18n/xliff_to_json.py`
- [Message extractor](https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/js_to_json.py): `i18n/js_to_json.py`
- [Message generator](https://github.com/penguinmod/penguinmod-blocks/blob/develop/i18n/create_messages.py): `i18n/create_messages.py`

### Other components

- **Editor user**
- **Embedding app**

## Connections

- Editor user → Embedding app: uses editor
- Embedding app → Vertical entry: loads vertical
- Embedding app → Horizontal entry: loads horizontal
- Vertical entry → Scratch messages: imports messages (evidence: `shim/vertical.js`)
- Horizontal entry → Scratch messages: imports messages (evidence: `shim/horizontal.js`)
- Block dragging → Insertion markers: creates manager (evidence: `core/block_dragger.js`)
- Insertion markers → Connections: connects blocks (evidence: `core/insertion_marker_manager.js`)
- XLIFF converter → Translation helpers: uses helpers (evidence: `i18n/xliff_to_json.py`)
- Message extractor → Translation helpers: writes via (evidence: `i18n/js_to_json.py`)
- Message generator → Translation helpers: uses helpers (evidence: `i18n/create_messages.py`)
