# shanorigin/shantanujs architecture

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

- Interactive diagram: https://gitdiagram.com/shanorigin/shantanujs
- Repository: https://github.com/shanorigin/shantanujs

## Overview

ShantanuJS is a browser-based 2D graphics and animation library that projects a matrix-driven scene onto SVG. The principal workflow is: consumer creates shapes and adds them to a Canvas; scene ownership and render-node state track changes; the frame Engine resolves transforms and submits nodes to the SVG renderer; pointer events are dispatched through the event system. Other documented capabilities include groups, media, filters, affine transforms, animation, and typed APIs. Relationships below rely on README statements and the cited excerpts; several subsystem implementations were not sampled.

Main entry points: [`src/graphics/render-node/render-node.ts`](https://github.com/shanorigin/shantanujs/blob/main/src/graphics/render-node/render-node.ts) (Render node), [`src/systems/canvas/canvas.ts`](https://github.com/shanorigin/shantanujs/blob/main/src/systems/canvas/canvas.ts) (Canvas), [`src/index/index.ts`](https://github.com/shanorigin/shantanujs/blob/main/src/index/index.ts) (Public API), [`src/systems/engine/engine.ts`](https://github.com/shanorigin/shantanujs/blob/main/src/systems/engine/engine.ts) (Frame engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public graphics API"]
  node_public_api["Public API<br/>[index.ts]"]
  node_canvas["Canvas<br/>[canvas.ts]"]
  node_shapes["Shapes and media"]
  node_group["Group<br/>[group.ts]"]
  node_contracts["Type contracts"]
end

subgraph group_state["Scene and state"]
  node_scene["Scene model<br/>[scene-model.ts]"]
  node_render_node["Render node<br/>[render-node.ts]"]
  node_graphics_model["Graphics model<br/>[graphics-model.ts]"]
  node_properties["Property definitions"]
  node_internal_keys["Internal access keys"]
  node_diagnostics["Error diagnostics<br/>[error-context.ts]"]
end

subgraph group_runtime["Frame and rendering"]
  node_engine["Frame engine<br/>[engine.ts]"]
  node_renderer["Renderer dispatch<br/>[renderer.ts]"]
  node_svg_renderer["SVG renderer<br/>[svg-renderer.ts]"]
  node_svg_dom["SVG DOM"]
  node_events["Event system<br/>[event-system.ts]"]
end

subgraph group_capabilities["Graphics capabilities"]
  node_transformation["Transform component<br/>[transformation.ts]"]
  node_animation["Animation component<br/>[animation.ts]"]
  node_filters["SVG filters<br/>[filters.ts]"]
  node_math["Affine and matrix math"]
  node_colors["Color utilities<br/>[colors.ts]"]
end

node_consumer(("Application code"))

node_consumer -->|"imports"| node_public_api
node_consumer -->|"creates"| node_canvas
node_consumer -->|"creates"| node_shapes
node_consumer -->|"adds shapes"| node_canvas
node_public_api -->|"exports"| node_canvas
node_public_api -->|"exports"| node_shapes
node_public_api -->|"exports"| node_group
node_canvas -->|"initializes"| node_scene
node_canvas -->|"initializes"| node_renderer
node_canvas -->|"starts"| node_engine
node_canvas -->|"connects pointer input"| node_events
node_scene -->|"owns scene nodes"| node_render_node
node_render_node -->|"holds model state"| node_graphics_model
node_render_node -->|"creates component"| node_transformation
node_render_node -->|"creates component"| node_animation
node_render_node -->|"exposes component"| node_filters
node_render_node -->|"uses definitions"| node_properties
node_render_node -->|"uses access keys"| node_internal_keys
node_group -->|"extends model"| node_render_node
node_group -->|"uses transforms"| node_transformation
node_transformation -->|"parses affine expressions"| node_math
node_engine -->|"reads scene"| node_scene
node_engine -->|"multiplies matrices"| node_math
node_engine -->|"renders nodes"| node_renderer
node_renderer -->|"dispatches rendering"| node_svg_renderer
node_svg_renderer -->|"patches attributes"| node_svg_dom
node_canvas -->|"dispatches pointers"| node_events
node_events -->|"targets nodes"| node_render_node
node_scene -->|"uses colors"| node_colors
node_contracts -.->|"specifies API"| node_canvas
node_diagnostics -.->|"supports errors"| node_graphics_model

click node_public_api "https://github.com/shanorigin/shantanujs/blob/main/src/index/index.ts"
click node_canvas "https://github.com/shanorigin/shantanujs/blob/main/src/systems/canvas/canvas.ts"
click node_shapes "https://github.com/shanorigin/shantanujs/tree/main/src/graphics/shapes"
click node_group "https://github.com/shanorigin/shantanujs/blob/main/src/graphics/container/group/group.ts"
click node_contracts "https://github.com/shanorigin/shantanujs/tree/main/src/models/interfaces"
click node_scene "https://github.com/shanorigin/shantanujs/blob/main/src/systems/scene/scene-model.ts"
click node_render_node "https://github.com/shanorigin/shantanujs/blob/main/src/graphics/render-node/render-node.ts"
click node_graphics_model "https://github.com/shanorigin/shantanujs/blob/main/src/core/graphics-model/graphics-model.ts"
click node_properties "https://github.com/shanorigin/shantanujs/tree/main/src/property-definitions"
click node_internal_keys "https://github.com/shanorigin/shantanujs/tree/main/src/internal/keys"
click node_diagnostics "https://github.com/shanorigin/shantanujs/blob/main/src/errors/core/diagnostics/error-context.ts"
click node_engine "https://github.com/shanorigin/shantanujs/blob/main/src/systems/engine/engine.ts"
click node_renderer "https://github.com/shanorigin/shantanujs/blob/main/src/systems/renderer/renderer.ts"
click node_svg_renderer "https://github.com/shanorigin/shantanujs/blob/main/src/systems/renderer/svg/svg-renderer/svg-renderer.ts"
click node_events "https://github.com/shanorigin/shantanujs/blob/main/src/systems/event/event-system.ts"
click node_transformation "https://github.com/shanorigin/shantanujs/blob/main/src/components/transformation/transformation.ts"
click node_animation "https://github.com/shanorigin/shantanujs/blob/main/src/components/animation/animation.ts"
click node_filters "https://github.com/shanorigin/shantanujs/blob/main/src/components/filter/filters.ts"
click node_math "https://github.com/shanorigin/shantanujs/tree/main/src/utils/math"
click node_colors "https://github.com/shanorigin/shantanujs/blob/main/src/utils/colors/colors.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_public_api,node_canvas,node_shapes,node_group,node_contracts toneBlue
class node_scene,node_render_node,node_graphics_model,node_properties,node_internal_keys,node_diagnostics toneAmber
class node_engine,node_renderer,node_svg_renderer,node_svg_dom,node_events toneMint
class node_transformation,node_animation,node_filters,node_math,node_colors toneRose
class node_consumer toneIndigo
```

## Components

### Public graphics API

- [Public API](https://github.com/shanorigin/shantanujs/blob/main/src/index/index.ts): `src/index/index.ts`
- [Canvas](https://github.com/shanorigin/shantanujs/blob/main/src/systems/canvas/canvas.ts): `src/systems/canvas/canvas.ts`
- [Shapes and media](https://github.com/shanorigin/shantanujs/tree/main/src/graphics/shapes): `src/graphics/shapes`
- [Group](https://github.com/shanorigin/shantanujs/blob/main/src/graphics/container/group/group.ts): `src/graphics/container/group/group.ts`
- [Type contracts](https://github.com/shanorigin/shantanujs/tree/main/src/models/interfaces): `src/models/interfaces`

### Scene and state

- [Scene model](https://github.com/shanorigin/shantanujs/blob/main/src/systems/scene/scene-model.ts): `src/systems/scene/scene-model.ts`
- [Render node](https://github.com/shanorigin/shantanujs/blob/main/src/graphics/render-node/render-node.ts): `src/graphics/render-node/render-node.ts`
- [Graphics model](https://github.com/shanorigin/shantanujs/blob/main/src/core/graphics-model/graphics-model.ts): `src/core/graphics-model/graphics-model.ts`
- [Property definitions](https://github.com/shanorigin/shantanujs/tree/main/src/property-definitions): `src/property-definitions`
- [Internal access keys](https://github.com/shanorigin/shantanujs/tree/main/src/internal/keys): `src/internal/keys`
- [Error diagnostics](https://github.com/shanorigin/shantanujs/blob/main/src/errors/core/diagnostics/error-context.ts): `src/errors/core/diagnostics/error-context.ts`

### Frame and rendering

- [Frame engine](https://github.com/shanorigin/shantanujs/blob/main/src/systems/engine/engine.ts): `src/systems/engine/engine.ts`
- [Renderer dispatch](https://github.com/shanorigin/shantanujs/blob/main/src/systems/renderer/renderer.ts): `src/systems/renderer/renderer.ts`
- [SVG renderer](https://github.com/shanorigin/shantanujs/blob/main/src/systems/renderer/svg/svg-renderer/svg-renderer.ts): `src/systems/renderer/svg/svg-renderer/svg-renderer.ts`
- **SVG DOM**
- [Event system](https://github.com/shanorigin/shantanujs/blob/main/src/systems/event/event-system.ts): `src/systems/event/event-system.ts`

### Graphics capabilities

- [Transform component](https://github.com/shanorigin/shantanujs/blob/main/src/components/transformation/transformation.ts): `src/components/transformation/transformation.ts`
- [Animation component](https://github.com/shanorigin/shantanujs/blob/main/src/components/animation/animation.ts): `src/components/animation/animation.ts`
- [SVG filters](https://github.com/shanorigin/shantanujs/blob/main/src/components/filter/filters.ts): `src/components/filter/filters.ts`
- [Affine and matrix math](https://github.com/shanorigin/shantanujs/tree/main/src/utils/math): `src/utils/math`
- [Color utilities](https://github.com/shanorigin/shantanujs/blob/main/src/utils/colors/colors.ts): `src/utils/colors/colors.ts`

### Other components

- **Application code**

## Connections

- Application code → Public API: imports (evidence: `README.md`)
- Application code → Canvas: creates (evidence: `README.md`)
- Application code → Shapes and media: creates (evidence: `README.md`)
- Application code → Canvas: adds shapes (evidence: `README.md`)
- Public API → Canvas: exports (evidence: `src/index/index.ts`)
- Public API → Shapes and media: exports (evidence: `src/index/index.ts`)
- Public API → Group: exports (evidence: `src/index/index.ts`)
- Canvas → Scene model: initializes (evidence: `src/systems/canvas/canvas.ts`)
- Canvas → Renderer dispatch: initializes (evidence: `src/systems/canvas/canvas.ts`)
- Canvas → Frame engine: starts (evidence: `README.md`)
- Canvas → Event system: connects pointer input (evidence: `README.md`)
- Scene model → Render node: owns scene nodes (evidence: `README.md`)
- Render node → Graphics model: holds model state (evidence: `src/graphics/render-node/render-node.ts`)
- Render node → Transform component: creates component (evidence: `src/graphics/render-node/render-node.ts`)
- Render node → Animation component: creates component (evidence: `src/graphics/render-node/render-node.ts`)
- Render node → SVG filters: exposes component (evidence: `README.md`)
- Render node → Property definitions: uses definitions (evidence: `src/graphics/render-node/render-node.ts`)
- Render node → Internal access keys: uses access keys (evidence: `src/graphics/render-node/render-node.ts`)
- Group → Render node: extends model (evidence: `src/graphics/container/group/group.ts`)
- Group → Transform component: uses transforms (evidence: `src/graphics/container/group/group.ts`)
- Transform component → Affine and matrix math: parses affine expressions (evidence: `src/components/transformation/transformation.ts`)
- Frame engine → Scene model: reads scene (evidence: `src/systems/engine/engine.ts`)
- Frame engine → Affine and matrix math: multiplies matrices (evidence: `src/systems/engine/engine.ts`)
- Frame engine → Renderer dispatch: renders nodes (evidence: `README.md`)
- Renderer dispatch → SVG renderer: dispatches rendering (evidence: `README.md`)
- SVG renderer → SVG DOM: patches attributes (evidence: `README.md`)
- Canvas → Event system: dispatches pointers (evidence: `src/systems/canvas/canvas.ts`)
- Event system → Render node: targets nodes (evidence: `README.md`)
- Scene model → Color utilities: uses colors (evidence: `src/systems/scene/scene-model.ts`)
- Type contracts → Canvas: specifies API
- Error diagnostics → Graphics model: supports errors
