# mof-mal/csharpblock4unity architecture

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

- Interactive diagram: https://gitdiagram.com/mof-mal/csharpblock4unity
- Repository: https://github.com/mof-mal/csharpblock4unity

## Overview

1. **What this repo is**
   - A single-page, browser-based visual programming editor for generating **C# code** from **Blockly** blocks.
   - The app is entirely client-side: React + TypeScript + Vite, with Blockly as the visual engine and a custom C# codegen layer.

2. **Top-level application shape**
   - `src/main.tsx` bootstraps the app.
   - `src/App.tsx` is the root shell.
   - The main editor experience lives under `src/pages/editor-page/`, which acts as the composition layer for the whole product.

3. **Primary screen composition**
   - The editor page combines several feature modules:
     - `header` for top-level actions/navigation
     - `workspace-tabs` for switching between multiple scripts/workspaces
     - `block-canvas` for the Blockly editing surface
     - `code-preview` for generated C# output
     - `chain-menu` for block-chain insertion/interaction affordances
     - `autosave` for persistence behavior
   - This is the main UI boundary: page-level orchestration vs feature-level implementation.

4. **Blockly integration layer**
   - The `src/util/blockly/` directory is the core integration boundary around Blockly.
   - It contains custom block creation, toolbox construction, mutator registration, connection/type checking, shadow blocks, and helpers for chain/block behavior.
   - This layer is responsible for turning the app’s schema and domain rules into a Blockly workspace that behaves consistently.

5. **Schema-driven block model**
   - `src/assets/schema/` holds JSON schema fragments such as `engineCore.json`, `variables.json`, `operators.json`, `event.json`, and others.
   - `src/util/schema/` loads, validates, and namespaces these schemas.
   - The schema layer is the source of truth for what blocks exist, how they are grouped, and what types or namespaces they belong to.

6. **Type and definition model**
   - `src/types/` defines the repository’s domain contracts: block definitions, workspace state, schema shape, and codegen-related types.
   - These types are shared across schema parsing, Blockly setup, workspace management, and code generation to keep the system aligned.

7. **Code generation pipeline**
   - `src/util/codegen/` is the output side of the architecture.
   - It converts the block/workspace model into formatted C# via custom generators and a C# formatter.
   - The code preview feature depends on this pipeline to render live output as the user edits blocks.

8. **Workspace and autosave behavior**
   - `src/features/workspace-tabs/` manages multiple editable workspaces, including tab state and switching logic.
   - `src/features/autosave/` provides persistence of editor state, likely backed by browser storage; the presence of `localStrageSample.json` suggests local serialized workspace data is a key runtime artifact.
   - Together, these features define how editing sessions survive and how multiple scripts are handled in one browser session.

9. **User interaction features**
   - `chain-menu` and its hook (`useDotMenu`) suggest specialized contextual editing for chaining blocks or inserting connected actions.
   - `block-canvas/customTheme.ts` and `src/shared/ui/ToolbarButton.tsx` indicate a small shared UI layer plus Blockly-specific theming for consistent editor behavior.

10. **Runtime data flow**
   - The practical flow is:
     - JSON schemas define available block families and types
     - Blockly utilities build/register those blocks and toolbox entries
     - The user assembles blocks in the canvas
     - Workspace state is updated and optionally autosaved
     - The codegen layer translates the workspace into C#
     - The preview panel renders the generated code in real time

11. **Boundary between presentation and domain logic**
   - `src/features/` contains user-facing capabilities and UI composition.
   - `src/util/` contains the heavier domain logic: Blockly customization, schema interpretation, and code generation.
   - This separation is important for diagramming: the editor UI is not where the block semantics live; those rules are centralized in utilities and schema assets.

12. **Build, tooling, and delivery**
   - Vite handles bundling and dev server operation.
   - ESLint, Prettier, and Husky indicate enforced code quality via local git hooks.
   - The GitHub Actions workflow under `.github/workflows/static.yml` suggests static build/deploy automation for the compiled client app.

13. **How to think about the architecture diagram**
   - Draw it as a **browser-based editor** with three main layers:
     - **UI composition**: page + features
     - **Domain engine**: Blockly/schema/type/codegen utilities
     - **Static assets and config**: schemas, icons, app config
   - The central integration point is the Blockly workspace, which connects user interaction to the generated C# output and persistence features.

