High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• README.en.md
• CONTRIBUTING.md
• orca.yaml
• SECURITY.md

OpenHWP is a cross-platform desktop application designed to view and eventually edit Korean HWP and HWPX documents without requiring Hancom Office. Its architecture is built upon a "thin shell" philosophy, utilizing the Deno runtime to manage the desktop environment while delegating document processing to a specialized WebAssembly (WASM) engine.

The system is designed to run on macOS, Windows, and Linux using a single Deno-based toolchain. By separating the document engine from the platform shell, OpenHWP ensures consistent rendering and simplified maintenance across different operating systems.

Sources: README.en.md:5-13, README.en.md:16-17

Core Component Structure

The architecture is divided into three primary layers: the Desktop Shell, the Rendering Backend, and the Document Engine.

Layered Architecture Overview

Component	Responsibility	Technology
Desktop Shell	Native window management, webview hosting, and OS-level integration.	deno desktop
Rendering Backend	Standardized web engine for consistent UI/UX across platforms.	CEF (Chromium)
Document Engine	Parsing, rendering logic, and HWP/HWPX data manipulation.	rhwp (Rust/WASM)
File I/O	Direct disk access for opening and saving documents.	File System Access API

Sources: README.en.md:19-24, README.md:18-23

Architecture Diagram

The following diagram illustrates the relationship between the Deno-based shell and the document processing components:

System Modules and Integration

Desktop Shell and Backend

The application uses deno desktop to create a native window. This window contains a webview that displays content served via Deno.serve(). To ensure identical rendering across all operating systems, the project explicitly configures the Chromium Embedded Framework (CEF) as the backend by setting "backend": "cef" in the project configuration. This allows the application to leverage modern web APIs consistently.

Sources: README.en.md:19-21, README.md:18-20

Document Engine: rhwp

The "brain" of the application is the rhwp engine, written in Rust and compiled to WebAssembly. Instead of being compiled directly into the binary shell, it is loaded as npm packages (@rhwp/core and @rhwp/editor). This decoupling allows the document logic to evolve independently of the platform shell.

• Viewer Logic: Uses @rhwp/core to parse document bytes and render pages to SVG format.
• Editor Logic: Uses @rhwp/editor to embed a full editor UI via an iframe.

Sources: README.en.md:22-23, README.en.md:31-35, README.en.md:41-45

File System Interaction

OpenHWP utilizes the standard web File System Access API rather than Deno-specific native file pickers. Because the app is served from localhost (a secure context) via the CEF backend, it can directly invoke window.showOpenFilePicker. This enables the application to obtain a FileSystemFileHandle for both reading and writing back to the disk without frequent permission prompts.

Sources: README.en.md:52-54, README.en.md:56-65

Data Flow: Opening a Document

The sequence below describes how a document is retrieved from the local file system and passed to the engine for rendering:

Development and Build Toolchain

The project strictly follows a single-toolchain approach using Deno (version 2.9.0 or higher). It avoids external runtimes like Node.js or Bun.

• Dependency Management: Dependencies are managed via Deno, with an optional setup script for worktrees using bunx for specific tooling tasks.
• Linting and Formatting: The project uses built-in Deno commands: deno lint and deno fmt.
• Build System: Standalone binaries and platform-specific installers (e.g., .dmg, .msi, .deb) are produced using the deno desktop command, configured via deno.json.

Sources: CONTRIBUTING.md:13-17, CONTRIBUTING.md:25-27, README.en.md:76-85, orca.yaml:16-19

Summary

The OpenHWP architecture prioritizes cross-platform consistency by wrapping a Rust-powered WASM engine (rhwp) within a standardized Chromium-based shell provided by Deno. By utilizing the File System Access API and maintaining a thin desktop shell, the project minimizes platform-specific code while providing high-fidelity HWP/HWPX document support across macOS, Windows, and Linux.

Sources: README.en.md:5-13, README.en.md:16-24