BeaverFlow Lite

BeaverFlow Lite is a compact, local-first workflow editor for mechanical-engineering studies. It combines a typed node graph, deterministic YAML, cached execution, a persistent engineering viewport, server-isolated Zoo credentials, and repository-owned CalculiX/BESO workers.

The application never represents an unavailable integration or failed live solve as successful. Bundled screenshots and retained JSON/GLB files are explicitly precomputed evidence; they are not runtime fallbacks.

Demo video

Watch the BeaverFlow Lite demo on Cap

Features

• Typed, direction-aware ports with connection validation and cycle detection
• Deterministic YAML import/export and downstream cache invalidation
• Two editable executable examples: Zookeeper Gear static FEA and Parametric Beam static topology optimization
• Session-scoped Zoo key handling on the Fastify server
• STEP preprocessing with gmsh and real linear-static analyses with CalculiX
• A bounded, deterministic repository BESO loop driven by repeated CalculiX analyses
• Validated GLB, FEA, topology, report, and evidence presentation
• Truthful failed, cancelled, timeout, and nonconverged states

Validated toolchain

The 2026-08-06 live validation environment used exactly:

• Node.js 24.12.0
• pnpm 11.20.0
• Python 3.13.14
• gmsh 4.15.2
• CalculiX 2.23 via a machine-local BEAVERFLOW_CCX executable
• Zoo CLI 0.2.186
• repository BESO version repository-beso-1

Node and pnpm are required. Python, gmsh, and CalculiX are required to run solver nodes. A Zoo API key and Zoo CLI are required only for the Zoo-backed CAD paths that use them.

Install and run

corepack enable
pnpm install --frozen-lockfile
pnpm dev

Open http://127.0.0.1:5173. Vite proxies /api to Fastify at http://127.0.0.1:3001.

For Zoo-backed nodes, export a key before starting the server:

export ZOO_API_KEY="..."
pnpm dev

Alternatively, enter a session key in Settings. Session keys stay in server memory, are associated with an HttpOnly session cookie, and are not written to browser storage or disk. The application does not parse .env files; load a local file into the process environment yourself.

Configure the solver with the Python interpreter containing gmsh and an absolute executable CalculiX path:

export PYTHON=/absolute/path/to/python3
export BEAVERFLOW_CCX=/absolute/path/to/ccx
pnpm dev

If BEAVERFLOW_CCX is unset, the worker resolves ccx from PATH. If it is set, it must name an absolute executable file. PYTHON defaults to python3.

Try the examples

Use Examples in the top bar:

• Zookeeper Gear — Static FEA obtains gear geometry through Zoo, resolves the submitted support/load regions against STEP, meshes it with gmsh, and runs CalculiX.
• Parametric Beam — Static Topology Optimization creates deterministic KCL beam geometry and runs the repository BESO loop, with every baseline and post-update analysis executed by CalculiX.

Both files are versioned in examples/ and can be imported through the YAML dialog:

• examples/parametric-topology.yaml
• examples/zookeeper-fea.yaml

Solver model and units

The current solver is deliberately narrow:

• STEP is imported as exactly one solid and scaled to the submitted body dimensions when those dimensions are available.
• Geometry coordinates and displacements are metres; forces are newtons; elastic modulus and von Mises stress are pascals; density is kilograms per cubic metre; compliance is joules.
• Loads accept N or kN. Displacement constraints accept m, cm, or mm; stress constraints accept Pa, MPa, or GPa.
• The deck is small-strain, linear-elastic, linear-static: fixed support nodes constrain degrees of freedom 1–3, and each region force is distributed equally over its selected nodes.
• gmsh generates first-order tetrahedra and the deck uses CalculiX C3D4 elements.

C3D4 elements are constant-strain, first-order tetrahedra. Coarse meshes can be overly stiff in bending and can under-resolve stress gradients or local peaks. The reported values are mesh-dependent and are not a substitute for mesh-convergence studies, higher-order elements, contact/nonlinear modeling, or design certification.

For each analysis, the worker writes job.inp in a private temporary directory and invokes ccx job. CalculiX runs with LANG=C, LC_ALL=C, and the OpenMP/OpenBLAS/MKL thread counts fixed to one. Only PATH, platform runtime paths, and the dynamic-library paths needed to start the executable are retained. Each CalculiX analysis has a 300-second worker timeout; the server bounds the whole FEA job to 10 minutes and topology job to 30 minutes. Cancellation terminates the CalculiX process group. FRD displacement/stress and DAT reaction data must be complete and finite, and reaction/applied-force imbalance must not exceed 1%.

BESO behavior

solver/beso/run_topology.py is the repository implementation identified as repository-beso-1. It is original repository code, not a vendored third-party optimizer distribution. It uses CalculiX element strain energy per volume, deterministic spatial/adjacency filtering with temporal averaging, a 5% evolution rate, protected elements around support/load regions, and a soft-void stiffness/density ratio of 1e-6.

