Skip to content

Architecture

Overview of the SciFlow monorepo architecture.

Package structure

The six published packages:

packages/
├── editor/
│   ├── core/          # @sciflow/editor-core     — editor runtime, features, commands
│   └── start/         # @sciflow/editor-start    — Lit web components + bundle entry
├── schema/
│   ├── core/          # @sciflow/schema-core     — ProseMirror-free helpers (texToHeadingText)
│   └── prosemirror/   # @sciflow/schema-prosemirror — schema, JSON-schema + JATS generators
├── import/            # @sciflow/pandoc-ast      — Pandoc AST → ProseMirror
└── pandoc-web/        # @sciflow/pandoc-web      — browser Pandoc-WASM wrapper

Package dependencies

@sciflow/editor-start ──┬─→ @sciflow/editor-core ──→ @sciflow/schema-prosemirror
                        └─→ @sciflow/schema-core

@sciflow/pandoc-web ────→ @sciflow/pandoc-ast ────→ @sciflow/schema-prosemirror

Two dependencies require clarification:

  • @sciflow/schema-prosemirror does not depend on @sciflow/schema-core. They are siblings. schema-core contains helpers that must work without ProseMirror and is the only dual CommonJS/ESM package); schema-prosemirror holds everything that needs a live Schema, including generateJsonSchema, generateSnapshotSchema and generateJatsBody.
  • @sciflow/editor-start depends on @sciflow/schema-core directly, not through editor-core — it uses texToHeadingText for outline headings that contain math.

@sciflow/editor-start declares @sciflow/editor-core, @sciflow/schema-prosemirror and the prosemirror-* packages as peer dependencies, so a host application resolves exactly one copy of each. The @sciflow/editor-start/bundle entry is the exception: it inlines its own copies.

Core concepts

Editor

The Editor class is the main entry point for programmatic control. It:

  • manages ProseMirror state;
  • handles document synchronization;
  • provides access to commands; and
  • emits events when the document or selection changes.

Command system

The command system provides 3 complementary APIs:

  • Immediate commands (commands.*) — execute immediately.
  • Flows (flow()) — group operations.
  • Inspection (can()) — check capabilities.

See Command System for details.

Sync strategy

The sync strategy is an abstract interface for persistence and collaboration:

  • load() — load a document from storage.
  • applyExternal() — handle remote changes.
  • applyLocal() — send local changes.
  • dispose() — release resources.

Schema

The ProseMirror schema defines:

  • node types such as doc, paragraph, and heading;
  • mark types such as strong and em; and
  • attributes for each node and mark.

Build system

  • Nx — monorepo orchestration.
  • TypeScript — type-checking and compilation.
  • Vite — browser bundle generation.
  • Vitest — testing framework.

Development tools

  • ESLint — code linting.
  • Prettier — code formatting.
  • TypeScript — static type checking.