# dnisdv/ascii-editor architecture

> Architecture diagram of the GitHub repository dnisdv/ascii-editor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dnisdv/ascii-editor
- Repository: https://github.com/dnisdv/ascii-editor

## Overview

##### Project type and purpose
- This is a browser-based, single-page ASCII art editor built with SvelteKit.
- It uses CanvasKit (Skia + WebAssembly) for canvas rendering, Redux Toolkit for state management, and localStorage for persistence.

##### File structure
- Top-level “src/routes” directory: SvelteKit routing (layout, pages).
- “src/components”, “src/views”: UI components and view assemblies.
- “src/store”: Redux Toolkit slices (document, layers, tools) and hooks.
- “src/bus”: an event-bus layer to decouple UI events and core logic.
- “src/editor”: core domain logic (canvas, camera, tools, history, serialization).
- “src/api/documents”: persistence API using localStorage.
- Config/bundler files: Vite, Tailwind, Docker, GitHub Actions.

##### Extract architectural insights from the README
- Single-page app with multi-layer ASCII canvas.
- Undo/Redo via history manager.
- Light/Dark theme support.
- Persistence in browser localStorage.

##### Main components & their interactions
a. Presentation Layer (Browser)
- SvelteKit routes → Layouts (+layout.svelte), Pages (Editor.svelte, Canvas.svelte)
- Views & re-usable UI components (buttons, menus, dialogs)
b. State Management
- Redux Toolkit store with three slices: document, layers, tools
- Hooks (useSelector, useDispatch) connect UI to store
c. Event Bus
- EditorBusProvider and individual buses (layers, notifications, tools)
- Decouples UI events from core logic
d. Editor Core
- Canvas manager using CanvasKit WASM → renders grid, ASCII characters
- History manager for undo/redo
- Camera & cursor modules
- Spatial indexing (spatial-hashmap) for performance
e. Persistence/API
- Document API abstracts localStorage reads/writes
- Serializer transforms in-memory models to JSON and back
f. External Dependencies
- CanvasKit WASM (Skia)
- SvelteKit, Vite, Tailwind CSS
- Docker for containerization, GitHub Actions for CI/CD

