Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
88 lines (65 loc) · 5.17 KB

ARCHITECTURE.md

File metadata and controls

88 lines (65 loc) · 5.17 KB
Raw

Panvas architecture

This overview describes the current runtime profiles and contributor boundaries.

Runtime profiles

Panvas has one React/Vite renderer with two storage profiles:

flowchart LR
    User[User] --> Renderer[React renderer]
    Renderer --> Services[Engines and domain services]
    Services --> Repositories[Repository layer]
    Repositories -->|Web| Dexie[(Dexie / IndexedDB)]
    Repositories -->|Electron| Preload[Preload contextBridge]
    Preload --> IPC[Validated IPC handlers]
    IPC --> Files[(Workspace files and assets)]
    Services -. optional, release-gated .-> Drive[(Google Drive)]
Loading
  • Windows Electron: the main process owns filesystem and native operations. The default workspace root is Documents/Panvas; a user-selected storage root is persisted in Electron settings.
  • Web: the repository layer uses origin-scoped Dexie/IndexedDB. Browser quota and site-data policies apply.
  • Cloud Sync: Google Drive support is present behind explicit build-time feature flags ; the example environment leaves it disabled. It is a backup/synchronization layer, not the local source of truth.

Renderer and domain layers

  • src/components/ contains the React UI for the library, notebook, PDF workspace, canvas, settings, and public pages.
  • src/components/notebook/engine/ contains the notebook drawing/input engines. They operate on page-local vector data and should be changed with focused tests.
  • src/repositories/ presents a common data-access surface. Repositories choose Electron IPC or browser database adapters without exposing storage details to most components.
  • src/services/ contains persistence, backup, search, PDF, audio, recognition, and optional sync services.
  • src/stores/ contains Zustand state for workspace navigation, notebook settings, canvas state, UI state, and sync status.

Notebook hierarchy

Documentation uses the existing TextObject.content Tiptap/ProseMirror JSON and the same page/drawing persistence as ink. DocumentFlowEditor lays that document across logical sheets; it does not introduce a second database/editor or unbounded physical canvas. Text gestures dispatch existing mark commands once per completed selection. Code wrap/language/caption belong to the code node, while the code toolbar is transient view state.

The public landing, legal and download routes share this renderer and load independently of editor engines. Public download metadata represents an already published version; the application version comes from the package/native runtime. Docker serves a static web build; see DOCKER.md.

flowchart TD
    Workspace --> Folder
    Workspace --> Notebook
    Workspace --> Canvas
    Folder --> Notebook
    Notebook --> Section
    Section --> Page
    Page --> Content[Rich-text content]
    Page --> Drawing[Vector drawing data]
    Canvas --> Scene[Excalidraw scene and Panvas blocks]
Loading

Folders can organize notebooks and canvases. A notebook is divided into sections and pages. Pages can carry rich text, drawings, page properties, and references to imported assets.

Electron boundary

The renderer cannot use Node.js filesystem APIs directly. electron/preload.ts exposes the typed window.panvas bridge. electron/ipc/domain-handlers.ts and related handlers validate trusted senders and operation inputs before delegating to WorkspaceService or other main-process services.

sequenceDiagram
    participant R as Renderer
    participant P as preload.ts
    participant H as IPC handler
    participant W as WorkspaceService
    participant D as Documents/Panvas
    R->>P: window.panvas operation
    P->>H: invoke allowlisted channel
    H->>W: validate and perform operation
    W->>D: queued JSON or asset I/O
    D-->>W: result
    W-->>H: result
    H-->>R: typed response
Loading

Persistence and recovery

Desktop writes are serialized by electron/ipc/write-queue.ts. Workspace metadata is stored in .panvas/workspace.json; page metadata, rich text, drawings, and canvas scenes are separate JSON payloads. Imported PDFs, images, and audio use the workspace asset stores. A last-good workspace mirror is kept under .panvas/recovery/ for metadata recovery.

Browser persistence uses the Dexie schema in src/database/schema.ts. Browser and Electron adapters share domain types but do not share a filesystem.

Recognition and PDFs

Handwriting recognition selects Windows Ink in a Windows Electron session, then a browser-native handwriting API when available. The local neural fallback infrastructure exists for evaluation but its runtime switch is off; unsupported providers preserve raw ink.

PDF.js renders imported documents and pdf-lib supports annotated-PDF export. Both operate in the renderer/service layer; native filesystem access for desktop assets still crosses IPC.

Security boundary

The Electron build uses context isolation, nodeIntegration: false, a sandboxed renderer, trusted-frame checks, and allowlisted preload methods. These are implementation controls, not a guarantee that an installation or host operating system is secure. See SECURITY.md for reporting guidance and STORAGE_AND_PERSISTENCE.md for data handling.