ADR-003: Client Surface Strategy

Deliver MetaForge through a web dashboard for collaboration and CAD-native plugins for design work — not a standalone desktop application

Table of Contents

1. ADR Header
2. Context
   1. The Core Insight
3. Options Considered
   1. Option A: Web Dashboard + CAD Plugins (two-surface) — Selected
   2. Option B: Desktop Application (Electron/Tauri) — Rejected
   3. Option C: Native Desktop Application — Rejected
   4. Option D: Web-Only (no CAD plugins) — Rejected
4. Decision
   1. Surface Responsibilities
   2. Who Uses What
5. Architecture Constraints
   1. 1. Shared Backend API
   2. 2. Plugin Communication Protocol
   3. 3. Dashboard Does Not Edit Designs
   4. 4. Plugin Scope Is Contextual, Not Comprehensive
6. IDE Assistant Delivery Phases
   1. Plugin Architecture Pattern
7. Consequences
   1. Positive
   2. Negative
   3. Risks and Mitigations
8. Why Not Desktop?
9. Related Documents

ADR Header

Context

MetaForge requires a user-facing client surface for hardware engineers. The question arose whether a desktop application (Electron, Tauri, or native) would be better suited than the current web-based dashboard, particularly for the 3D Digital Twin viewer.

The platform backend is cloud-native:

• Agent orchestration via Temporal + Pydantic AI
• Neo4j artifact graph (Digital Twin)
• Event sourcing pipeline (Kafka)
• AI Memory (pgvector + RAG)
• Constraint engine
• Multi-user sessions via WebSocket
• Server-side STEP-to-GLB conversion (ADR-002)

All of these run server-side. Any client — web, desktop, or plugin — connects to the same backend over the network.

The Core Insight

MetaForge is not a CAD tool. It is an orchestration and intelligence layer that augments existing CAD tools. Engineers already have preferred design environments (SolidWorks, Fusion 360, KiCad, FreeCAD, VS Code). Building a standalone desktop app would compete with those tools rather than complement them.

Options Considered

Option A: Web Dashboard + CAD Plugins (two-surface) — Selected

Separate the client into two complementary surfaces matched to different user workflows:

Strengths:

• Meets engineers where they already work — no context switching to a new app
• Web dashboard is zero-install, cross-platform, instantly updatable
• CAD plugins have native access to file system, GPU, and CAD kernel — no conversion needed
• Clean separation: collaboration/review (web) vs. design-time (plugin)
• Plugins already specified in the architecture (Assistant Mode)
• Each surface can evolve independently

Weaknesses:

• Two codebases to maintain (dashboard + plugin per CAD tool)
• Plugin APIs vary across CAD tools — adapter complexity
• Some feature duplication (e.g., BOM view in dashboard and in CAD plugin)

Option B: Desktop Application (Electron/Tauri) — Rejected

Single desktop application bundling a native renderer, local file access, and the full dashboard experience.

Strengths:

• Better GPU access and memory management for 3D rendering
• Native file system access for STEP files
• Offline capability for local operations
• Single unified application

Weaknesses:

• Still requires network for all backend services — not truly offline
• Deployment and update burden (installers, auto-updaters, code signing, cross-platform builds)
• Competes with engineers’ existing CAD tools rather than integrating with them
• Electron bundles Chromium (~150MB+); Tauri is lighter but has WebView limitations
• Cross-platform testing matrix (Windows, macOS, Linux)
• Does not solve the fundamental problem: engineers want AI assistance inside their CAD tool, not in a separate window

Option C: Native Desktop Application — Rejected

Purpose-built native application (C++/Qt, Swift, etc.) with embedded CAD kernel.

Strengths:

• Best possible 3D performance
• Full native CAD kernel (OpenCascade) without conversion
• Native OS integration

Weaknesses:

• Massive development effort — essentially building a new CAD tool
• Competes directly with SolidWorks, Fusion 360, etc.
• Completely misaligned with MetaForge’s value proposition (orchestration, not CAD)
• Per-platform development and maintenance
• Slowest time to market

Option D: Web-Only (no CAD plugins) — Rejected

Single web dashboard with the 3D viewer as the only design surface.

Strengths:

• Simplest architecture — one codebase, one deployment
• Lowest maintenance burden

Weaknesses:

• Forces engineers to leave their CAD tools to interact with MetaForge
• No real-time design-time integration (file save detection, contextual suggestions)
• The 3D viewer can display designs but cannot edit them — engineers must round-trip between tools
• Loses the core value of Assistant Mode: AI assistance embedded in the design workflow

Decision

Adopt a two-surface client strategy: web dashboard for collaboration and review, CAD-native IDE Assistants for design-time integration.

