Helicity and WBK — system maps

Main flow

Follow the top row first. Supporting components and possible failure outcomes appear below.

Read at 100% for full-size text; use Fit for the overall layout. Scroll inside the diagram to follow longer paths. Each interaction has one label.

Source files behind this diagram

Open the watch editor
src/main.js src/editor.js

Change the watch
src/editor.js src/design-panel.js src/watch-model.js

See and inspect the watch
src/editor.js src/inspection.js

Who remembers the design?
src/lab-preferences.js docs/ENGINE.md docs/RELEASES.md

Which choices are allowed?
src/component-library.js src/engine-contract.js

View settings are separate
src/editor.js src/lume-lighting.js

Choosing a part

An accepted choice replaces only the affected parts. A rejected choice leaves the previous watch intact.

90%Open diagram Editable board

2. What happens when you choose a different part

Read at 100% for full-size text; use Fit for the overall layout. Scroll inside the diagram to follow longer paths. Each interaction has one label.

Source files behind this diagram

You pick an option
src/design-panel.js src/component-library.js

Check the proposed watch
src/component-library.js:createDesignSession src/editor.js:beforeChange

Build and show the change
src/watch-model.js:setSelections

Apply the selection rules
src/component-library.js src/watch-model.js

Make the visible shapes
src/watch.js src/nh35-movement.js src/lume-regions.js

Tell the host what changed
src/editor.js:onChange src/editor.js:onSaveRequest

Changing the view

Camera, lighting and presentation change how you see the same watch.

90%Open diagram Editable board

3. What happens when you change the view

Read at 100% for full-size text; use Fit for the overall layout. Scroll inside the diagram to follow longer paths. Each interaction has one label.

Source files behind this diagram

You use a view control
src/editor.js src/editor-template.html

Update the view settings
src/editor.js src/view-camera.js

Draw the next frame
src/editor.js src/lume-glow.js

Camera and part inspection
src/view-camera.js src/inspection.js

Move the parts
src/assembly-controller.js src/presentation.js

Change the lighting
src/lume-lighting.js src/lume-regions.js

Lab system

Everything needed to draw the watch runs in your browser. Only the tiny wrist-tone cycle survives reload.

90%Open diagram Editable board

Helicity Lab — what runs where, and what is saved

Read at 100% for full-size text; use Fit for the overall layout. Scroll inside the diagram to follow longer paths. Each interaction has one label.

Source files behind this diagram

Static hosting
docs/RELEASING.md vite.config.js

Lab page and watch editor
src/main.js src/editor.js

Helicity engine
src/engine.js src/engine-contract.js src/watch-model.js

Temporary browser memory
src/main.js src/editor.js

Browser local storage
src/lab-preferences.js

WBK system

The browser draws the watch; WBK’s backend saves records and manages image files.

90%Open diagram Editable board

WatchBuildKit — UI, backend and durable storage

Read at 100% for full-size text; use Fit for the overall layout. Scroll inside the diagram to follow longer paths. Each interaction has one label.

Source files behind this diagram

WBK browser interface
frontend/components/design-3d-editor.tsx frontend/lib/api/client.ts

Bundled Helicity Studio
frontend/lib/helicity-editor.ts frontend/lib/helicity-engines.js

Next.js web application
frontend/next.config.ts frontend/lib/api/server.ts

FastAPI backend
app/main.py app/design_visualization.py app/helicity_contract.py

PostgreSQL database
app/models.py app/db.py

Managed upload folder
app/storage.py app/media_storage.py

Workspace backup archive
app/backup_bundle.py scripts/save_backup.py

AI image provider
app/openai_mockup.py

WBK records

These are the main record groups and optional handoffs, not a complete table schema.

90%Open diagram Editable board

WatchBuildKit — the main records and their relationships

Read at 100% for full-size text; use Fit for the overall layout. Scroll inside the diagram to follow longer paths. Each interaction has one label.

Source files behind this diagram

Design and revisions
app/models.py app/design_revisions.py

Sourcing and purchases
app/models.py

Build and physical work
app/models.py

Watch and configurations
app/models.py

Suppliers and products
app/models.py

Inventory and movements
app/models.py

The important boundaries

Concern	Helicity Lab	WatchBuildKit
Watch drawing	Shared editor and engine in the browser.	The same browser editor, bundled into WBK. It does not call the Lab website to render.
Saving	Current watch stays in memory. Built-in starting designs ship with the app.	Designs and revisions live in PostgreSQL. Uploaded and generated image bytes live in managed files.
Versions	Uses the engine bundled with the current Lab build.	Saved visual documents pin an engine. Retained engines keep older designs readable without silent migration.
AI images	No persistent AI image workflow.	Optional mockups become image assets. They are separate from the editable 3D design.
Real parts and work	Visual component choices; no purchasing or build records.	Sourcing, purchases, inventory, physical builds and watch history are separate records.

Retained engines: the nine current WBK engine folders total about 13 MB. A version is shared by all designs using it, not copied per design. This excludes application builds and dependencies.

Architecture source snapshot: October 7, 2026 — Lab 0.6.3 / Engine 0.3.3; WBK 0.4.2.