# chanind/hanzi-writer architecture

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

- Interactive diagram: https://gitdiagram.com/chanind/hanzi-writer
- Repository: https://github.com/chanind/hanzi-writer

## Overview

##### Project Type and Purpose
- Hanzi Writer is a JavaScript library focused on animating Chinese character stroke orders and offering stroke order practice quizzes.
- It is not a full-stack web application but a front-end library that can be embedded into web pages. It also provides a demo (in the demo folder) and has a modular internal structure for rendering and logic.

##### File Structure
- Notice the clear segmentation: a top-level source directory (src) for main code and a demo directory that demonstrates usage.
- Within src, key files like HanziWriter.ts, LoadingManager.ts, Quiz.ts, Mutation.ts, and RenderState.ts indicate core functionality (orchestration, resource management, user interaction logic, and animation/rendering state).
- The presence of two distinct renderer folders (renderers/canvas and renderers/svg) shows that the library supports multiple rendering backends. Each renderer folder contains base components (like HanziWriterRenderer, StrokeRenderer, etc.) along with a set of tests in their respective __tests__ folders.
- The models directory (e.g., Character.ts, Stroke.ts) encapsulates the data structures used by the library.
- Utility files (e.g., geometry.ts, utils.ts) and configurations (e.g., rollup.config.js, babel.config.js, tsconfig.json) further provide insights into build, transformation, and testing aspects.

##### README for Additional Insights
- The documentation highlights that its key functionality is stroke order animation and interactive quizzes.
- It explains that the character data comes from a related data repository (Hanzi Writer Data) based on the "Make me a Hanzi" project.
- Instructions for building, testing, and contributing are provided which imply that the project is well modularized.

a. Main components:
- Core Library API (HanziWriter.ts): Acts as the entry point for users of the library. Represent this as the central component.
- Logic and Service Modules: Include modules like LoadingManager (managing resource loading such as SVG data), Quiz (handling stroke order quiz interactions), Mutation, and RenderState for maintaining state during animations.
- Data Models: Modules in the models directory (e.g., Character, Stroke, UserStroke) that capture the structure of stroke data.
- Rendering Engines: Two major renderer systems – one for Canvas (located under renderers/canvas) and one for SVG (located under renderers/svg). Each will have its own specialized components: CharacterRenderer, HanziWriterRenderer, StrokeRenderer, and additional utility modules for drawing.
- Utilities & Helpers: Shared functions and utilities (e.g., geometry calculations and other helper functions) that support rendering and user interaction.
- Demo/Example: The demo folder contains a simple HTML/JS example to show integration and usage.

b. Relationships and Interactions:
- The core API (HanziWriter.ts) interacts with the LoadingManager to load SVG and stroke order data.
- Once data is loaded, the core API chooses an appropriate rendering engine based on user configuration – either Canvas or SVG.
- The rendering engine uses data models to interpret character structure and draws the stroke animations.
- The Quiz module uses the drawing routines and user interactions; it communicates with the rendering system to provide immediate feedback.
- All modules interact through clearly defined APIs and utility functions that handle mathematical (geometry.ts) and state operations (RenderState.ts).

c. Architectural Patterns and Design Principles:
- Modular and Separated Concerns: The separation of the core library logic from the rendering-specific details (canvas vs. SVG) illustrates a layered architecture.
- Extensibility: The use of base renderer classes (e.g., HanziWriterRendererBase) allows extension by other rendering implementations.
- Testability: A robust test infrastructure is seen in the __tests__ folders spread across the project, indicating test-driven design.

