# bbogdan-ov/pixma architecture

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

- Interactive diagram: https://gitdiagram.com/bbogdan-ov/pixma
- Repository: https://github.com/bbogdan-ov/pixma

## Overview

##### Project Type & Purpose
- Pixma is a front-end pixel art editor and is essentially a single-page application. It’s a rewrite of an earlier project (Pixel Share) but now focused solely on providing a rich editor interface without server-side complexities.
- The use of vanilla TypeScript, Vite, and Sass indicates a modern, performance-optimized frontend architecture that emphasizes modularity and extensibility (plugin support is already hinted at with a dedicated plugins folder).

##### Analyzing the File Structure
- Top-Level Files: Index.html acts as the entry point. Package.json, vite.config.ts, and tsconfig.json indicate configuration and build tooling.
- The src Directory: Contains the core application code. Important subdirectories include:
- src/App.ts and src/Editor.ts: Likely the main application and editor controller files.
- src/actions: Contains action files (app-actions, editor-actions) which hint at event-driven logic or state updates.
- src/base: Contains foundational components (BaseApp, UI elements, common utilities, maths, and other logic). This folder seems to define shared classes and infrastructure such as key binds, listable state management, and reusable UI elements.
- src/elements: Houses the UI components (e.g., AppElement, EditorElement, CanvasWrapper, Panels, and buttons) which form the visible parts of the UI.
- src/managers: Contains various managers responsible for controlling tools, layers, palettes, plugins, etc.
- src/utils and src/styles: Provide utility methods and styling instructions, which are essential for the interactive and visual parts of the editor.
- plugins: Contains scripts (test.js) to manage or test plugin functionalities.

##### Additional Insights from the README
- The README clarifies that Pixma is meant to be free and open source and it represents a major rewrite targeting a focused pixel art editor experience.
- It outlines future plans (animation, code-based image generation, plugin support, potential desktop app integration via Tauri) which hints at an architecture designed for extensibility.

a. Main Components:
- Application Entry Point: index.html loads the bundled code.
- Core Application & Editor: Represented by src/App.ts and src/Editor.ts, these manage overall app lifecycle and editor functionalities.
- UI Components/Elements: Derived from src/elements and src/base/elements. Include:
- Canvas and Drawing Layers
- Interactive Controls (buttons, toggles, inputs, etc.)
- Action Handlers & State Management: From src/actions and src/base/common/listenable. These dictate how user events propagate through the system.
- Managers: Represent the “brains” of specific capabilities (BrushesManager, LayersManager, ToolsManager, etc.) contained in src/managers. They control the logic for different tools and features.
- Plugin System: Indicated by the plugins folder and the PluginsManager in src/managers, this supports future extensibility.
- Utilities and Helpers: Located in src/utils and supporting files (math, misc, etc.) to perform common tasks.

b. Relationships and Interactions:
- The Application Entry Point initializes the core components, bootstrapping the App and Editor.
- UI Components interact with Managers to trigger changes and update rendering. For example, user inputs captured by Elements will dispatch actions (via files in src/actions) that in turn update states managed by the listens and triggers in src/base/common/listenable.
- Manager components aggregate and coordinate state changes, update the UI (through re-rendering or direct DOM manipulations), and handle specific operations like managing layers or switching tools.
- Utility modules support all components by providing shared functionality (drawing routines, DOM handling, random utilities, etc.).
- The plugin system hooks into the core logic (perhaps via the PluginsManager) to allow external modules to extend functionality.

c. Architectural Patterns:
- Modular and Component-Based Structure: The strict separation into directories (base, common, elements, managers) suggests a componentized approach.
- Event-Driven / Action-Based Architecture: The actions and listeners in the code highlight an event-driven design where state updates and UI reactions are decoupled.
- Separation of Concerns: Distinct layers separate core logic, UI rendering, state management, and utilities.
- Extensibility: The inclusion of a plugins folder and dedicated manager for plugins points toward a system built to allow additions without major rewrites.