The baseline design consumes one CalculiX analysis. Every history entry is a completed post-update analysis, so analysisCount = 1 + iterationHistory.length. Convergence requires the applicable constraint utilization to be at most 1 and the changed-element fraction to be at most 0.005 for two consecutive iterations. Reaching maxIterations returns a structurally valid result with converged: false; it means nonconverged / maximum iterations, not a converged design. Solver execution, protocol, balance, timeout, or cancellation failures remain failed/cancelled jobs and are never replaced by precomputed data.

Viewer caveat

The viewer decodes a strict, bounded subset of embedded GLB 2.0 and renders validated inline solver meshes, fields, legends, and reports. STEP remains downloadable rather than directly rendered. The current support and load glyphs indicate that support/load data was reported, but they are fixed 2D overlay symbols: their screen positions and arrow direction are not derived from the selected 3D faces or load vector. Use the resolved-region evidence and numerical report—not the glyph placement—to audit boundary conditions.

Server API

Principal routes:

• GET /api/health
• GET /api/zoo/status
• POST|DELETE /api/zoo/session-key
• POST /api/jobs/zoo/{units,kcl,agent,properties,export}
• POST /api/jobs/geometry/face-selection
• POST /api/jobs/solver/{fea,topology}
• GET|DELETE /api/jobs/:jobId
• GET /api/artifacts/:artifactId
• DELETE /api/artifacts

See API_NOTES.md for exact adapter and error semantics.

Verify and live validation

Safe non-billable repository gate:

corepack enable
pnpm install --frozen-lockfile
pnpm verify

Safe version inspection (does not print credentials):

node --version
pnpm --version
/absolute/path/to/python3 --version
/absolute/path/to/python3 -c 'import gmsh; print(gmsh.__version__)'
/absolute/path/to/ccx -v
zoo --version

The full live solver validation uses real Zoo services and real solver binaries and can be billable. It refuses to start without both its opt-in and a Zoo key:

set -a
source .env
set +a
export PYTHON=/absolute/path/to/python3
export BEAVERFLOW_CCX=/absolute/path/to/ccx
BEAVERFLOW_ENABLE_LIVE_SOLVER_VALIDATION=1 pnpm validate:solver:live

pnpm probe:live is a separate billable Zoo adapter probe gated by BEAVERFLOW_ENABLE_LIVE_PROBE=1; Agent generation additionally requires BEAVERFLOW_ENABLE_AGENT_PROBE=1. Neither command runs in pnpm verify or CI.

Validation truth

At commit d74ebbafc9660a9832956d409cbc3c8ede7a1817, the latest pnpm verify passed 144 Vitest tests. The 41-test Python suite passed in the commit-only environment with its one real gmsh/ccx toolchain test skipped because those tools were unavailable there. Earlier, before the final integration fix, the full live environment passed 143/143 Vitest and 41/41 Python tests with the real toolchain. These are distinct runs; they must not be combined into a larger total.

Supplied live evidence includes:

• Beam FEA: displacement 0.0018682649434588984 m versus 0.001953125 m analytical (4.3448% relative error), maximum stress 85492598.44292949 Pa, force-balance relative error 4.0414848773921e-7.
• Direct bounded BESO: 21 analyses / 20 iterations, volume fraction 0.5499907444934679, compliance 1.7969994545454544 → 2.8515334545454545 J, active elements 8433 → 5401, maximum balance error 2.7061184080380857e-6, nonconverged / maximum iterations.
• Browser example topology: 61 analyses / 60 history entries, volume fraction 0.5499999290637684, compliance 1.8156791970802924 → 2.0597929562043786 J, active elements 50458 → 36967, maximum balance error 1.1507896140937236e-5, nonconverged / maxIterations.
• Browser Zookeeper gear FEA: displacement 0.00010078161295373426 m, maximum stress 45614395.11782024 Pa, force-balance relative error 1.9271950114611207e-8.

These metrics and the durable artifact/capture hashes are detailed in VALIDATION.md. They are precomputed release evidence only and never substitute for a failed live solve.

Security and persistence

• Zoo keys are read from the server environment or held in an in-memory session store.
• Keys are never returned by status routes or placed in workflow YAML or artifacts.
• Jobs and artifacts enforce session ownership.
• External errors are normalized; secrets and authorization headers are redacted.
• Subprocess input/output is bounded, timed out, abortable, and structurally validated.
• Browser persistence restores projects/editor state, not jobs, results, artifacts, credentials, or feedback.

This is a local engineering tool, not a multi-tenant hosted service or a certified analysis system.

Additional documentation

• API_NOTES.md
• VALIDATION.md
• DEPENDENCIES.md
• AI_CONTRIBUTIONS.md
• DEMO.md
• LICENSE