Skip to content
MatemiumMatemium

Architecture overview

Matemium is a monorepo with independently deployed products and a local engine.

Desktop UI (TypeScript)
        │ Tauri invoke
        ▼
Rust shell
        │ NDJSON stdin/stdout
        ▼
Python sidecar + Canvas engine


Desktop ── HTTPS ──► Optional cloud API

Engine

Section titled “Engine”

Locations:

canvas/
matemium/
projects/

Responsibilities:

  • Declarative scene model
  • Layout and measurement
  • Timeline compilation
  • Camera and focus
  • 2D and 3D rendering
  • Project discovery and CLI
  • Sidecar project commands

The engine must not import the server or desktop application.

Desktop

Section titled “Desktop”

Location:

desktop/
├── app/
├── src-tauri/
├── packaging/
└── scripts/

The TypeScript interface never imports Python. Rust owns the sidecar process and the invoke bridge.

Cloud API

Section titled “Cloud API”

Location:

server/

The cloud can provide authentication, profile data, and user-selected AI routing helpers. It does not render projects or receive the complete workspace as a normal rendering operation.

Marketing website

Section titled “Marketing website”

Location:

website/

The website introduces Matemium, presents real output, explains support, and links into these task-oriented docs.

Documentation

Section titled “Documentation”

Location:

docs/

The Astro/Starlight build is independently deployed to docs.matemium.fargonee.space.

Authoring boundary

Section titled “Authoring boundary”

Product authors edit scenes.py through CanvasBuilder. SheetDSL is internal compiler data and a debugging interface—not the normal authoring format.

Project versus engine behavior

Section titled “Project versus engine behavior”

Generic capabilities belong in canvas/:

  • Layout
  • Camera
  • Focus
  • Timeline behavior
  • General solids and surfaces
  • Sampled paths and plots
  • Semantic node-edge diagrams
  • Allowlisted state transitions and compiled morphs

Subject recipes belong in projects/<name>/helpers.py:

  • A specific circuit
  • A quadratic comparison
  • A molecular arrangement
  • A historical timeline composition

This boundary allows Matemium to expand across subjects without forcing every topic into its core API.

The same rule applies to ongoing 3D authoring research. Real projects are used as evidence and acceptance tests, but they do not determine subject-specific engine APIs. The possible abstractions for relative movement, traversal, and surface-aware authoring remain undecided; see the open spatial-authoring discussion.

Current generic contracts

Section titled “Current generic contracts”

DataPath, DataPlot, and Diagram provide shared build/measurement behavior, pure content validation, and stable semantic parts. Timeline actions address parts with element_id::part_id.

StateTransition changes an allowlisted set of visual properties in one synchronized action. ElementMorph recompiles a target CanvasElement and replaces the source registry object. CanvasScene validates these contracts strictly before render by default.

The automatic root tape is the mature default. Additional tapes are isolated, camera-facing presentation contexts. Revealing tape content or calling scroll_tape() closes that tape over the world; a world observation opens it and restores only free-world objects.

See the CanvasBuilder reference and Data visuals and transitions.

Deeper engineering records

Section titled “Deeper engineering records”