d. Mention Technologies & Frameworks:
- TypeScript (for strong typing and modular code organization)
- Vite (modern, fast bundler)
- Sass (for modular styling)
- Vanilla DOM manipulation & potential integration with external libraries (as hinted in the README for future desktop integration via Tauri)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & Core
    subgraph "Entry & Core"
        entryPoint["Entry Point"]:::core
        subgraph "Core Application"
            app["App.ts"]:::core
            editor["Editor.ts"]:::core
        end
    end

    %% UI Components
    subgraph "UI Components"
        uiElements["UI Elements"]:::ui
        baseElements["Base Elements"]:::ui
    end

    %% Actions & State Management
    subgraph "Actions & State Management"
        actions["Action Handlers"]:::actions
        stateListeners["State Listeners"]:::actions
    end

    %% Managers
    subgraph "Managers"
        brushesMgr["BrushesManager"]:::managers
        layersMgr["LayersManager"]:::managers
        paletteMgr["PaletteManager"]:::managers
        pluginsMgr["PluginsManager"]:::managers
        projectsMgr["ProjectsManager"]:::managers
        toolsMgr["ToolsManager"]:::managers
        baseManagers["Base Managers"]:::managers
    end

    %% Domain Modules
    subgraph "Domain Modules"
        brushDomain["Brushes"]:::domain
        colorsDomain["Colors"]:::domain
        layersDomain["Layers"]:::domain
        projectsDomain["Projects"]:::domain
        toolsDomain["Tools"]:::domain
    end

    %% Plugin System
    subgraph "Plugin System"
        pluginScript["Plugin Script"]:::plugin
    end

    %% Utilities and Helpers
    subgraph "Utilities"
        utils["Utils"]:::utils
        baseUtils["Base Utils"]:::utils
    end

    %% Connections from Entry & Core to others
    entryPoint --> app
    entryPoint --> editor
    app --> actions
    editor --> actions
    app --> stateListeners
    editor --> stateListeners
    app --> uiElements
    editor --> uiElements

    %% UI Internal connection
    uiElements --- baseElements

    %% Connections from Actions to Managers
    actions --> brushesMgr
    actions --> layersMgr
    actions --> paletteMgr
    actions --> pluginsMgr
    actions --> projectsMgr
    actions --> toolsMgr
    stateListeners --> brushesMgr
    stateListeners --> layersMgr
    stateListeners --> toolsMgr

    %% Managers update UI
    brushesMgr --> uiElements
    layersMgr --> uiElements
    paletteMgr --> uiElements
    toolsMgr --> uiElements
    baseManagers --> uiElements

    %% Managers drive Domain Modules
    brushesMgr --> brushDomain
    layersMgr --> layersDomain
    paletteMgr --> colorsDomain
    projectsMgr --> projectsDomain
    toolsMgr --> toolsDomain

    %% Plugin Manager integration
    pluginsMgr --> pluginScript

    %% Utilities support Core and Managers
    utils --- app
    utils --- brushesMgr
    utils --- layersMgr
    baseUtils --- app
    baseUtils --- toolsMgr

    %% Click Events
    click entryPoint "https://github.com/bbogdan-ov/pixma/blob/master/index.html"
    click app "https://github.com/bbogdan-ov/pixma/blob/master/src/App.ts"
    click editor "https://github.com/bbogdan-ov/pixma/blob/master/src/Editor.ts"
    click actions "https://github.com/bbogdan-ov/pixma/tree/master/src/actions"
    click stateListeners "https://github.com/bbogdan-ov/pixma/tree/master/src/base/common/listenable"
    click uiElements "https://github.com/bbogdan-ov/pixma/tree/master/src/elements"
    click baseElements "https://github.com/bbogdan-ov/pixma/tree/master/src/base/elements"
    click brushesMgr "https://github.com/bbogdan-ov/pixma/blob/master/src/managers/BrushesManager.ts"
    click layersMgr "https://github.com/bbogdan-ov/pixma/blob/master/src/managers/LayersManager.ts"
    click paletteMgr "https://github.com/bbogdan-ov/pixma/blob/master/src/managers/PaletteManager.ts"
    click pluginsMgr "https://github.com/bbogdan-ov/pixma/blob/master/src/managers/PluginsManager.ts"
    click projectsMgr "https://github.com/bbogdan-ov/pixma/blob/master/src/managers/ProjectsManager.ts"
    click toolsMgr "https://github.com/bbogdan-ov/pixma/blob/master/src/managers/ToolsManager.ts"
    click baseManagers "https://github.com/bbogdan-ov/pixma/tree/master/src/base/managers"
    click brushDomain "https://github.com/bbogdan-ov/pixma/tree/master/src/common/brushes"
    click colorsDomain "https://github.com/bbogdan-ov/pixma/tree/master/src/common/colors"
    click layersDomain "https://github.com/bbogdan-ov/pixma/tree/master/src/common/layers"
    click projectsDomain "https://github.com/bbogdan-ov/pixma/tree/master/src/common/project"
    click toolsDomain "https://github.com/bbogdan-ov/pixma/tree/master/src/common/tools"
    click pluginScript "https://github.com/bbogdan-ov/pixma/blob/master/plugins/test.js"
    click utils "https://github.com/bbogdan-ov/pixma/tree/master/src/utils"
    click baseUtils "https://github.com/bbogdan-ov/pixma/tree/master/src/base/utils"

    %% Styles
    classDef core fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef ui fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef actions fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef managers fill:#f9c5d1,stroke:#c0392b,stroke-width:2px;
    classDef domain fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef plugin fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef utils fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
```