Main entry points: [`src/pages/editor-page/ui.tsx`](https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/ui.tsx) (Page UI), [`src/pages/editor-page/index.tsx`](https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/index.tsx) (Editor page), [`src/util/blockly`](https://github.com/mof-mal/csharpblock4unity/tree/main/src/util/blockly) (Blockly integration), [`src/features/block-canvas/index.tsx`](https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/block-canvas/index.tsx) (Block canvas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_main["main.tsx<br/>bootstrap<br/>[main.tsx]"]
  node_node_app["App shell<br/>root component<br/>[App.tsx]"]
end

subgraph group_group_ui["Editor UI"]
  node_node_editor_page["Editor page<br/>composition page<br/>[index.tsx]"]
  node_node_editor_ui["Page UI<br/>page view<br/>[ui.tsx]"]
  node_node_editor_model["Page model<br/>page logic<br/>[model.ts]"]
  node_node_header["Header<br/>editor feature<br/>[index.tsx]"]
  node_node_tabs["Workspace tabs<br/>editor feature<br/>[index.tsx]"]
  node_node_canvas["Block canvas<br/>editor surface<br/>[index.tsx]"]
  node_node_chain_menu["Chain menu<br/>editor feature<br/>[index.tsx]"]
  node_node_preview["Code preview<br/>output panel<br/>[index.tsx]"]
  node_node_autosave["Autosave<br/>persistence feature<br/>[index.ts]"]
  node_node_shared_ui["Shared UI<br/>ui primitives"]
end

subgraph group_group_domain["Domain Engine"]
  node_node_blockly["Blockly integration<br/>integration layer"]
  node_node_schema_util["Schema loader<br/>schema service"]
  node_node_codegen["C# codegen<br/>generation pipeline"]
  node_node_types["Domain types<br/>contracts"]
  node_node_app_config["App config<br/>app settings<br/>[appConfig.ts]"]
end

subgraph group_group_assets["Static Assets"]
  node_node_schemas["Block schemas<br/>schema assets"]
end

subgraph group_group_tooling["Tooling"]
  node_node_build{{"Build & deploy<br/>tooling"}}
end

node_node_main -->|"mounts"| node_node_app
node_node_app -->|"renders"| node_node_editor_page
node_node_editor_page -->|"composes"| node_node_editor_ui
node_node_editor_page -->|"orchestrates"| node_node_editor_model
node_node_editor_ui -->|"includes"| node_node_header
node_node_editor_ui -->|"includes"| node_node_tabs
node_node_editor_ui -->|"includes"| node_node_canvas
node_node_editor_ui -->|"includes"| node_node_chain_menu
node_node_editor_ui -->|"includes"| node_node_preview
node_node_editor_page -->|"persists"| node_node_autosave
node_node_canvas -->|"uses"| node_node_blockly
node_node_chain_menu -->|"extends"| node_node_blockly
node_node_blockly -->|"loads schema from"| node_node_schema_util
node_node_schema_util -->|"reads"| node_node_schemas
node_node_blockly -->|"conforms to"| node_node_types
node_node_codegen -->|"conforms to"| node_node_types
node_node_preview -->|"renders output from"| node_node_codegen
node_node_autosave -->|"stores"| node_node_types
node_node_shared_ui -->|"supports"| node_node_header
node_node_shared_ui -->|"supports"| node_node_canvas
node_node_blockly -->|"feeds"| node_node_codegen
node_node_app_config -->|"configures"| node_node_editor_page
node_node_build -->|"delivers"| node_node_main
node_node_build -->|"bundles"| node_node_schemas

click node_node_main "https://github.com/mof-mal/csharpblock4unity/blob/main/src/main.tsx"
click node_node_app "https://github.com/mof-mal/csharpblock4unity/blob/main/src/App.tsx"
click node_node_editor_page "https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/index.tsx"
click node_node_editor_ui "https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/ui.tsx"
click node_node_editor_model "https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/model.ts"
click node_node_header "https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/header/index.tsx"
click node_node_tabs "https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/workspace-tabs/index.tsx"
click node_node_canvas "https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/block-canvas/index.tsx"
click node_node_chain_menu "https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/chain-menu/index.tsx"
click node_node_preview "https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/code-preview/index.tsx"
click node_node_autosave "https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/autosave/index.ts"
click node_node_blockly "https://github.com/mof-mal/csharpblock4unity/tree/main/src/util/blockly"
click node_node_schema_util "https://github.com/mof-mal/csharpblock4unity/tree/main/src/util/schema"
click node_node_codegen "https://github.com/mof-mal/csharpblock4unity/tree/main/src/util/codegen"
click node_node_types "https://github.com/mof-mal/csharpblock4unity/tree/main/src/types"
click node_node_schemas "https://github.com/mof-mal/csharpblock4unity/tree/main/src/assets/schema"
click node_node_shared_ui "https://github.com/mof-mal/csharpblock4unity/tree/main/src/shared/ui"
click node_node_app_config "https://github.com/mof-mal/csharpblock4unity/blob/main/src/app/config/appConfig.ts"

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_node_main,node_node_app toneBlue
class node_node_editor_page,node_node_editor_ui,node_node_editor_model,node_node_header,node_node_tabs,node_node_canvas,node_node_chain_menu,node_node_preview,node_node_autosave,node_node_shared_ui toneAmber
class node_node_blockly,node_node_schema_util,node_node_codegen,node_node_types,node_node_app_config toneMint
class node_node_schemas toneRose
class node_node_build toneIndigo
```

## Components

### App Shell

Bootstrapping and top-level page composition for the client app.

- [main.tsx](https://github.com/mof-mal/csharpblock4unity/blob/main/src/main.tsx): bootstrap · App entrypoint that mounts the React application. · `src/main.tsx`
- [App shell](https://github.com/mof-mal/csharpblock4unity/blob/main/src/App.tsx): root component · Top-level React shell for the single-page app. · `src/App.tsx`

### Editor UI

User-facing editor features assembled on the main screen.

- [Editor page](https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/index.tsx): composition page · Main composition layer that wires together the editing experience. · `src/pages/editor-page/index.tsx`
- [Page UI](https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/ui.tsx): page view · Editor page presentation and layout boundaries. · `src/pages/editor-page/ui.tsx`
- [Page model](https://github.com/mof-mal/csharpblock4unity/blob/main/src/pages/editor-page/model.ts): page logic · State and orchestration logic behind the editor page. · `src/pages/editor-page/model.ts`
- [Header](https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/header/index.tsx): editor feature · Top-level actions and navigation for the editor. · `src/features/header/index.tsx`
- [Workspace tabs](https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/workspace-tabs/index.tsx): editor feature · Switches between multiple workspaces or scripts. · `src/features/workspace-tabs/index.tsx`
- [Block canvas](https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/block-canvas/index.tsx): editor surface · Blockly editing surface and theme integration. · `src/features/block-canvas/index.tsx`
- [Chain menu](https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/chain-menu/index.tsx): editor feature · Contextual chain insertion and block interaction affordances. · `src/features/chain-menu/index.tsx`
- [Code preview](https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/code-preview/index.tsx): output panel · Renders generated C# output as the user edits blocks. · `src/features/code-preview/index.tsx`
- [Autosave](https://github.com/mof-mal/csharpblock4unity/blob/main/src/features/autosave/index.ts): persistence feature · Persists editor state across sessions. · `src/features/autosave/index.ts`
- [Shared UI](https://github.com/mof-mal/csharpblock4unity/tree/main/src/shared/ui): ui primitives · Reusable UI controls shared across the editor. · `src/shared/ui`

### Domain Engine

Schema, Blockly integration, workspace model, and C# code generation.

- [Blockly integration](https://github.com/mof-mal/csharpblock4unity/tree/main/src/util/blockly): integration layer · Custom Blockly setup for block creation, workspace behavior, and toolbox assembly. · `src/util/blockly`
- [Schema loader](https://github.com/mof-mal/csharpblock4unity/tree/main/src/util/schema): schema service · Loads, validates, and namespaces schema definitions. · `src/util/schema`
- [C# codegen](https://github.com/mof-mal/csharpblock4unity/tree/main/src/util/codegen): generation pipeline · Transforms workspace blocks into formatted C# output. · `src/util/codegen`
- [Domain types](https://github.com/mof-mal/csharpblock4unity/tree/main/src/types): contracts · Shared type definitions for blocks, schema, workspace, and codegen. · `src/types`
- [App config](https://github.com/mof-mal/csharpblock4unity/blob/main/src/app/config/appConfig.ts): app settings · Client application configuration and runtime settings. · `src/app/config/appConfig.ts`

### Static Assets

Schema fragments and other static runtime inputs.

- [Block schemas](https://github.com/mof-mal/csharpblock4unity/tree/main/src/assets/schema): schema assets · JSON schema fragments defining available block families and namespaces. · `src/assets/schema`

### Tooling

Build, quality, and delivery configuration.

- **Build & deploy**: tooling · Vite bundling, linting, hooks, and static deployment automation.

## Connections

- main.tsx → App shell: mounts · Bootstraps the React shell.
- App shell → Editor page: renders · The app shell hosts the editor experience.
- Editor page → Page UI: composes · Page composition delegates to a UI layer.
- Editor page → Page model: orchestrates · Page logic manages editor state and coordination.
- Page UI → Header: includes · Top-level actions are part of the editor layout.
- Page UI → Workspace tabs: includes · Workspace switching is embedded in the screen.
- Page UI → Block canvas: includes · Blockly canvas is the main editing surface.
- Page UI → Chain menu: includes · Contextual chain interactions support block editing.
- Page UI → Code preview: includes · Code output is shown alongside the canvas.
- Editor page → Autosave: persists · Session state is saved from the editor boundary.
- Block canvas → Blockly integration: uses · The canvas is backed by custom Blockly integration.
- Chain menu → Blockly integration: extends · Chain interactions operate on Blockly workspace behavior.
- Blockly integration → Schema loader: loads schema from · Blockly setup is driven by normalized schema data.
- Schema loader → Block schemas: reads · Schema utilities consume JSON schema fragments.
- Blockly integration → Domain types: conforms to · Block and workspace behavior uses shared contracts.
- C# codegen → Domain types: conforms to · Code generation consumes shared workspace and block types.
- Code preview → C# codegen: renders output from · The preview panel displays generated C# code.
- Autosave → Domain types: stores · Persisted workspace state follows shared workspace types.
- Shared UI → Header: supports · Shared controls are used by editor-facing features.
- Shared UI → Block canvas: supports · Reusable UI primitives support the editor surface.
- Blockly integration → C# codegen: feeds · Workspace edits flow into the generation pipeline.
- App config → Editor page: configures · App settings influence editor startup and behavior.
- Build & deploy → main.tsx: delivers · Tooling packages and serves the client application.
- Build & deploy → Block schemas: bundles · Static schema assets are included in the app build.
