Sketchup-Booth-Designer/docs/ARCHITECTURE.md

# Architecture

## System Overview

The Expolinc Booth Designer connects three layers: the **AI assistant**, the **MCP server bridge**, and **FreeCAD** acting as the geometry engine.

```
┌──────────────────────────────────────────────────┐
│                  AI Assistant                     │
│         (Claude Desktop / Claude Code)            │
│  "build a 4x3m island booth with 2 backlit walls" │
└──────────────────────┬───────────────────────────┘
                       │  MCP protocol (stdio JSON-RPC)
                       ▼
┌──────────────────────────────────────────────────┐
│              MCP Server (Node.js/TS)              │
│                                                   │
│  ┌─────────────────┐  ┌──────────────────────┐   │
│  │ Built-in tools   │  │ Expolinc tools       │   │
│  │ (165 tools from  │  │ 12 custom tools:     │   │
│  │  freecad-mcp)    │  │ build_booth,         │   │
│  │                  │  │ create_wall,         │   │
│  │ - BIM primitives │  │ export_bom,          │   │
│  │ - Part operations│  │ arrange_layout, ...  │   │
│  │ - TechDraw       │  └──────────────────────┘   │
│  │ - Import/Export  │                              │
│  └─────────────────┘                              │
│                                                   │
│  ┌──────────────────────────────────────────────┐ │
│  │             Layout Engine                     │ │
│  │  Interprets booth spec → wall positions →    │ │
│  │  component list → placement coordinates       │ │
│  └──────────────────────────────────────────────┘ │
│                                                   │
│  ┌──────────────────────────────────────────────┐ │
│  │             BOM Generator                     │ │
│  │  Component count, weights, transport cases,  │ │
│  │  SEG graphic area, part numbers              │ │
│  └──────────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────────┘
                       │  TCP JSON-RPC :12345
                       ▼
┌──────────────────────────────────────────────────┐
│              FreeCAD (GUI or headless)            │
│                                                   │
│  ┌──────────────────────────────────────────────┐ │
│  │         ExpolincLib (Python)                  │ │
│  │                                               │ │
│  │  classic_frame.py  ── App::FeaturePython      │ │
│  │  light_frame.py    ── Parametric objects      │ │
│  │  connectors.py     ── Placement helpers       │ │
│  │  accessories.py    ── Storage, doors, etc.    │ │
│  │  layouts.py        ── Assembly builder        │ │
│  │  bom.py            ── Spreadsheet output      │ │
│  └──────────────────────────────────────────────┘ │
│                                                   │
│  ┌──────────────────────────────────────────────┐ │
│  │         FreeCAD Workbenches Used              │ │
│  │  - Part (primitives, booleans)               │ │
│  │  - PartDesign (sketches, pads, pockets)      │ │
│  │  - BIM (walls, slabs for booth structure)    │ │
│  │  - TechDraw (dimensioned drawings)           │ │
│  │  - Spreadsheet (BOM data)                    │ │
│  └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```

## Data Flow

### Booth Creation Flow

```
User: "Build a 6x4m island booth with 2.5m Classic Frame walls,
       backlit on walls 0 and 2, with a storage room"

1. MCP Server receives `expolinc_build_booth` tool call
2. Layout Engine parses parameters:
   - Layout: island (4 walls, open all sides)
   - Wall 0: 6000×2500mm Classic Frame + Light Frame backlit
   - Wall 1: 4000×2500mm Classic Frame
   - Wall 2: 6000×2500mm Classic Frame + Light Frame backlit
   - Wall 3: 4000×2500mm Classic Frame
   - Storage: 1950×1000×2500mm
3. Layout Engine computes wall positions:
   - Wall 0: position (0,0,0), rotation 0°
   - Wall 1: position (6000,0,0), rotation 90°
   - Wall 2: position (6000,4000,0), rotation 180°
   - Wall 3: position (0,4000,0), rotation -90°
   - 4× 90° corner connectors at each junction
   - Storage room attached to Wall 3
4. BOM Generator calculates:
   - 2× Classic Frame 4950mm + 2× extension profiles
   - 2× Light Frame 4950mm
   - 4× 90° corner connectors
   - 8× support feet
   - 1× Storage room kit
   - SEG graphic area: ~50 m²
   - Total weight: ~120 kg
   - Recommended transport: 2× Standard Case XL
5. FreeCAD creates:
   - 4 FCStd documents with parametric components
   - Assembly with placements
   - Spreadsheet with BOM data
6. Response returned with:
   - Document reference
   - BOM as structured data
   - Preview screenshot (if GUI mode)
```

