# darwin/supex architecture

> Architecture diagram of the GitHub repository darwin/supex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darwin/supex
- Repository: https://github.com/darwin/supex

## Overview

Supex lets an agent or person describe and iterate on SketchUp models through CLI/MCP tools, with the Python driver sending commands to a Ruby extension inside SketchUp. The VCAD branch resolves geometry imports, evaluates Loon through a Rust sidecar, then places meshes in SketchUp and can relay previews to a standalone viewer. The Ruby standard library supports modeling utilities; Radar is a separate log-aggregation TUI. The README documents these capabilities; some unsampled subsystem links are omitted where source evidence was unavailable.

Main entry points: [`driver/src/supex_driver/mcp/vcad_tools.py`](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/mcp/vcad_tools.py) (VCAD Tools), [`vcad/sidecar/src/evaluator.rs`](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/evaluator.rs) (Loon Evaluator), [`runtime/src/supex_runtime/vcad_tools.rb`](https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/vcad_tools.rb) (VCAD Placement), [`devtools/radar/src/radar/ingest.py`](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/ingest.py) (Log Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_driver["Python Driver"]
  node_cli["CLI<br/>[main.py]"]
  node_mcp["MCP Server<br/>[mcp_server.py]"]
  node_driverconn["SketchUp Connection"]
  node_vcadtools["VCAD Tools<br/>[vcad_tools.py]"]
  node_vcadconn["VCAD Connection<br/>[vcad_connection.py]"]
  node_dag["Dependency DAG<br/>[vcad_dag.py]"]
  node_relay["Viewer Relay"]
end

subgraph group_runtime["SketchUp Runtime"]
  node_main["Runtime Startup<br/>[main.rb]"]
  node_bridge["JSON-RPC Bridge<br/>[bridge_server.rb]"]
  node_rubytools["Ruby Execution Tools<br/>[tools.rb]"]
  node_runtimevcad["VCAD Placement<br/>[vcad_tools.rb]"]
  node_repl["Ruby REPL<br/>[repl_server.rb]"]
end

subgraph group_stdlib["Ruby Modeling Utilities"]
  node_stdlib["Modeling Helpers<br/>[geom.rb]"]
end

subgraph group_vcad["VCAD Geometry"]
  node_sidecar["Sidecar Server<br/>[server.rs]"]
  node_evaluator["Loon Evaluator<br/>[evaluator.rs]"]
  node_imports["Import Resolution<br/>[imports.rs]"]
  node_mesh["Mesh Registry<br/>[mesh_registry.rs]"]
  node_dae["DAE Export<br/>[dae_export.rs]"]
  node_modules["Module Provider<br/>[modules.rs]"]
  node_config["Sidecar Config<br/>[config.rs]"]
  node_viewer["Live Preview Viewer<br/>[App.tsx]"]
  node_viewerclient["Relay Client"]
end

subgraph group_radar["Radar Logs"]
  node_radarcli["Radar CLI<br/>[cli.py]"]
  node_ingest["Log Ingestion<br/>[ingest.py]"]
  node_tailer["Log Tailer<br/>[tailer.py]"]
  node_normalizer["Event Normalizer<br/>[normalizer.py]"]
  node_buffer[("Event Buffer<br/>[buffer.py]")]
  node_tui["Log TUI<br/>[app.py]"]
  node_renderers["Log Renderers<br/>[renderers.py]"]
end

node_agent(("AI Agent / User"))

node_agent -->|"runs commands"| node_cli
node_agent -->|"invokes tools"| node_mcp
node_cli -->|"sends commands"| node_driverconn
node_mcp -->|"uses connection"| node_driverconn
node_mcp -->|"exposes tools"| node_vcadtools
node_vcadtools -->|"requests evaluation"| node_vcadconn
node_vcadtools -->|"resolves imports"| node_driverconn
node_vcadtools -->|"checks revisions"| node_dag
node_vcadtools -->|"places mesh"| node_runtimevcad
node_vcadtools -->|"pushes updates"| node_relay
node_main -->|"starts bridge"| node_bridge
node_main -->|"starts REPL"| node_repl
node_main -->|"loads tools"| node_runtimevcad
node_driverconn -->|"sends JSON-RPC"| node_bridge
node_bridge -->|"dispatches requests"| node_rubytools
node_bridge -->|"dispatches VCAD"| node_runtimevcad
node_runtimevcad -.->|"requests evaluation"| node_sidecar
node_vcadconn -->|"sends requests"| node_sidecar
node_sidecar -->|"loads settings"| node_config
node_sidecar -->|"evaluates requests"| node_evaluator
node_evaluator -->|"resolves imports"| node_imports
node_evaluator -->|"registers meshes"| node_mesh
node_evaluator -->|"exports geometry"| node_dae
node_evaluator -->|"evaluates modules"| node_modules
node_runtimevcad -.->|"uses modeling helpers"| node_stdlib
node_relay -.->|"relays preview"| node_viewerclient
node_viewer -->|"connects client"| node_viewerclient
node_radarcli -->|"starts ingestion"| node_ingest
node_ingest -->|"reads log streams"| node_tailer
node_ingest -->|"normalizes lines"| node_normalizer
node_ingest -->|"appends events"| node_buffer
node_radarcli -->|"launches interface"| node_tui
node_tui -->|"displays events"| node_buffer
node_tui -->|"renders entries"| node_renderers

click node_cli "https://github.com/darwin/supex/blob/main/driver/src/supex_driver/cli/main.py"
click node_mcp "https://github.com/darwin/supex/blob/main/driver/src/supex_driver/mcp/mcp_server.py"
click node_driverconn "https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/sketchup_connection.py"
click node_vcadtools "https://github.com/darwin/supex/blob/main/driver/src/supex_driver/mcp/vcad_tools.py"
click node_vcadconn "https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/vcad_connection.py"
click node_dag "https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/vcad_dag.py"
click node_relay "https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/vcad_viewer_relay.py"
click node_main "https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/main.rb"
click node_bridge "https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/bridge_server.rb"
click node_rubytools "https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/tools.rb"
click node_runtimevcad "https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/vcad_tools.rb"
click node_repl "https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/repl_server.rb"
click node_stdlib "https://github.com/darwin/supex/blob/main/stdlib/src/supex_stdlib/geom.rb"
click node_sidecar "https://github.com/darwin/supex/blob/main/vcad/sidecar/src/server.rs"
click node_evaluator "https://github.com/darwin/supex/blob/main/vcad/sidecar/src/evaluator.rs"
click node_imports "https://github.com/darwin/supex/blob/main/vcad/sidecar/src/imports.rs"
click node_mesh "https://github.com/darwin/supex/blob/main/vcad/sidecar/src/mesh_registry.rs"
click node_dae "https://github.com/darwin/supex/blob/main/vcad/sidecar/src/dae_export.rs"
click node_modules "https://github.com/darwin/supex/blob/main/vcad/sidecar/src/modules.rs"
click node_config "https://github.com/darwin/supex/blob/main/vcad/sidecar/src/config.rs"
click node_viewer "https://github.com/darwin/supex/blob/main/vcad/viewer/src/App.tsx"
click node_viewerclient "https://github.com/darwin/supex/blob/main/vcad/viewer/src/DriverRelayClient.ts"
click node_radarcli "https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/cli.py"
click node_ingest "https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/ingest.py"
click node_tailer "https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/tailer.py"
click node_normalizer "https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/normalizer.py"
click node_buffer "https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/buffer.py"
click node_tui "https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/tui/app.py"
click node_renderers "https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/tui/renderers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp,node_driverconn,node_vcadtools,node_vcadconn,node_dag,node_relay,node_agent toneBlue
class node_main,node_bridge,node_rubytools,node_runtimevcad,node_repl toneAmber
class node_stdlib toneMint
class node_sidecar,node_evaluator,node_imports,node_mesh,node_dae,node_modules,node_config,node_viewer,node_viewerclient toneRose
class node_radarcli,node_ingest,node_tailer,node_normalizer,node_buffer,node_tui,node_renderers toneIndigo
```

## Components

### Python Driver

- [CLI](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/cli/main.py): `driver/src/supex_driver/cli/main.py`
- [MCP Server](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/mcp/mcp_server.py): `driver/src/supex_driver/mcp/mcp_server.py`
- [SketchUp Connection](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/sketchup_connection.py): `driver/src/supex_driver/connection/sketchup_connection.py`
- [VCAD Tools](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/mcp/vcad_tools.py): `driver/src/supex_driver/mcp/vcad_tools.py`
- [VCAD Connection](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/vcad_connection.py): `driver/src/supex_driver/connection/vcad_connection.py`
- [Dependency DAG](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/vcad_dag.py): `driver/src/supex_driver/connection/vcad_dag.py`
- [Viewer Relay](https://github.com/darwin/supex/blob/main/driver/src/supex_driver/connection/vcad_viewer_relay.py): `driver/src/supex_driver/connection/vcad_viewer_relay.py`

### SketchUp Runtime

- [Runtime Startup](https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/main.rb): `runtime/src/supex_runtime/main.rb`
- [JSON-RPC Bridge](https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/bridge_server.rb): `runtime/src/supex_runtime/bridge_server.rb`
- [Ruby Execution Tools](https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/tools.rb): `runtime/src/supex_runtime/tools.rb`
- [VCAD Placement](https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/vcad_tools.rb): `runtime/src/supex_runtime/vcad_tools.rb`
- [Ruby REPL](https://github.com/darwin/supex/blob/main/runtime/src/supex_runtime/repl_server.rb): `runtime/src/supex_runtime/repl_server.rb`

### Ruby Modeling Utilities

- [Modeling Helpers](https://github.com/darwin/supex/blob/main/stdlib/src/supex_stdlib/geom.rb): `stdlib/src/supex_stdlib/geom.rb`

### VCAD Geometry

- [Sidecar Server](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/server.rs): `vcad/sidecar/src/server.rs`
- [Loon Evaluator](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/evaluator.rs): `vcad/sidecar/src/evaluator.rs`
- [Import Resolution](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/imports.rs): `vcad/sidecar/src/imports.rs`
- [Mesh Registry](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/mesh_registry.rs): `vcad/sidecar/src/mesh_registry.rs`
- [DAE Export](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/dae_export.rs): `vcad/sidecar/src/dae_export.rs`
- [Module Provider](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/modules.rs): `vcad/sidecar/src/modules.rs`
- [Sidecar Config](https://github.com/darwin/supex/blob/main/vcad/sidecar/src/config.rs): `vcad/sidecar/src/config.rs`
- [Live Preview Viewer](https://github.com/darwin/supex/blob/main/vcad/viewer/src/App.tsx): `vcad/viewer/src/App.tsx`
- [Relay Client](https://github.com/darwin/supex/blob/main/vcad/viewer/src/DriverRelayClient.ts): `vcad/viewer/src/DriverRelayClient.ts`

### Radar Logs

- [Radar CLI](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/cli.py): `devtools/radar/src/radar/cli.py`
- [Log Ingestion](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/ingest.py): `devtools/radar/src/radar/ingest.py`
- [Log Tailer](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/tailer.py): `devtools/radar/src/radar/tailer.py`
- [Event Normalizer](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/normalizer.py): `devtools/radar/src/radar/normalizer.py`
- [Event Buffer](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/buffer.py): `devtools/radar/src/radar/buffer.py`
- [Log TUI](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/tui/app.py): `devtools/radar/src/radar/tui/app.py`
- [Log Renderers](https://github.com/darwin/supex/blob/main/devtools/radar/src/radar/tui/renderers.py): `devtools/radar/src/radar/tui/renderers.py`

### Other components

- **AI Agent / User**

## Connections

- AI Agent / User → CLI: runs commands
- AI Agent / User → MCP Server: invokes tools
- CLI → SketchUp Connection: sends commands (evidence: `driver/src/supex_driver/cli/main.py`)
- MCP Server → SketchUp Connection: uses connection (evidence: `driver/src/supex_driver/mcp/mcp_server.py`)
- MCP Server → VCAD Tools: exposes tools (evidence: `driver/src/supex_driver/mcp/mcp_server.py`)
- VCAD Tools → VCAD Connection: requests evaluation (evidence: `driver/src/supex_driver/mcp/vcad_tools.py`)
- VCAD Tools → SketchUp Connection: resolves imports (evidence: `driver/src/supex_driver/mcp/vcad_tools.py`)
- VCAD Tools → Dependency DAG: checks revisions (evidence: `driver/src/supex_driver/mcp/vcad_tools.py`)
- VCAD Tools → VCAD Placement: places mesh (evidence: `driver/src/supex_driver/mcp/vcad_tools.py`)
- VCAD Tools → Viewer Relay: pushes updates (evidence: `driver/src/supex_driver/mcp/vcad_tools.py`)
- Runtime Startup → JSON-RPC Bridge: starts bridge (evidence: `runtime/src/supex_runtime/main.rb`)
- Runtime Startup → Ruby REPL: starts REPL (evidence: `runtime/src/supex_runtime/main.rb`)
- Runtime Startup → VCAD Placement: loads tools (evidence: `runtime/src/supex_runtime/main.rb`)
- SketchUp Connection → JSON-RPC Bridge: sends JSON-RPC
- JSON-RPC Bridge → Ruby Execution Tools: dispatches requests (evidence: `runtime/src/supex_runtime/bridge_server.rb`)
- JSON-RPC Bridge → VCAD Placement: dispatches VCAD (evidence: `runtime/src/supex_runtime/bridge_server.rb`)
- VCAD Placement → Sidecar Server: requests evaluation
- VCAD Connection → Sidecar Server: sends requests
- Sidecar Server → Sidecar Config: loads settings (evidence: `vcad/sidecar/src/main.rs`)
- Sidecar Server → Loon Evaluator: evaluates requests (evidence: `vcad/sidecar/src/server.rs`)
- Loon Evaluator → Import Resolution: resolves imports (evidence: `vcad/sidecar/src/evaluator.rs`)
- Loon Evaluator → Mesh Registry: registers meshes (evidence: `vcad/sidecar/src/evaluator.rs`)
- Loon Evaluator → DAE Export: exports geometry (evidence: `vcad/sidecar/src/evaluator.rs`)
- Loon Evaluator → Module Provider: evaluates modules (evidence: `vcad/sidecar/src/evaluator.rs`)
- VCAD Placement → Modeling Helpers: uses modeling helpers
- Viewer Relay → Relay Client: relays preview
- Live Preview Viewer → Relay Client: connects client (evidence: `vcad/viewer/src/App.tsx`)
- Radar CLI → Log Ingestion: starts ingestion (evidence: `devtools/radar/src/radar/cli.py`)
- Log Ingestion → Log Tailer: reads log streams (evidence: `devtools/radar/src/radar/ingest.py`)
- Log Ingestion → Event Normalizer: normalizes lines (evidence: `devtools/radar/src/radar/ingest.py`)
- Log Ingestion → Event Buffer: appends events (evidence: `devtools/radar/src/radar/ingest.py`)
- Radar CLI → Log TUI: launches interface (evidence: `devtools/radar/src/radar/cli.py`)
- Log TUI → Event Buffer: displays events (evidence: `devtools/radar/src/radar/tui/app.py`)
- Log TUI → Log Renderers: renders entries (evidence: `devtools/radar/src/radar/tui/app.py`)