Skip to content

CAD Viewer and Annotation Architecture

Source file: Step CAD_Viewer_Architecture_and_Tech_Stack.md Last synthesized: March 2026 Purpose: Define how RapidDraft should render 3D CAD and drawings, attach AI findings, and phase from demo stack to production-grade review tooling.

Why This Page Exists

RapidDraft is not building a passive file viewer. The product promise is a guided engineering review session where AI findings, human decisions, and geometry context all stay connected. That means the key architectural question is not just "what viewer do we use?" but "what state and annotation model lets the viewer, chat, and review logic operate on the same object?"

The source note adds an important framing: a professional review session needs a persistent inspection surface, not a one-shot model embedded inside a chat bubble. The viewer is a durable workspace, and the chat panel is a command and explanation layer attached to it.

Core Architecture Decision

RapidDraft should use a dedicated viewer plus chat panel rather than embedding a disposable 3D viewport inside the chat stream.

Why

  • Review sessions are stateful and often last long enough that camera position, selected faces, highlighted findings, and comment threads all need to persist.
  • One persistent viewer context is cheaper and operationally cleaner than spinning up multiple WebGL contexts per message.
  • The chat panel becomes more useful when it can read what the engineer is looking at and write new highlights or actions back into the same session state.

Interaction Model

Viewer -> shared state -> chat context
Chat -> shared state -> viewer highlights / selections / annotations

For the current stage, a lightweight shared store such as Zustand is enough. The important decision is the bidirectional contract, not the library brand.

Current RapidDraft Near-Term Architecture

The active RapidDraft implementation now uses a progressive browser viewer rather than a canonical or nothing load contract.

The current sequence is:

  1. preview mesh first
  2. backend canonical manifest second
  3. lazy per-component semantic detail third

This is the important current boundary:

  • preview geometry makes the workspace visible and usable quickly
  • backend canonical data remains the only trusted source for face ids, edge ids, feature refs, and review-grade selection behavior
  • heavy assemblies are allowed to stay partially in preview mode while canonical detail keeps warming

This is the near-term production architecture for RapidDraft. A browser-side OCCT/WebAssembly runtime is still a future branch, not the current implementation.

Representation Strategy: Mesh for Display, Semantics for Review

RapidDraft can display meshes early, but the full product requires B-Rep-aware selection whenever the system needs to reason about exact faces, edges, and drawing-linked manufacturing issues.

What matters

  • Mesh-only formats such as GLB are fine for visual display, but they discard the semantic face structure needed for engineering-grade selection and downstream edits.
  • B-Rep-aware stacks keep mathematical surfaces and topology available after tessellation, which is what turns a click into a meaningful engineering reference instead of a triangle index.

Practical implication

For the current implementation, RapidDraft now explicitly splits those concerns:

  • preview mesh for immediate display
  • canonical backend scene data for exact review semantics
  • progressive swap from preview components to canonical components as detail becomes ready

That lets the viewer stay visible on heavy models without relaxing the semantic standard for exact face and feature interaction.

This fits the broader product direction already present in the wiki: deterministic review and evidence matter more than flashy rendering.

Drawings Need an Annotation Architecture More Than a Fancy Viewer

For drawing review, the annotation layer is the real product surface.

  • PDF first: Good enough for early customer workflows because engineers will send PDFs.
  • DXF to SVG later: Better long-term path when entity identity matters and RapidDraft needs cleaner coordinate handling.
  • SVG-native outputs: Best case when RapidDraft generates the drawing or controls the export path.

The source note is directionally right here: viewer choice matters less than whether AI findings can be placed precisely, remain stable during zoom and pan, and stay tied to auditable evidence.

3D Annotation Model

3D comments should be stored as world-space anchors and rendered as screen-space UI.

Rules

  • Store the anchor in model/world coordinates.
  • Reproject to screen coordinates every frame as the camera moves.
  • Render comment bubbles as HTML so threading, editing, and accessibility stay simple.
  • Keep leader lines or anchor markers in a lightweight overlay layer.

Minimal annotation shape

{
  "id": "ann_001",
  "anchor": { "x": 24.5, "y": 10.0, "z": 3.0 },
  "faceId": "face_17",
  "severity": "error",
  "status": "open",
  "source": "dfm_auto",
  "text": "Draft angle below review threshold"
}

This is the right mental model for RapidDraft because it keeps findings stable even as the camera changes.

Phase 3D viewer Drawing viewer Annotation approach Why
Immediate demo Self-hosted lightweight STEP viewer PDF.js Canvas or SVG overlay on PDF Fastest path to a believable review demo with minimal infrastructure work
Post-demo validation occt-import-js plus Three.js PDF.js, then DXF to SVG where available Shared app state plus HTML/SVG overlays Unlocks richer face selection without committing to enterprise licensing too early
Production HOOPS Communicator-class viewer HOOPS-linked or equivalent semantic 2D path Native markup plus persistent review state Best fit for multi-format enterprise review, semantic selection, and scalable professional UX

RapidDraft-Specific Recommendation

The source note points to a staged decision that fits RapidDraft well:

  1. Start with the cheapest stack that proves the review loop.
  2. Upgrade the viewer only when the product truly needs semantic geometry selection.
  3. Treat annotations, evidence, and review memory as the durable moat, not the rendering layer by itself.

That means the short-term focus should stay on:

  • persistent viewer plus chat coupling
  • stable annotation coordinates for PDFs and 3D findings
  • clean handoff between AI findings and deterministic review state

The long-term production path remains consistent with the existing TextCAD decisions around HOOPS-family enterprise infrastructure.

Open Questions

  • Is PDF-first sufficient for the first customer-facing drawing-review workflow, or does RapidDraft need DXF-level entity references earlier than expected?
  • At what point does the commercial benefit of HOOPS Communicator outweigh the cost and integration complexity of a lighter open-source stack?
  • Should geometry edits stay server-side through FreeCAD/OpenCASCADE for the foreseeable future, or does RapidDraft eventually need a tighter native-CAD edit loop for selected operations?

Sources