massing: Instructions file for Claude Code

Project: Massing

What this is

A standalone web BIM modeling program + data platform for AEC firms. IFC is the source of truth. The web app is a genuine authoring tool: create a model from scratch (blank IFC → levels/grid datum), then draw walls/columns/slabs/families/MEP via server-side GUID-stable edit recipes — not just a viewer. (Directional change, 2026-07: in-browser authoring is now a first-class goal, reversing the earlier "web = viewer, Blender = editor" split.) Blender/Bonsai remains an optional advanced/interop editor, not the required one. RVT support is an optional, paid Autodesk bridge — never assume RVT can be read offline.

Non-negotiables

• Reference model elements by IFC GlobalId (GUID), never by transient viewer IDs.
• Pre-convert IFC to Fragments on the server; never parse full IFC in the browser at runtime.
• Keep geometry and metadata separate: geometry streams as .frag; data comes from the API.
• Pins/RFIs/punchlist follow the BCF model so they round-trip with other BIM tools.
• The viewer must run fully offline (local WASM, self-hosted tiles).

Stack

• Web: Vite + TS, web-ifc, @thatopen/{fragments,components,components-front,ui}, three (pinned pair).
• Services: Python, ifcopenshell, FastAPI, SQLAlchemy/Postgres, MinIO.
• Editor: Blender + Bonsai, driven via Bonsai-MCP.
• Optional: Autodesk APS Model Derivative (RVT→IFC), behind a feature flag with a cost warning.

Build order

Phase 0 smoke tests → 1 conversion → 2 large-model → 3 viewer/tools → 4 API/BCF → 5 data export → 6 editor/families → 7 deploy.

Watch out for

• @thatopen/components and @thatopen/fragments version coupling — pin a compatible pair.
• Bonsai-MCP execute_blender_code runs arbitrary Python: gate it, save first, chunk big ops.
• Set-origin/georeferencing: preserve real coordinates for export, render near scene origin.

Local environment notes (this machine)

• Bare node now resolves to v24.18.0 — the PATH workaround this line demanded is obsolete (re-measured 2026-08-27). which node → /c/Program Files/nodejs/node → v24.18.0, npm 11.16.0. v18.8.0 is still installed, at /c/laragon/bin/nodejs/node-v18/node, but it sits later on PATH and you no longer get it by default. export PATH="/c/Program Files/nodejs:$PATH" is therefore belt-and-braces, not a requirement — harmless to keep, and worth keeping in scripts, because the thing that changed is PATH order, which can change back the moment laragon updates. Both manifests declare "engines": {"node": ">=24"} and CI pins node-version: 24, so 24 is the supported baseline. This is the fourth wrong value in these three lines, and the first to be wrong in the safe direction: v20.3.1, then a version naming the Node you get after fixing PATH, then a major nobody had run in weeks — and now a workaround that outlived its cause. A stale instruction to do something unnecessary costs less than a stale one to skip something, but it still teaches the reader that this file is not to be trusted, which is the expensive part. A config file that is subtly wrong is worse than one that is silent — four drifts in, the only safe move is which node && node -v, never reading this line.
• Python ≥ 3.12 is now a HARD FLOOR, not a preference (corrected 2026-08-25; this line said "guide targets ≥ 3.11" and "prefer a 3.11+ interpreter … if available"). requirements.lock pins numpy==2.5.2, and numpy dropped <3.12 at 2.5.0 — so on 3.11 the install does not degrade, it fails outright: No matching distribution found for numpy==2.5.2. CI pins python-version: "3.12" in ci.yml, db-migrations.yml, desktop.yml and security.yml, and the lock is compiled in python:3.12-slim, the prod base image. Same failure as the Node line above, in the other language: a floor that moved under a note phrased as advice. "Prefer if available" is what a version note says when nobody has tried the alternative — and the alternative had stopped working. Check a floor by creating the venv, not by reading this line.
• RESOLVED 2026-08-27: 3.12.10 installed, and services/api/.venv now MEETS the floor. This entry previously said the venv could not meet it and that CI was therefore the only authority for the backend. Both halves are now out of date, and the reason it had drifted was not the one recorded here.