##### Architectural patterns & design principles
- Layered architecture: Presentation → State → Domain → Persistence
- Event-driven communication via an in-process event bus
- Unidirectional data flow (Redux Toolkit)
- Separation of concerns: UI components vs. editor core logic vs. persistence

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Layout["+layout.svelte"]:::ui
        EditorPage["Editor.svelte"]:::ui
        CanvasPage["Canvas.svelte"]:::ui
        Components["src/components"]:::ui
        Views["src/views"]:::ui
    end

    %% State & Event Bus Layer
    subgraph "State Management & Event Bus"
        direction TB
        subgraph "Redux Store" 
            direction TB
            StoreTS["store.ts"]:::state
            DocSlice["document.slice.ts"]:::state
            LayersSlice["layers.slice.ts"]:::state
            ToolsSlice["tool.slice.ts"]:::state
            UseDispatch["useDispatch.ts"]:::state
            UseSelector["useSelector.ts"]:::state
        end
        subgraph "Event Bus"
            direction TB
            EditorBusProvider["EditorBusProvider.svelte"]:::bus
            ToolsBus["editor-tools.bus.ts"]:::bus
            LayersBus["editor-layers.bus.ts"]:::bus
            NotificationsBus["editor-notifications.bus.ts"]:::bus
        end
    end

    %% Domain / Core Layer
    subgraph "Editor Core"
        direction TB
        subgraph "Canvas & Rendering"
            direction TB
            CanvasTS["canvas.ts"]:::core
            GridTS["grid.ts"]:::core
            AsciiTS["ascii.ts"]:::core
            RenderManager["render-manager.ts"]:::core
        end
        Camera["camera.ts"]:::core
        Cursor["cursor.ts"]:::core
        subgraph "History Manager"
            direction TB
            HistoryManager["history-manager.ts"]:::core
            HistoryFiles["src/editor/history"]:::core
        end
        subgraph "Tool Manager & Tools"
            direction TB
            ToolManager["tool-manager.ts"]:::core
            ToolsFolder["src/editor/tools"]:::core
        end
        SpatialIndex["spatial-hashmap.ts"]:::core
        subgraph "Serializer"
            direction TB
            SerializerIndex["index.ts"]:::core
            DocSerializer["document.serializer.ts"]:::core
            LayerSerializer["layer.serializer.ts"]:::core
            HistoryMgrSerializer["historyManager.serializer.ts"]:::core
        end
    end

    %% Persistence Layer
    subgraph "Persistence / API"
        direction TB
        DBLocal["db-localstorage.ts"]:::persistence
        DocumentAPI["document-api.ts"]:::persistence
        LayersAPI["layers-api.ts"]:::persistence
        ToolsConfigAPI["tools-config-api.ts"]:::persistence
    end

    %% External Dependencies
    subgraph "External & Config"
        direction TB
        CanvasKit["CanvasKit WASM"]:::external
        Vite["vite.config.ts"]:::external
        Tailwind["tailwind.config.ts"]:::external
        Dockerfile["Dockerfile"]:::external
        CI[".github/workflows/playwright.yml"]:::external
    end

    %% Flow Arrows
    Layout -->|"renders"| EditorPage
    Layout -->|"renders"| CanvasPage
    EditorPage -->|"dispatch actions"| StoreTS
    CanvasPage -->|"dispatch actions"| StoreTS
    Components -->|"used by"| EditorPage
    Views -->|"used by"| EditorPage

    StoreTS -->|"state updates"| EditorPage
    StoreTS -->|"state updates"| CanvasPage

    EditorPage -->|"emit events"| EditorBusProvider
    EditorPage -->|"emit events"| ToolsBus
    EditorPage -->|"emit events"| LayersBus

    EditorBusProvider -->|"/bus events"| CanvasTS
    ToolsBus -->|"/bus events"| ToolManager
    LayersBus -->|"/bus events"| HistoryManager

    CanvasTS -->|"renders via"| CanvasKit
    RenderManager -->|"calls"| CanvasTS

    ToolManager -->|"manages tools"| ToolsFolder
    Camera -->|"controls viewport"| RenderManager
    Cursor -->|"tracks pointer"| CanvasTS

    HistoryManager -->|"store history via"| StoreTS
    StoreTS -->|"persist state"| DocumentAPI
    DocumentAPI -->|"read/write"| DBLocal
    DocumentAPI -->|"reads/writes"| LayersAPI
    DocumentAPI -->|"reads/writes"| ToolsConfigAPI

    StoreTS -->|"serialize on save"| SerializerIndex
    SerializerIndex -->|"uses"| DocSerializer
    SerializerIndex -->|"uses"| LayerSerializer
    SerializerIndex -->|"uses"| HistoryMgrSerializer

    SpatialIndex -->|"optimized lookup"| CanvasTS

    Vite -->|"builds"| Layout
    Tailwind -->|"styles"| Components
    Dockerfile -->|"containerizes"| Layout
    CI -->|"tests & deploys"| Dockerfile

    %% Click Events
    click Layout "https://github.com/dnisdv/ascii-editor/blob/main/src/routes/+layout.svelte"
    click EditorPage "https://github.com/dnisdv/ascii-editor/blob/main/src/routes/Editor.svelte"
    click CanvasPage "https://github.com/dnisdv/ascii-editor/blob/main/src/routes/Canvas.svelte"
    click Components "https://github.com/dnisdv/ascii-editor/tree/main/src/components"
    click Views "https://github.com/dnisdv/ascii-editor/tree/main/src/views"
    click StoreTS "https://github.com/dnisdv/ascii-editor/blob/main/src/store/store.ts"
    click DocSlice "https://github.com/dnisdv/ascii-editor/blob/main/src/store/slices/document/document.slice.ts"
    click LayersSlice "https://github.com/dnisdv/ascii-editor/blob/main/src/store/slices/layers/layers.slice.ts"
    click ToolsSlice "https://github.com/dnisdv/ascii-editor/blob/main/src/store/slices/tools/tool.slice.ts"
    click UseDispatch "https://github.com/dnisdv/ascii-editor/blob/main/src/store/useDispatch.ts"
    click UseSelector "https://github.com/dnisdv/ascii-editor/blob/main/src/store/useSelector.ts"
    click EditorBusProvider "https://github.com/dnisdv/ascii-editor/blob/main/src/bus/EditorBusProvider.svelte"
    click ToolsBus "https://github.com/dnisdv/ascii-editor/blob/main/src/bus/editor-tools.bus.ts"
    click LayersBus "https://github.com/dnisdv/ascii-editor/blob/main/src/bus/editor-layers.bus.ts"
    click NotificationsBus "https://github.com/dnisdv/ascii-editor/blob/main/src/bus/editor-notifications.bus.ts"
    click CanvasTS "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/canvas/canvas.ts"
    click GridTS "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/canvas/grid.ts"
    click AsciiTS "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/canvas/ascii.ts"
    click RenderManager "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/render-manager.ts"
    click Camera "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/camera.ts"
    click Cursor "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/cursor.ts"
    click HistoryManager "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/history-manager.ts"
    click HistoryFiles "https://github.com/dnisdv/ascii-editor/tree/main/src/editor/history"
    click ToolManager "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/tool-manager.ts"
    click ToolsFolder "https://github.com/dnisdv/ascii-editor/tree/main/src/editor/tools"
    click SpatialIndex "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/spatial-hashmap.ts"
    click SerializerIndex "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/serializer/index.ts"
    click DocSerializer "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/serializer/document.serializer.ts"
    click LayerSerializer "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/serializer/layer.serializer.ts"
    click HistoryMgrSerializer "https://github.com/dnisdv/ascii-editor/blob/main/src/editor/serializer/historyManager.serializer.ts"
    click DBLocal "https://github.com/dnisdv/ascii-editor/blob/main/src/api/documents/db-localstorage.ts"
    click DocumentAPI "https://github.com/dnisdv/ascii-editor/blob/main/src/api/documents/document-api.ts"
    click LayersAPI "https://github.com/dnisdv/ascii-editor/blob/main/src/api/documents/layers-api.ts"
    click ToolsConfigAPI "https://github.com/dnisdv/ascii-editor/blob/main/src/api/documents/tools-config-api.ts"

    %% Styles
    classDef ui fill:#E3F2FD,stroke:#2196F3,color:#0D47A1;
    classDef state fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20;
    classDef bus fill:#FFF3E0,stroke:#FF9800,color:#E65100;
    classDef core fill:#F3E5F5,stroke:#9C27B0,color:#4A148C;
    classDef persistence fill:#ECEFF1,stroke:#607D8B,color:#263238;
    classDef external fill:#FFFDE7,stroke:#FFEB3B,color:#F57F17;
```
