# elouangrimm/kelk architecture

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

- Interactive diagram: https://gitdiagram.com/elouangrimm/kelk
- Repository: https://github.com/elouangrimm/kelk

## Overview

1. **What this repo is**
   - This is a browser-based digital painting app, “Kelk,” forked from Klecks.
   - It is a client-side TypeScript application with no visible backend in the repo; persistence and export are handled in-browser using Web APIs.

2. **Top-level app shell**
   - `src/app/script/main-standalone.ts` is the standalone entrypoint used for the downloadable app build.
   - `src/index.html`, `src/style/*`, `src/app/theme/*`, and `src/app/fonts/*` define the page shell, styling, themeing, and font assets.
   - `src/app/script/app/*` contains bootstrapping and app-level wiring, including import handling and app selection flows.

3. **Core painting domain**
   - The main domain lives under `src/app/script/klecks/*`.
   - This layer owns the project model, layers, brushes, tools, filters, selection, history, storage, and most UI.
   - `kl.ts`, `kl-types.ts`, and `kl-config.ts` appear to define the application’s central state and configuration boundaries.

4. **Canvas and rendering pipeline**
   - `src/app/script/klecks/canvas/*` is the raster drawing/compositing layer.
   - It handles painting onto canvases, eyedropper sampling, blending, and composing layer updates into the final project view.
   - `src/app/script/klecks/ui/project-viewport/*` is the preview/render surface shown to the user, including project preview rendering and FX preview integration.

5. **Brush and stroke subsystem**
   - Brushes are separated into a brush engine and brush-specific UI.
   - `src/app/script/klecks/brushes/*` contains the drawing behaviors: pen, blend, sketchy, pixel, chemy, smudge, and eraser.
   - `src/app/script/klecks/brushes-ui/*` contains the settings panels and controls for those brushes.
   - Stroke cleanup and smoothing live in `src/app/script/klecks/events/*`, which sits between raw input and rendered brush paths.

6. **Input and gesture architecture**
   - Raw user input is normalized in `src/app/script/bb/input/*`.
   - There are separate listeners for pointer, key, gesture, and wheel input, plus utilities for pressure normalization and event-chain handling.
   - The event-chain utilities suggest a middleware-like pipeline for multi-touch gestures such as pinch zoom, double tap, and pointer coalescing before tools receive input.

7. **Tooling and interaction model**
   - The interactive tool layer is in `src/app/script/klecks/ui/easel/*` and `src/app/script/klecks/ui/tool-tabs/*`.
   - The easel is the main interaction surface for brush strokes, hand/pan, zoom, rotate, select, paint bucket, gradient, shape, text, and eyedropper tools.
   - Tool tabs expose higher-level editing workflows such as file operations, fill, filters, layers, selection, settings, shapes, and text.

8. **Selection, transforms, and edit operations**
   - Selection logic and transform handling are split across `src/app/script/klecks/select-tool/*`, `src/app/script/bb/multi-polygon/*`, and `src/app/script/bb/transform/*`.
   - This layer supports polygon/shape selection, bounding-box calculations, free transform, crop/expand, resize, perspective, and related geometry operations.
   - It is a distinct boundary between user interaction and pixel-level canvas mutation.

9. **Filters and image operations**
   - There are two filter-related areas:
     - `src/app/script/fx-canvas/*` for WebGL-based effect infrastructure and shaders.
     - `src/app/script/klecks/filters/*` for app-level filter workflows such as blur, curves, distort, noise, rotate, flip, tilt-shift, unsharp mask, and perspective.
   - Additional image tools such as flood fill, text rendering, grids, vanish point, and shapes are under `src/app/script/klecks/image-operations/*`.
   - This indicates a split between GPU-accelerated effects and application-level editing commands.

10. **History and undo/redo**
    - `src/app/script/klecks/history/*` manages project history, temp history, and execution of history entries.
    - The history system tracks layer changes, opacity/visibility changes, and canvas tile diffs, which implies fine-grained undo/redo rather than full-scene snapshots only.
    - There are helpers for composing history state, estimating memory cost, and converting project state to composable layer data.

