Skip to content

plan.md

Latest commit

 

History

History
229 lines (160 loc) · 8.85 KB

plan.md

File metadata and controls

229 lines (160 loc) · 8.85 KB

Draftly — Technical Specification & Roadmap

Status note:
The core geometry engine, editor features, backend persistence, and Docker deployment are fully implemented and functional.
The only known active issue is strictly related to coordinate stacking in multi-selection transforms (see Phase 5).

Aim

Draftly is a high-performance, precision-focused design drafting engine built for rapid ideation and technical visualization.
Unlike full-scale production suites, Draftly is intentionally optimized for the drafting phase of product development—where speed, geometric correctness, and iteration velocity matter more than asset polish.

At its core, Draftly is powered by a custom graphics and geometry engine written in Rust and compiled to WebAssembly, deliberately bypassing JavaScript-centric rendering stacks to achieve:

  • Deterministic geometry
  • Sub-pixel precision
  • Numerically stable transforms
  • Predictable performance under complex scenes

Draftly treats design not as “pixels on a canvas,” but as structured, mathematically grounded geometry.

Key Differentiator (USP)

Engine-First Design Tooling

Draftly is not UI-driven with an engine bolted on later.
It is engine-first:

  • All geometry, snapping, transforms, and scene state live in Rust
  • React is a thin orchestration and presentation layer
  • Rendering is a deterministic projection of engine state—not ad-hoc UI logic

This architecture mirrors professional CAD and simulation software rather than typical web design tools, making Draftly closer to a technical drafting system than a visual editor.

Technical Pillars

1. Custom Rust Geometry Engine (WASM)

A high-precision core written in Rust and compiled to WebAssembly, responsible for:

  • Scene graph management
  • Coordinate systems and transforms
  • Snapping mathematics and alignment logic
  • Hit-testing and selection geometry

This ensures computational accuracy beyond floating-point-heavy JavaScript libraries.

2. Direct Canvas Rendering Pipeline

A low-overhead rendering pipeline where:

  • Rust computes frame-level draw instructions
  • Commands are issued directly to the HTML5 Canvas API
  • React never participates in per-frame rendering

This avoids virtual-DOM bottlenecks and ensures predictable frame performance.

3. High-Performance Backend Infrastructure

A backend built with Hono on Bun, designed for:

  • Low-latency persistence
  • Deterministic project serialization
  • Future real-time collaboration primitives
  • Stateless, distributed-ready APIs

Technical Stack

  • Runtime: Bun
  • System Core: Rust (WebAssembly via wasm-bindgen)
  • Graphics: Custom Rust Engine + HTML5 Canvas API
  • API Framework: Hono (Bun)
  • Frontend: React 19 + TypeScript
  • Interaction & Motion: Framer Motion
  • Styling: Tailwind CSS v4

Architecture Overview

Draftly follows a strictly decoupled systems architecture:

  • Client (React):
    Manages UI composition, tool state, and user input routing.

  • Engine (Rust / WASM):
    Owns all geometry, scene state, snapping logic, transforms, and draw command generation.

  • API (Hono):
    Handles persistence, export pipelines, and future collaborative coordination.

For deeper engine internals, see:
Engine Core Architecture

Implementation Roadmap

Phase 1: Environment & Core Shell — COMPLETED

  • Monorepo setup using Bun workspaces and Biome
  • Vite + React frontend, Hono backend, Rust engine foundation
  • Professional dark-mode UI scaffold using Tailwind CSS v4
  • Strict linting and type-checking (TypeScript, Biome, Clippy)

Phase 2: Rust Engine Core — COMPLETED

  • WASM build pipeline using wasm-pack
  • High-performance React ↔ Rust bridge
  • Real-time pointer event handling inside Rust
  • Internal Scene Graph implementation
  • Infinite canvas with high-precision pan & zoom math

Phase 3: Advanced Engine Engineering — COMPLETED

  • Modular engine architecture (core, editor, render)
  • Persistent engine state with atomic execution guards
  • Professional 9-point snapping system
  • Marquee selection and bounding-box hit testing
  • 8-point resize handles + rotation handle with angular delta math
  • Hierarchical scene graph with recursive transforms
  • Per-shape styling (fill, stroke, opacity)
  • Real-time SVG export from engine state
  • Live Properties Panel with Rust-backed updates
  • Layer Panel synchronized with engine Scene Graph
  • Cubic Bezier drafting with symmetrical handle control
  • Direct path editing with rotation-aware anchors
  • Smart Guides for dynamic alignment feedback
  • Global keyboard shortcut system