### MCP Tool Dispatch

```
Client → MCP Server → freecad-mcp bridge → FreeCAD TCP server → ExpolincLib
```

Each Expolinc tool call:
1. Validates parameters at the MCP server level
2. Translates to FreeCAD Python script
3. Sends to FreeCAD via JSON-RPC
4. FreeCAD executes on main thread via task queue
5. Returns result (object IDs, geometry metadata, or file paths)

## Module Responsibilities

### ExpolincLib (Python, runs inside FreeCAD)

| Module | Responsibility |
|---|---|
| `classic_frame.py` | Create Classic Frame walls: aluminum profile frame, SEG graphic panel, support feet. Parameters: width, height, double_sided |
| `light_frame.py` | Create Light Frame backlit walls: LED frame, diffuser, LED strip, power supply housing. Parameters: width, height, led_temp, brightness |
| `connectors.py` | Create 90° corner connectors, 180° inline connectors, T-connectors. Handles placement alignment between adjacent walls |
| `accessories.py` | Create storage rooms (enclosed box frame + door), hinged/pocket doors, shelves, bridge connectors between parallel walls |
| `layouts.py` | Orchestrate wall placement for each layout type. Computes positions from booth dimensions. Handles corner alignment |
| `bom.py` | Traverse the document tree, enumerate Expolinc components, collect parameters, output CSV/JSON/spreadsheet |
| `specs.py` | Official Expolinc dimensional specs, weight tables, available sizes, material properties |

### MCP Server Extension (TypeScript, runs as MCP stdio server)

| Module | Responsibility |
|---|---|
| `server.ts` | Extends freecad-mcp with Expolinc tool registration, parameter validation, error handling |
| `expolinc_tools.ts` | Tool definitions: parameter schemas, descriptions, FreeCAD script generation |
| `layout_engine.ts` | Booth geometry math: wall positioning, corner fitting, grid alignment (990mm grid) |
| `bom_generator.ts` | Parse BOM response from FreeCAD, format as CSV/JSON, calculate totals |

## Data Sources

All Expolinc specification data (dimensions, weights, materials, LED specs) is sourced from:

1. **Expolinc official website** — product pages for Classic Frame and Light Frame list exact weights per size
2. **Expolinc Catalog 2020/2021** (PDF) — full product catalog with dimensions
3. **Expolinc Panel Guide 2024** (PDF) — SEG graphic panel specifications
4. **SketchUp 3D Warehouse** (`3dwarehouse.sketchup.com/by/expolinc`) — official 3D models for dimensional reference
5. **Expolinc Google Drive** — per-product folders with CAD files, setup instructions, templates

All weight data has been verified against the official website. The 3D models are SketchUp format (.skp) and serve as reference for profile cross-sections and connector details — they cannot be directly converted to parametric FreeCAD FeaturePython objects.

## FreeCAD Configuration

### GUI Mode (recommended for design)

FreeCAD runs with UI visible. The MCP server connects via the TCP addon. Users see changes live in the 3D viewport.

### Headless Mode (for automation / CI)

FreeCAD is imported as a Python module (`freecadcmd`). No GUI. Suitable for batch BOM generation or scripted production of standard booth layouts.

## Port Layout

| Port | Service | Protocol |
|---|---|---|
| `12345` | freecad-mcp addon (TCP) | JSON-RPC |
| `12346` | ExpolincLib internal | JSON-RPC (optional) |
| `stdin/stdout` | MCP server ↔ AI assistant | JSON-RPC (MCP) |