11. **Storage, import/export, and external boundaries**
    - Persistence is handled in `src/app/script/klecks/storage/*`.
    - The app uses browser storage primitives such as IndexedDB and likely localStorage for project persistence and state recall.
    - It can load/save project formats, export canvas data, and save files to the user’s computer.
    - The presence of `imgur-upload.ts` indicates an optional external service boundary for sharing or uploading images.

12. **UI system and modal workflows**
    - Reusable UI widgets live in `src/app/script/klecks/ui/components/*`.
    - Modal dialogs cover file import, new image creation, clipboard actions, licenses, image import, text tool editing, and iframe-based dialogs.
    - Mobile-specific layout and toolspace behavior live under `src/app/script/klecks/ui/mobile/*`, showing the app is designed for multiple form factors with separate interaction ergonomics.

13. **Localization and content assets**
    - User-facing language content is stored under `src/languages/*`, with generated JSON5 sources and language metadata.
    - `src/app/script/language/*` likely wires translated strings into runtime language selection.
    - Fonts and licenses are bundled locally, so text rendering and legal attribution are part of the app package rather than external dependencies.

14. **Build and deployment shape**
    - This is a Node/npm-based frontend project, built with `npm run build` into `dist/`.
    - `docker-compose.yml` and `Dockerfile` support containerized local serving on port 5050.
    - The architecture is therefore a single-page/browser app with static asset delivery, GPU-accelerated effects, and browser-native persistence, rather than a client-server application.