Phase 3.5: Advanced Design Operations — COMPLETED

  • Undo / Redo: Transaction-based history (50-step stack)
  • Grouping: Invisible group containers with hierarchical transforms
  • Clipboard: Copy, paste, cut, duplicate workflows
  • Z-Index Control: Stepwise and absolute ordering

Phase 3.6: Professional UX & Context Menus — COMPLETED

  • Unified context menu system (Canvas + Layers)
  • Quick-action UI for core operations
  • Recursive hierarchical layer tree with collapse/expand
  • Orphan layer handling and selection syncing

Phase 4: Persistence & Project Management — COMPLETED

4.1: Local Persistence — COMPLETED

  • Auto-Save to localStorage: Automatic serialization of scene state on every change (debounced).
  • Auto-Load on Startup: Restore last working session from localStorage with robust polling for engine initialization.
  • Scene Serialization: High-performance conversion of Rust SceneGraph to/from JSON format with ID restoration logic.
  • WASM Lifecycle Management: Explicit memory cleanup and defensive render guards to ensure stability during session restoration.

4.2: Backend API (For Resume/Portfolio) — COMPLETED

  • User Authentication: JWT-based auth with bcrypt hashing and Hono middleware.
  • Project CRUD API: Full RESTful lifecycle for user projects.
  • Database Schema: PostgreSQL with Drizzle ORM (Users & Projects).
  • Validation: Explicit Zod schemas for all request contracts.

4.3: DevOps & Deployment — COMPLETED

  • Containerization: Multi-stage Docker builds for Bun/Hono and Vite/React (WASM-aware).
  • Infrastructure: Docker Compose environment with Postgres, API, and Client fully orchestrated.
  • Developer Experience: Modern "Compose Watch" integration for real-time container hot-reloading.
  • One-Command Setup: Added bun run docker and bun run dev scripts for instant "clone-and-run" capability.

4.4: Frontend Integration — COMPLETED

  • Cloud Persistence: Upgraded useAutoSave with dual-layer storage (Local + PostgreSQL).
  • Auth Workflow: Implemented secure session management and animated AuthModal.
  • Sync Indicators: Real-time visual feedback for cloud synchronization status.
  • Smart Session Management: Prioritized local cache over stale cloud data for seamless reloads.

4.5: User Dashboard & Multi-File Support — COMPLETED

  • Premium Project Dashboard: High-fidelity project manager with grid/list views and cloud syncing.
  • Liquid Transitions: Framer Motion layoutId animations for sidebar navigation and tab switching.
  • Project Management: Full functional CRUD for opening and deleting cloud projects.
  • Search & Filter: Command-style "Jump to project" search and recent drafts filtering.
  • Inline Renaming: Seamless double-click interaction to rename projects directly in the grid.
  • Unique Name Enforcement: Backend logic to automatically handle duplicate names (e.g., "Untitled Design (1)").

4.6: UI/UX Modernization & Polish — COMPLETED

  • Sonner Integration: Replaced all legacy browser alerts with modern, interactive toast notifications (2026 standard).
  • Dashboard Polish: Figma-inspired workspace design with custom scrollbars and integrated profile management.
  • Security hardening: Auto-logout on 401 Unauthorized errors to prevent invalid session states.
  • Accessibility: Comprehensive A11Y pass (ARIA roles, button types, keyboard navigation).
  • Code Quality: Full Biome linting and strict Type-Checking across the Monorepo.

Phase 5: Future Roadmap / Backlog

  • Transformation Synchronization:
    Fix for Properties Panel bugs where multi-selection or group updates cause objects to stack and lose individual styles.
    Known issue: Coordinate stacking and style inheritance in multi-select.

  • Boolean Operations:
    Union, Subtract, Intersect, Difference (XOR).

  • Advanced Text Layout:
    Rich text, text-on-path, and font management.

Project Structure

/client   → React frontend
/server   → Hono backend
/engine   → Rust + WASM geometry engine
/assets   → Icons and visual assets
/docs     → Technical documentation & product learnings