Guides and workflows

Choose a guide

• Quickstart: install dependencies, start the desktop, and locate its database.
• Install: download a published desktop build, check its checksum, and tell it apart from a source checkout.
• Accounts: edit profile, password, API keys, and git identity in local Studio.
• Local development: run a browser preview or real sidecar, configure processes, and diagnose startup.
• Contributing code: locate modules, change shared contracts, and select checks.
• Packages: navigate workspace responsibilities and public entry points.

The desktop, sidecar, companion, and documentation site have different launch commands and persistence models. Choose the runtime that exercises the behavior you are changing. A browser fixture is useful for screen work; database, streaming, and authorization changes need the real server.

Understand the runtime

The core package implements geometry, toolpaths, posts, and verification. The API package defines shared schemas, endpoints, and generated clients. The sidecar combines those contracts with repositories, SQLite, AI, plugins, version control, and workflow services. The desktop renders those services through a local API connection and native shell.

The iOS companion connects through a separate pinned HTTPS gateway. The web package runs the Astro documentation site and local Studio integration. These are separate clients and must not be assumed to share a database path or security context.

Common commands

bun install
bun run desktop:dev
bun run --filter @cadcamfun/desktop dev
bun run --cwd packages/web start

desktop:dev builds the real sidecar and stages migrations before opening Tauri. The desktop dev script starts Vite on port 1420; without a sidecar URL it uses an in-memory preview API. The web start script starts Astro only; its dev script also starts the local Studio API.

Migration generation is for schema changes, not an installation prerequisite. The database layer creates a new database and applies available migrations when opened. Consult the quickstart before choosing a CLI database path.

Root scripts are defined in the repository package.json: typecheck, test, build, build:sidecar, build:desktop, desktop:dev, generate, generate:check, db:generate, and db:migrate.

Start with a concrete flow

For desktop development, open a project, create or load a drawing, and inspect the CAD/CAM flow you intend to modify. Follow its route adapter into the feature screen and locate the API call and handler. For server work, use the schema, handler, service, and repository chain to identify where validation, ownership, and persistence happen.

For companion work, install a native iOS build, enable the desktop gateway, and pair through its QR code. For documentation work, start Astro, open the changed route, and run the web build to catch template and prerender errors.

Maintain clear boundaries

Keep credentials out of source, examples, logs, and browser screenshots. Use placeholders in documentation and provide runtime configuration through the supported process or application settings. Keep generated clients synchronized with their contract, and generate SQL migrations from the schema rather than editing generated migration files.

Use a separate disposable data directory for integration tests and local experiments. A preview fixture, CLI migration database, packaged application database, and companion gateway have distinct purposes; selecting one should be explicit.

Find the right workflow

Use a guide for a sequence of actions and the linked reference pages for field and behavior details. Keep the runtime choice explicit throughout the workflow: changing from a browser fixture to a native sidecar changes persistence, credentials, native capabilities, and error behavior.

Know what a check establishes

Different checks answer different questions. A TypeScript compiler can prove that a client call matches its generated signature. A handler test can prove the expected response under supplied layers. A native simulator run can exercise certificate pinning and app startup. None of these independently proves that a signed installer runs on every supported device or that a toolpath is safe for a specific machine.

1. Record the exact runtime and data directory used for the check.
2. Perform the operation through the boundary the user will use.
3. Inspect the resulting persisted state or exported artifact, not only a success toast.
4. Exercise the failure or cancellation path affected by the change.
5. Report any external service, signing, native-device, or graphics coverage still missing.

For deterministic integration work, use isolated SQLite directories and scripted/offline AI fixtures. For provider-specific behavior, separately exercise the configured provider with appropriate credentials. Example requests in these guides describe supported shapes; timestamps, identifiers, ports, and credentials vary per run.

Practical guides

These guides follow complete operations through the application and its API. Each includes the required inputs, the relevant state changes, and the failure cases to inspect. Use the subsystem references for underlying models and the API resource pages for exact field and response contracts.

Design and manufacture

Clients and extensions

Operations and recovery

New to a published build? Start at Install. New to the checkout? Begin with Quickstart. New to its HTTP behavior? Use the walkthrough with captured responses, then choose a typed client or a resource in the complete API reference.

Work through a complete task

Create a saved design

Create a project and retain the returned identifier. Create its drawing or component through the appropriate project-scoped collection. Edit geometry in the CAD workspace, save through that resource's actual feature action, and reopen the saved resource to establish that the intended document was persisted. The editor's current selection and command history are not a substitute for the stored drawing.

When two clients edit the same data, follow the endpoint's current update semantics rather than assume every resource has compare-and-swap protection. Read the project lifecycle guide for drawing/component differences, resource associations, access checks, and restore limits.

Produce a manufacturing result

Capture the geometry, placement, stock, material, machine, tools, and operation order. Run generation with those explicit inputs. Inspect the result's issues and applicable evidence; verify that the program and NC correspond to the intended snapshot. Saving is a separate operation and must retain a portable document consistent with the exact bytes being saved.

A changed cutter, stock, model, or work frame changes the job being evaluated. Reusing an earlier artifact after editing NC does not transfer its evidence to the new text. The native manufacturing guide explains preparation, generation, claims, persistence validation, and the difference between one integrated posted program and concatenated operation sections.

Integrate an assistant

Configure a provider on the desktop and verify its status before starting a conversation. Preserve the project and session identity, consume events incrementally, and implement permission and question replies through the admitted session controls. On disconnection, recover current state before resending a request that may have edited the project.

The streaming guide covers recovery, cancellation, and follow-up admission. The client guide explains why Promise result values, thrown HTTP bodies, Effect errors, and stream completion cannot be handled as one universal envelope.

Record and review a change

Save the working resource, inspect project status, and commit the intended state on the intended branch. Review the structural diff and open a local pull request when the change should be proposed rather than directly adopted. Resolve blocking review verdicts and conflicts before merging.

Version workflow definitions with the project, then inspect each run's selected commit and individual check outputs. A successful run that skipped its machining checks does not supply machining evidence. Read the branches and workflow guide before automating a writing step or configuring a remote mirror.

Operate a second client

Enable the companion gateway intentionally, create an individually named device pairing, and connect a native build that includes certificate pinning. Retain the full desktop address, fingerprint, and device token as the paired connection. Read the current route policy before assuming a phone is read-only or unrestricted.

When access should end, revoke the device from the desktop; removing the connection on the phone alone does not revoke the server-side token. The pairing guide separates network diagnosis, native transport availability, certificate identity, and token revocation.

Guides by task and time

In 3D