Main entry points: [`src/app/script/klecks/kl.ts`](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/kl.ts) (Kelk state), [`src/app/script/app/kl-app.ts`](https://github.com/elouangrimm/kelk/blob/main/src/app/script/app/kl-app.ts) (App wiring), [`src/app/script/klecks/ui/easel/easel.ts`](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/easel/easel.ts) (Easel), [`src/app/script/klecks/ui/tool-tabs/file-ui.ts`](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/tool-tabs/file-ui.ts) (Tool tabs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App shell"]
  node_main_standalone["Standalone app<br/>entrypoint<br/>[main-standalone.ts]"]
  node_app_wiring["App wiring<br/>bootstrap<br/>[kl-app.ts]"]
  node_theme_assets["Theme & styles<br/>ui assets<br/>[style.scss]"]
  node_fonts_assets["Fonts<br/>asset bundle<br/>[fonts.ts]"]
end

subgraph group_painting_core["Painting core"]
  node_kl_state["Kelk state<br/>core model<br/>[kl.ts]"]
  node_kl_types["Core types<br/>type boundary<br/>[kl-types.ts]"]
  node_kl_config["Config<br/>[kl-config.ts]"]
  node_brushes["Brush engine<br/>paint engine<br/>[brushes.ts]"]
  node_brushes_ui["Brush UI<br/>controls<br/>[brushes-ui.ts]"]
  node_canvas_core["Canvas core<br/>raster pipeline<br/>[kl-canvas.ts]"]
  node_history["History<br/>undo/redo<br/>[kl-history.ts]"]
  node_storage["Storage<br/>persistence/export<br/>[project-store.ts]"]
end

subgraph group_interaction["Interaction"]
  node_input_chain["Input chain<br/>event pipeline<br/>[event-chain.ts]"]
  node_geometry["Geometry<br/>math helpers"]
  node_select_tool["Selection tools<br/>selection/transform<br/>[select-tool.ts]"]
end

subgraph group_effects["Effects"]
  node_fx_core["FX canvas<br/>webgl effects<br/>[fx-canvas.ts]"]
  node_filters["Filters<br/>[filters.ts]"]
  node_image_ops["Image ops<br/>tools<br/>[flood-fill.ts]"]
end

subgraph group_ui["UI"]
  node_easel_ui["Easel<br/>interaction surface<br/>[easel.ts]"]
  node_project_view["Project view<br/>preview/render"]
  node_tool_tabs["Tool tabs<br/>workspace ui<br/>[file-ui.ts]"]
  node_ui_components["UI components<br/>widgets<br/>[checkbox.ts]"]
  node_mobile_ui["Mobile UI<br/>responsive ui<br/>[mobile-ui.ts]"]
  node_modals["Modals<br/>dialogs"]
end

subgraph group_assets["Assets"]
  node_languages["Languages<br/>localization<br/>[language.ts]"]
end

node_main_standalone -->|"boots"| node_app_wiring
node_app_wiring -->|"initializes"| node_kl_state
node_app_wiring -->|"loads"| node_theme_assets
node_app_wiring -->|"localizes"| node_languages
node_app_wiring -->|"opens"| node_modals
node_kl_state -->|"uses"| node_kl_types
node_kl_state -->|"reads"| node_kl_config
node_kl_state -->|"coordinates"| node_brushes
node_kl_state -->|"mutates"| node_canvas_core
node_kl_state -->|"records"| node_history
node_kl_state -->|"persists"| node_storage
node_brushes_ui -->|"configures"| node_brushes
node_input_chain -->|"feeds"| node_easel_ui
node_input_chain -->|"drives"| node_select_tool
node_input_chain -->|"streams"| node_brushes
node_geometry -->|"supports"| node_select_tool
node_select_tool -->|"applies"| node_canvas_core
node_easel_ui -->|"renders via"| node_canvas_core
node_easel_ui -->|"invokes"| node_image_ops
node_project_view -->|"previews"| node_fx_core
node_filters -->|"executes on"| node_fx_core
node_filters -->|"updates"| node_canvas_core
node_tool_tabs -->|"exposes"| node_filters
node_tool_tabs -->|"commits"| node_history
node_tool_tabs -->|"saves"| node_storage
node_ui_components -->|"compose"| node_easel_ui
node_ui_components -->|"compose"| node_tool_tabs
node_mobile_ui -->|"adapts"| node_easel_ui
node_modals -->|"imports/exports"| node_storage

click node_main_standalone "https://github.com/elouangrimm/kelk/blob/main/src/app/script/main-standalone.ts"
click node_app_wiring "https://github.com/elouangrimm/kelk/blob/main/src/app/script/app/kl-app.ts"
click node_theme_assets "https://github.com/elouangrimm/kelk/blob/main/src/app/style/style.scss"
click node_fonts_assets "https://github.com/elouangrimm/kelk/blob/main/src/app/fonts/fonts.ts"
click node_kl_state "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/kl.ts"
click node_kl_types "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/kl-types.ts"
click node_kl_config "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/kl-config.ts"
click node_brushes "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/brushes/brushes.ts"
click node_brushes_ui "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/brushes-ui/brushes-ui.ts"
click node_canvas_core "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/canvas/kl-canvas.ts"
click node_history "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/history/kl-history.ts"
click node_storage "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/storage/project-store.ts"
click node_input_chain "https://github.com/elouangrimm/kelk/blob/main/src/app/script/bb/input/event-chain/event-chain.ts"
click node_geometry "https://github.com/elouangrimm/kelk/blob/main/src/app/script/bb/multi-polygon/multi-polygon-from-rect.ts"
click node_select_tool "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/select-tool/select-tool.ts"
click node_fx_core "https://github.com/elouangrimm/kelk/blob/main/src/app/script/fx-canvas/fx-canvas.ts"
click node_filters "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/filters/filters.ts"
click node_image_ops "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/image-operations/flood-fill.ts"
click node_easel_ui "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/easel/easel.ts"
click node_project_view "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/project-viewport/project-viewport.ts"
click node_tool_tabs "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/tool-tabs/file-ui.ts"
click node_ui_components "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/components/checkbox.ts"
click node_mobile_ui "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/mobile/mobile-ui.ts"
click node_modals "https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/modals/show-import-image-dialog.ts"
click node_languages "https://github.com/elouangrimm/kelk/blob/main/src/app/script/language/language.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_main_standalone,node_app_wiring,node_theme_assets,node_fonts_assets toneBlue
class node_kl_state,node_kl_types,node_kl_config,node_brushes,node_brushes_ui,node_canvas_core,node_history,node_storage toneAmber
class node_input_chain,node_geometry,node_select_tool toneMint
class node_fx_core,node_filters,node_image_ops toneRose
class node_easel_ui,node_project_view,node_tool_tabs,node_ui_components,node_mobile_ui,node_modals toneIndigo
class node_languages toneTeal
```

## Components

### App shell

Standalone entrypoint, page chrome, theme, fonts, and app boot wiring.

- [Standalone app](https://github.com/elouangrimm/kelk/blob/main/src/app/script/main-standalone.ts): entrypoint · Downloadable app bootstrap and standalone startup. · `src/app/script/main-standalone.ts`
- [App wiring](https://github.com/elouangrimm/kelk/blob/main/src/app/script/app/kl-app.ts): bootstrap · Application selection, import handling, and shell coordination. · `src/app/script/app/kl-app.ts`
- [Theme & styles](https://github.com/elouangrimm/kelk/blob/main/src/app/style/style.scss): ui assets · Global theme, page styles, and visual variables. · `src/app/style/style.scss`
- [Fonts](https://github.com/elouangrimm/kelk/blob/main/src/app/fonts/fonts.ts): asset bundle · Bundled font data and licenses for text rendering. · `src/app/fonts/fonts.ts`

### Painting core

Project state, tools, brushes, canvas rendering, history, storage, and editing operations.

- [Kelk state](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/kl.ts): core model · Central project and application state boundary. · `src/app/script/klecks/kl.ts`
- [Core types](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/kl-types.ts): type boundary · Shared type definitions for the painting domain. · `src/app/script/klecks/kl-types.ts`
- [Config](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/kl-config.ts): runtime config · Application configuration and feature/runtime settings. · `src/app/script/klecks/kl-config.ts`
- [Brush engine](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/brushes/brushes.ts): paint engine · Brush behaviors including pen, blend, sketchy, pixel, chemy, smudge, and eraser. · `src/app/script/klecks/brushes/brushes.ts`
- [Brush UI](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/brushes-ui/brushes-ui.ts): controls · Brush settings panels and brush-specific controls. · `src/app/script/klecks/brushes-ui/brushes-ui.ts`
- [Canvas core](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/canvas/kl-canvas.ts): raster pipeline · Painting, compositing, sampling, and layer update operations. · `src/app/script/klecks/canvas/kl-canvas.ts`
- [History](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/history/kl-history.ts): undo/redo · Undo/redo execution and fine-grained project change tracking. · `src/app/script/klecks/history/kl-history.ts`
- [Storage](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/storage/project-store.ts): persistence/export · Project persistence, PSD conversion, local save/load, and browser storage. · `src/app/script/klecks/storage/project-store.ts`

### Interaction

Input normalization, gesture handling, selection geometry, and transforms.

- [Input chain](https://github.com/elouangrimm/kelk/blob/main/src/app/script/bb/input/event-chain/event-chain.ts): event pipeline · Pointer, key, gesture, wheel, and pressure normalization pipeline. · `src/app/script/bb/input/event-chain/event-chain.ts`
- [Geometry](https://github.com/elouangrimm/kelk/blob/main/src/app/script/bb/multi-polygon/multi-polygon-from-rect.ts): math helpers · Multi-polygon selection and transform geometry helpers. · `src/app/script/bb/multi-polygon/multi-polygon-from-rect.ts`
- [Selection tools](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/select-tool/select-tool.ts): selection/transform · Selection and transform interaction tools. · `src/app/script/klecks/select-tool/select-tool.ts`

### Effects

GPU effect pipeline and app-level filters/image operations.

- [FX canvas](https://github.com/elouangrimm/kelk/blob/main/src/app/script/fx-canvas/fx-canvas.ts): webgl effects · WebGL effect infrastructure, shaders, textures, and shared FX plumbing. · `src/app/script/fx-canvas/fx-canvas.ts`
- [Filters](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/filters/filters.ts): edit filters · App-level image filters and transformation workflows. · `src/app/script/klecks/filters/filters.ts`
- [Image ops](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/image-operations/flood-fill.ts): tools · Flood fill, text rendering, grid, vanish point, gradient, and shape operations. · `src/app/script/klecks/image-operations/flood-fill.ts`

### UI

Reusable widgets, easel surface, project viewport, tool tabs, mobile, and modals.

- [Easel](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/easel/easel.ts): interaction surface · Primary drawing surface and tool interaction layer. · `src/app/script/klecks/ui/easel/easel.ts`
- [Project view](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/project-viewport/project-viewport.ts): preview/render · Project preview rendering, FX preview, and viewport presentation. · `src/app/script/klecks/ui/project-viewport/project-viewport.ts`
- [Tool tabs](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/tool-tabs/file-ui.ts): workspace ui · File, fill, filters, layers, selection, settings, shapes, text, and related workflows. · `src/app/script/klecks/ui/tool-tabs/file-ui.ts`
- [UI components](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/components/checkbox.ts): widgets · Reusable controls, overlays, sliders, dialogs, and layout primitives. · `src/app/script/klecks/ui/components/checkbox.ts`
- [Mobile UI](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/mobile/mobile-ui.ts): responsive ui · Mobile-specific layout and toolspace behavior. · `src/app/script/klecks/ui/mobile/mobile-ui.ts`
- [Modals](https://github.com/elouangrimm/kelk/blob/main/src/app/script/klecks/ui/modals/show-import-image-dialog.ts): dialogs · File import, clipboard, licenses, text tool, upload, and other modal workflows. · `src/app/script/klecks/ui/modals/show-import-image-dialog.ts`

### Assets

Language and font assets bundled with the client app.

- [Languages](https://github.com/elouangrimm/kelk/blob/main/src/app/script/language/language.ts): localization · Localized string sources and runtime language selection. · `src/app/script/language/language.ts`

## Connections

- Standalone app → App wiring: boots · Standalone entrypoint starts the app shell.
- App wiring → Kelk state: initializes · Boot wiring creates and coordinates the main app state.
- App wiring → Theme & styles: loads · Application shell applies theme and global styles.
- App wiring → Languages: localizes · Runtime selects translated UI strings.
- App wiring → Modals: opens · Shell routes import and setup workflows into dialogs.
- Kelk state → Core types: uses · Core state is defined by shared domain types.
- Kelk state → Config: reads · State and runtime behavior depend on central config.
- Kelk state → Brush engine: coordinates · App state drives brush behavior and active tool state.
- Kelk state → Canvas core: mutates · Brush strokes and edits apply through the canvas pipeline.
- Kelk state → History: records · Project changes are pushed into undo/redo history.
- Kelk state → Storage: persists · Projects are saved, loaded, and exported through storage.
- Brush UI → Brush engine: configures · Brush settings panels control brush engine parameters.
- Input chain → Easel: feeds · Normalized input is consumed by the drawing surface.
- Input chain → Selection tools: drives · Gestures and pointer events feed selection and transform tools.
- Input chain → Brush engine: streams · Pointer and pressure data become brush stroke input.
- Geometry → Selection tools: supports · Selection and transform tools use polygon and transform helpers.
- Selection tools → Canvas core: applies · Selections and transforms alter project pixels and layers.
- Easel → Canvas core: renders via · The easel paints strokes and tool interactions into the canvas layer.
- Easel → Image ops: invokes · Tools like bucket, gradient, shape, and text trigger image operations.
- Project view → FX canvas: previews · Viewport includes FX preview rendering for effects.
- Filters → FX canvas: executes on · App filters use the effect canvas and shader infrastructure.
- Filters → Canvas core: updates · Filter workflows apply changes to project canvas data.
- Tool tabs → Filters: exposes · Filter workflows are surfaced in the workspace tabs.
- Tool tabs → History: commits · Editing workflows push undoable actions into history.
- Tool tabs → Storage: saves · File workflows connect to persistence and export.
- UI components → Easel: compose · Shared UI widgets are used to build the easel surface.
- UI components → Tool tabs: compose · Shared widgets support the tool tab workspace.
- Mobile UI → Easel: adapts · Mobile layout changes the easel and toolspace ergonomics.
- Modals → Storage: imports/exports · Dialogs mediate file and clipboard boundaries.
