Architecture Overview

A high-level guide to the OpenGPEX engine architecture — what it is, how it's organized, and the key design decisions that differentiate it from traditional web editors.

System Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         OpenGPEX Editor                                │
├──────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌─────────────┐   ┌──────────────┐   ┌───────────────────────────┐ │
│  │  Workspace   │   │    Stage     │   │        Plugins            │ │
│  │  (Layout)    │   │  (Viewport)  │   │  (Drawers, Overlays,     │ │
│  │              │   │              │   │   Options, Panels,        │ │
│  │  Slot Mgr    │   │  Camera      │   │   Backstage services)     │ │
│  │  Plugin Mgr  │   │  Interaction │   │                           │ │
│  └──────┬───────┘   └──────┬───────┘   └────────────┬──────────────┘ │
│         │                  │                         │                │
│         └──────────────────┼─────────────────────────┘                │
│                            │                                          │
│                   ┌────────▼────────┐                                 │
│                   │      Core       │                                 │
│                   ├─────────────────┤                                 │
│                   │  State (Store)  │  ← Normalized, Immer-powered   │
│                   │  Engine         │  ← Worker-based pixel pipeline │
│                   │  Plugin Registry│  ← Dual-track (static/dynamic) │
│                   │  Geometry       │  ← Matrix math, spatial service │
│                   │  Storage        │  ← CAS (SHA-256), IndexedDB    │
│                   │  FileService    │  ← 10+ format handlers + vips  │
│                   │  Types          │  ← Full TypeScript contracts    │
│                   └─────────────────┘                                 │
│                                                                       │
└──────────────────────────────────────────────────────────────────────┘

Module Dependency Graph

Dependencies flow inward — outer layers depend on inner layers, never the reverse.

Plugins  →  Workspace  →  Stage  →  Core
   │                                  ▲
   └──────────────────────────────────┘
              (via context hooks)

Layer	Responsibility	May Import
Core	Engine, state, types, geometry, storage	Nothing (leaf layer)
Stage	Viewport rendering, interaction dispatch	Core
Workspace	Layout shell, slot management, plugin init	Core, Stage
Plugins	Business features (tools, panels, overlays)	Core (via hooks), Widgets
Widgets	Reusable UI components	Nothing editor-specific

Core Architectural Aspects

#	Aspect	Design Choice	Status
1	State & Data Flow	Normalized dictionary + Dual-track (Fast/Slow) + Immer patches for undo	✅ Stable
2	Rendering & Engine	Tiled rendering + Three-lane export + Worker-only pixel computation + isomorphic painter	✅ Stable
3	Color Pipeline	Centralized strategy-routed color management with wide-gamut (P3) + ICC support	✅ Stable
4	Plugin System	Metadata-driven IoC registry with slot-based UI injection	✅ Stable
5	File Format & Storage	CAS-backed immutable assets + 10+ format handlers via vips/WASM	✅ Stable
6	Cloud Integration	Stateless API protocol + explicit user-driven sync	✅ Stable

Key Design Decisions

1. Dual-Track State (Fast Track + Persistent)

Traditional React editors suffer from 16ms+ re-render latency during drag operations. OpenGPEX uses a volatile mutable reference that bypasses React entirely during interactions, then commits once on pointer-up — achieving native-refresh-rate rendering (60–120fps depending on display) with zero jank.

2. Zero Main-Thread Pixel Computation

All pixel-intensive operations (compositing, filtering, decoding, resampling) run in a dedicated Web Worker. The main thread only orchestrates and renders pre-computed tiles, ensuring the UI never freezes regardless of image complexity.

3. Content-Addressable Storage (CAS)

Every image asset is stored by its SHA-256 hash. Duplicate images share a single blob. Layer operations create metadata-only derivatives, preserving original pixels immutably — enabling non-destructive editing throughout.

4. Plugin-First Architecture

The editor ships zero hardcoded UI. Every panel, tool, and overlay — including crop, layers, undo — is a plugin registered through the same metadata contract as user-authored plugins. The core is a pure framework with no built-in business logic.

5. Isomorphic Rendering

A single atomic painter function is shared between the main-thread canvas engine and the Web Worker compositor. This eliminates coordinate drift between what users see on screen and what gets exported to file.

Comparison with Traditional Web Editors

Aspect	Traditional Web Editor	OpenGPEX
Large images	OOM crash at ~8K	Tiled rendering handles 16K+
Drag performance	Jank (full React cycle)	Native refresh rate (Fast Track bypass)
Undo memory	Full-state snapshots (MB each)	JSON Patches (bytes each)
Extensibility	Monolithic codebase	Plugin slots with IoC registry
Pixel integrity	Destructive edits	CAS-backed non-destructive
Export fidelity	Preview ≠ export	Isomorphic single painter
High bit-depth	8-bit only	16/32-bit via vips (WASM)

Last updated: 2026-07-30