d. Technologies, Frameworks, or Libraries:
- JavaScript/TypeScript (with tsconfig.json indicating TypeScript usage).
- Build Tools: Babel and Rollup are used for compilation and bundling.
- Testing: Jest is evident from configuration files (jest-setup.js, jest-jsdom-env.js) and numerous test files.
- Linting and Formatting: ESLint and Prettier configurations indicate stylistic and static analysis enforcement.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Components"
        core["Core API (HanziWriter.ts)"]:::service
        loading["Loading Manager"]:::service
        quiz["Quiz Module"]:::service
        mutation["Mutation Handling"]:::service
        state["Render State Management"]:::service
    end

    subgraph "Data Models"
        data_char["Character Model"]:::model
        data_stroke["Stroke Model"]:::model
        data_user["User Stroke Model"]:::model
    end

    subgraph "Canvas Rendering Engine"
        canvas_char["Canvas Character Renderer"]:::renderer
        canvas_hanzi["Canvas HanziWriter Renderer"]:::renderer
        canvas_stroke["Canvas Stroke Renderer"]:::renderer
        canvas_target["Canvas Render Target"]:::renderer
        canvas_util["Canvas Utilities"]:::renderer
    end

    subgraph "SVG Rendering Engine"
        svg_char["SVG Character Renderer"]:::renderer
        svg_hanzi["SVG HanziWriter Renderer"]:::renderer
        svg_stroke["SVG Stroke Renderer"]:::renderer
        svg_user["SVG User Stroke Renderer"]:::renderer
        svg_target["SVG Render Target"]:::renderer
        svg_util["SVG Utilities"]:::renderer
    end

    subgraph "Utilities & Helpers"
        geometry["Geometry Utilities"]:::utility
        utils["General Utilities"]:::utility
    end

    subgraph "Demo/Example Integration"
        demo["Demo/Example"]:::demo
    end

    %% Connections between Core Components
    core -->|"loads_data"| loading
    core -->|"initiates_quiz"| quiz
    core -->|"handles_mutation"| mutation
    core -->|"updates_state"| state
    core -->|"renders_canvas"| canvas_hanzi
    core -->|"renders_svg"| svg_hanzi

    %% Interaction between Quiz Module and Core API
    quiz -->|"sends_input"| core
    quiz -->|"updates_state"| state

    %% Renderers using Data Models
    canvas_hanzi -->|"uses_model"| data_char
    svg_hanzi -->|"uses_model"| data_char

    %% Renderers utilizing their utilities
    canvas_hanzi -->|"calls_canvasUtils"| canvas_util
    svg_hanzi -->|"calls_svgUtils"| svg_util

    %% Core and Loading using Utilities
    core -->|"uses_geometry"| geometry
    loading -->|"utilizes_utilities"| utils

    %% Demo Integration consuming Core API
    demo -->|"consumes_API"| core

    %% Styling Classes
    classDef service fill:#a3d5d3,stroke:#333,stroke-width:2px;
    classDef model fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef renderer fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef utility fill:#fadbd8,stroke:#333,stroke-width:2px;
    classDef demo fill:#d2b4de,stroke:#333,stroke-width:2px;

    %% Click Events for Core Components
    click core "https://github.com/chanind/hanzi-writer/blob/master/src/HanziWriter.ts"
    click loading "https://github.com/chanind/hanzi-writer/blob/master/src/LoadingManager.ts"
    click quiz "https://github.com/chanind/hanzi-writer/blob/master/src/Quiz.ts"
    click mutation "https://github.com/chanind/hanzi-writer/blob/master/src/Mutation.ts"
    click state "https://github.com/chanind/hanzi-writer/blob/master/src/RenderState.ts"

    %% Click Events for Data Models
    click data_char "https://github.com/chanind/hanzi-writer/blob/master/src/models/Character.ts"
    click data_stroke "https://github.com/chanind/hanzi-writer/blob/master/src/models/Stroke.ts"
    click data_user "https://github.com/chanind/hanzi-writer/blob/master/src/models/UserStroke.ts"

    %% Click Events for Canvas Rendering Engine
    click canvas_char "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/canvas/CharacterRenderer.ts"
    click canvas_hanzi "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/canvas/HanziWriterRenderer.ts"
    click canvas_stroke "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/canvas/StrokeRenderer.ts"
    click canvas_target "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/canvas/RenderTarget.ts"
    click canvas_util "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/canvas/canvasUtils.ts"

    %% Click Events for SVG Rendering Engine
    click svg_char "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/svg/CharacterRenderer.ts"
    click svg_hanzi "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/svg/HanziWriterRenderer.ts"
    click svg_stroke "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/svg/StrokeRenderer.ts"
    click svg_user "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/svg/UserStrokeRenderer.ts"
    click svg_target "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/svg/RenderTarget.ts"
    click svg_util "https://github.com/chanind/hanzi-writer/blob/master/src/renderers/svg/svgUtils.ts"

    %% Click Events for Utilities & Helpers
    click geometry "https://github.com/chanind/hanzi-writer/blob/master/src/geometry.ts"
    click utils "https://github.com/chanind/hanzi-writer/blob/master/src/utils.ts"

    %% Click Event for Demo Integration
    click demo "https://github.com/chanind/hanzi-writer/tree/master/demo"
```
