Cross-Platform Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Dotorixel is designed as a learning-first, cross-platform pixel art editor that shares core logic across Web and Apple native (macOS/iPadOS) environments. The architecture centralizes performance-critical and domain-specific logic in a shared Rust core, while utilizing platform-native UI frameworks—Svelte for Web and SwiftUI for Apple platforms—to ensure high-quality user experiences and optimal hardware utilization.
Sources: CLAUDE.md:3-23, README.md:34-45
Shared Core Logic
The backbone of Dotorixel is a self-contained Rust core located in crates/core/. This module is free from framework dependencies and side effects, ensuring portability across different runtimes. It handles pixel manipulation, coordinate transformations, tool algorithms, and undo/redo history.
The core is integrated into different platforms using specialized binding generators:
- Web (WASM): Compiled via
wasm-packwithwasm-bindgeninterfaces for consumption by the SvelteKit frontend. - Apple Native (Swift): Utilizes
UniFFIto generate Swift bindings, allowing the SwiftUI layer to call Rust functions directly.
Sources: CLAUDE.md:144-150, issues/013-apple-native-catchup.md:21-27, tasks/records/010-xcode-project.md:14-15
Core Responsibilities
The shared Rust core implements the following critical systems:
- Canvas Storage: Pixel data structures and buffer management.
- Tool Algorithms: Logic for pencil, eraser, flood fill, line, rectangle, and ellipse.
- Viewport Math: Coordinate transforms and zoom/pan calculations.
- History Management: Snapshot-based undo and redo logic.
- Encoding: PNG encoding and color parsing.
Sources: issues/013-apple-native-catchup.md:29-33, tasks/records/001-pre-workflow-migration.md:65-72
This diagram shows how the shared Rust core is consumed by both the Web and Apple shells through platform-specific bindings.
UI Frameworks and Rendering
Dotorixel uses platform-native UI frameworks to provide a high-fidelity experience while maintaining a unified visual identity (the "Pebble UI").
Platform Comparison
| Feature | Web Platform | Apple Native Platform |
|---|---|---|
| UI Framework | Svelte / SvelteKit | SwiftUI |
| Rendering Engine | Canvas2D (MVP), WebGL2 (Later) | Metal GPU Rendering |
| Package Manager | bun | XcodeGen / SPM |
| Primary Language | TypeScript | Swift |
| Bindings | wasm-bindgen | UniFFI |
Sources: CLAUDE.md:5-12, README.md:34-45
Responsive Layout Strategy
The project follows a "native-first" responsive design approach. Layout transitions are extraction from SwiftUI's automatic size class handling and then mapped to CSS media and container queries on the web.
The architecture supports three primary layout paradigms based on screen width:
- Compact (<600px): Tab-based navigation (Draw, Colors, Settings).
- Medium (600px - 1023px): Transition point using floating panels or initial docked structures.
- Wide/X-Wide (>=1024px): A fully docked layout consisting of a
TopBar,LeftToolbar,RightPanel, andStatusBar.
Sources: CLAUDE.md:195-201, tasks/records/040-screen-inventory-breakpoint-matrix.md:16-18, tasks/records/046-editor-layout-restructure.md:14-38
Design System and Synchronization
To maintain visual parity across shells, Dotorixel utilizes a shared design system. On the web, this is implemented via CSS custom properties (--ds-*). On Apple platforms, these tokens are mirrored as static SwiftUI.Color properties.
Unified Design Tokens
Design tokens follow a standardized naming convention (e.g., bgBase, bgSurface, borderSubtle, accent). The goal is to avoid the cost of dual-shell design maintenance by using the web design as the single source of truth, adapted to native platform idioms.
Sources: CLAUDE.md:189-193, issues/014-apple-native-docked-layout.md:73-82, tasks/records/041-design-system-finalization.md:10-15
This sequence diagram illustrates how both platforms interact with the same core logic but utilize different rendering pipelines for visual output.
Build Pipeline and Targets
The project manages complex cross-platform builds using modern tooling:
- Web: Uses
Vitefor the frontend andwasm-packfor Rust compilation. - Apple: Uses
XcodeGento generate.xcodeprojfiles from aproject.ymldefinition. A custombuild-rust.shscript maps platform architectures to Rust target triples and copies the static libraries into the final bundle.
Sources: CLAUDE.md:12, tasks/records/010-xcode-project.md:8-15
Target Support Matrix
| Platform | Target Support |
|---|---|
| Web | Modern Browsers (Chrome/Safari/Firefox) |
| macOS | Native App (Silicon/Intel) |
| iPadOS | Tablet (Landscape/Portrait/Compact) |
Sources: tasks/records/010-xcode-project.md:8, tasks/records/046-editor-layout-restructure.md:14-25
Conclusion
Dotorixel's cross-platform architecture succeeds by isolating domain logic within a strictly managed Rust core while allowing the UI shell to exploit platform-specific strengths, such as Metal for high-performance rendering on iOS and Svelte's reactivity for the web. This dual-shell approach ensures that the application feels native on all devices while sharing the vast majority of its functional codebase.