flowchart TD
    subgraph SURFACES["Client Surfaces"]
        direction LR
        subgraph WEB["Web Dashboard (React)"]
            ORCH_UI["Session Orchestration"]
            TWIN_UI["3D Digital Twin Review"]
            BOM_UI["BOM & Supply Chain"]
            COMP_UI["Compliance Tracking"]
            APPROVE["Approval Workflows"]
            CHAT["Agent Chat"]
        end
        subgraph PLUGINS["CAD IDE Assistants"]
            KC["KiCad Plugin"]
            FC["FreeCAD Plugin"]
            SW["SolidWorks Add-in"]
            VSC["VS Code Extension"]
        end
    end

    subgraph BACKEND["MetaForge Backend"]
        GW["Gateway (HTTP/WS)"]
        ORCH["Orchestrator"]
        AGENTS["Domain Agents"]
        GRAPH["Neo4j Graph"]
    end

    WEB --> GW
    PLUGINS --> GW
    GW --> ORCH
    ORCH --> AGENTS
    AGENTS --> GRAPH

Surface Responsibilities

Who Uses What

Architecture Constraints

1. Shared Backend API

Both surfaces connect to the same Gateway service. There is no surface-specific backend. The Gateway exposes:

• REST API for CRUD operations
• WebSocket for real-time session updates, agent chat, and telemetry
• Authentication via the same identity provider

2. Plugin Communication Protocol

All CAD IDE Assistants communicate with the backend using the same protocol:

• File change detection via watchfiles (inotify/FSEvents)
• Adapter parsers convert tool-specific formats to GraphEvent[]
• Events published to the ingest pipeline with actor_id = "user:<id>"
• See Assistant Mode for the full specification

3. Dashboard Does Not Edit Designs

The web dashboard is a read-only review and collaboration surface for design artifacts. It can:

• Display 3D models (via R3F, per ADR-002)
• Show BOM data, compliance status, and approval workflows
• Trigger agent tasks and approve/reject proposals

It cannot modify design files. Design modifications flow through CAD IDE Assistants only.

4. Plugin Scope Is Contextual, Not Comprehensive

CAD IDE Assistants provide contextual assistance relevant to the current design task — constraint violations, related BOM data, agent suggestions. They do not replicate the full dashboard experience. Engineers switch to the web dashboard for comprehensive views (full compliance matrix, cross-project BOM analysis, session history).

IDE Assistant Delivery Phases

Plugin Architecture Pattern

Each IDE Assistant follows the same adapter pattern:

┌─────────────────────────────┐
│  CAD Tool (KiCad/FreeCAD/…) │
│  ┌───────────────────────┐  │
│  │  MetaForge Plugin      │  │
│  │  ├─ File Watcher       │  │
│  │  ├─ Format Adapter     │  │
│  │  ├─ Notification Panel │  │
│  │  └─ Chat Sidebar       │  │
│  └───────┬───────────────┘  │
└──────────┼──────────────────┘
           │ GraphEvent[] / WebSocket
           ▼
    MetaForge Gateway

Consequences

Positive

• No competition with existing tools — MetaForge augments, not replaces, the engineer’s CAD environment
• Zero-install for reviewers — managers, compliance, and supply chain use the web dashboard without any setup
• Native design-time experience — engineers get AI assistance without leaving their CAD tool
• Independent evolution — dashboard and plugins ship on separate cadences
• Lower client complexity — neither surface tries to do everything

Negative

• Multiple codebases — dashboard (React/TS) + one plugin per CAD tool (Python for KiCad/FreeCAD, C# for SolidWorks, TS for VS Code)
• Plugin API variability — each CAD tool has a different plugin API, requiring per-tool adapter work
• Feature coordination — changes to the backend API must be tested against all surfaces
• Partial duplication — some views (BOM, constraints) appear in both surfaces with different fidelity

Risks and Mitigations

Why Not Desktop?

This section exists to document the reasoning explicitly for future reference.

A desktop application was considered and rejected because:

1. MetaForge is an orchestration layer, not a CAD tool. A desktop app would either duplicate CAD functionality (competing with SolidWorks) or be a thin shell around a web view (Electron), gaining little over a browser.

2. All core services are server-side. A desktop app still needs network connectivity for agents, graph, events, and AI memory. It cannot offer meaningful offline capability for MetaForge’s core value proposition.

3. Engineers already have a desktop app — their CAD tool. Adding another window to manage is friction, not value. Embedding MetaForge into the tool they already use (via plugins) is higher-value and lower-friction.

4. The web dashboard serves non-engineer stakeholders well. Compliance officers, managers, and supply chain analysts do not need or want a desktop install. Zero-install browser access is the right model for these users.

5. Deployment cost. Desktop apps require installers, auto-updaters, code signing, platform-specific builds, and crash reporting infrastructure. The web dashboard deploys once and updates instantly for all users.

Related Documents