VEHICLE LAB / DOCUMENTATION

Architecture & extension points

Separate the project record from the tools that produce evidence. A CAD package authors geometry, a solver performs an experiment, and the notebook connects those outputs to the question being investigated.

Project manifest
  ├── Intent and constraints
  ├── Models → geometry adapter → verified display assets
  ├── Revisions → parent graph and decision record
  ├── Evidence → external engine → saved replay or result
  └── Stages → interactive studio → film and documentation

Modules

Module	Responsibility	Extension point
Project CLI	Initialize, import and validate projects.	Manifest schema and validation functions.
Geometry adapter	Pack authored tessellation with stable IDs and hashes.	Export parts from a CAD API or OBJ.
Replay adapter	Validate sampled rigid-body states.	Export poses from an external engine.
Browser studio	Inspect geometry and display recorded evidence.	Project stages and local asset references.
Analysis examples	Restricted formula graph, compact packaging trade and linkage closure.	Python inputs, equations and independent checks.
Publishing tools	Generate documentation, capture media and verify release surfaces.	Static source files and reproducible capture scripts.

Data flow and privacy

The supplied server binds to loopback, serves local files, rejects hidden paths and disables directory listings. It has no write API. Project commands write explicitly chosen local project files. The website contains no analytics, account integration, uploads or external font requests. Three.js is vendored. External documentation links open their own websites only when followed.

How it relates to other tools

FreeCAD and other CAD tools remain the geometry authoring environment. Chrono and other engines remain responsible for simulation. Vehicle Lab provides the surrounding project record, inspection and communication layer. The documentation organization takes inspiration from Chrono's overview, installation, manuals, tutorials and API reference; this project is independent and is not endorsed by Chrono.

Source distribution

release-files.json is the explicit distribution allowlist. The archive builder preflights the selected files and replaces the completed archive and checksum only after packaging succeeds. Unlisted notebooks, local state and repository history are excluded.

One archive publisher can replace outputs at a time. A competing publisher reports a conflict; retry after the active writer finishes. Errors or cancellation during replacement restore the previous pair. A forcibly terminated process can leave .local/dist/.promotion.lock and a recovery directory. Check the lock's process ID before clearing abandoned state. In an archive recovery directory, 0 and 1 hold the previous archive and checksum when those files existed. Keep recovery files until you have restored and verified the pair.

Current extension boundary

The format is usable today for static design studies and rigid-body replays. A plug-in loader, hosted collaboration, CAD regeneration service and automatic evolutionary search are not implemented. Add integrations through explicit file contracts before introducing a service layer.