Source map

CAD and drawing

Begin at packages/core/src/index.ts to see namespace exports. packages/core/src/cad/index.ts lists CAD APIs; packages/core/src/drawing/index.ts lists drawing operations.

• cad/sketch.ts, sketch-shapes.ts, snap.ts, intersect.ts: sketch data, shapes, snapping, and intersection.
• cad/history.ts, history-edit.ts, history-brep.ts: feature history, edits, and B-rep reconstruction.
• cad/brep/, solid.ts, tessellate.ts: solid topology, modelling, and renderable meshes.
• cad/import-step.ts, dxf.ts, and import-drawing.ts: exchange and import boundaries.
• cad/scene-analysis.ts, scene-evidence.ts, dfm.ts: scene analysis, evidence, and manufacturability checks.

Keep import parsing, exact geometry, tessellation, and viewport selection separate when tracing a display issue. A visible mesh may have a different origin from an editable parametric feature.

CAM and G-code

• packages/core/src/cam/index.ts: public CAM namespaces and exports.
• cam/operations/ and cam/generator/: operation implementations and generation pipeline.
• cam/setup.ts, indexing.ts, ir.ts: setup frames, indexed machining, and intermediate motion representation.
• cam/post/index.ts, emitter.ts, and the dialect files: registered posts and shared program emission.
• cam/post/convert.ts: the NC conversion kernel: replays G-code or Klartext, rewrites it with any post and proves the motion by replay.
• cam/verify/, kernel/, model/, and viewer/: verification, machining kernels, models, and viewer helpers.

Trace persisted machining through apps/sidecar/src/http/toolpaths.ts and src/services/cam-program.ts, then into the desktop CAM feature. The setups reference explains how portable program documents relate to saved toolpaths.

HTTP and persistence

• packages/api/src/index.ts, groups/, errors.ts, auth.ts: endpoint contracts, wire errors, and authorization declarations.
• packages/api/src/client.ts: full contract-based Effect client with bearer middleware.
• packages/api/scripts/generate-clients.ts: target outputs and explicit generation exclusions.
• packages/httpapi-codegen/src/index.ts: contract reflection, validation, and client emitters.
• apps/sidecar/src/main.ts, config.ts, layers.ts: server lifecycle, configuration, and dependency wiring.
• apps/sidecar/src/http/, services/, repos/: protocol adapters, application operations, and persistence access.
• packages/db/src/index.ts, schema.ts, upgrade.ts, migrate.ts: database service, tables, upgrade safety, and CLI.
• packages/db/drizzle/: generated migrations and metadata shipped with the desktop.

Desktop and mobile

apps/desktop/src/app/App.tsx, Shell.tsx, and routes.tsx assemble the workbench and routes. client.ts and sidecar.ts handle API access and native connection state. Product behavior lives under src/features; shared controls and state live under src/shared.

The viewport is under apps/desktop/src/viewport, split into editor2d, view3d, and spatial. Native commands and lifecycle are under apps/desktop/src-tauri/src; packaging configuration is src-tauri/tauri.conf.json.

Mobile routes are under apps/mobile/app, reusable components under components, and client/pairing logic under lib. The native socket module is modules/companion-net. On the server, start companion tracing at apps/sidecar/src/http/companion.ts and services/companion.ts.

AI, plugins, history, and workflows

• packages/ai/src/actions and tools: action declarations and assistant tool integration.
• packages/ai/src/nikcli, prompts, and skills: embedded host integration and assistant guidance.
• apps/sidecar/src/services/ai.ts: live AI dependencies and host selection.
• packages/nikcli-plugin/src/index.ts: external nikcli HTTP bridge.
• packages/plugin-sdk/src/index.ts and apps/sidecar/src/plugins/host.ts: plugin authoring surface and runtime host.
• packages/vcs/src/index.ts, apps/sidecar/src/services/project-vcs.ts, and repos/project-vcs-repo.ts: history library, orchestration, and persistence.
• packages/workflow/src/index.ts, apps/sidecar/src/services/workflow-runner.ts, and workflow-service-steps-live.ts: workflow contract, execution, and service step registration.

Version control lives in packages/vcs/src: object.ts (git object format), repository.ts (refs and commits), snapshot.ts, diff.ts, store.ts, transport.ts, and github.ts. Workflows live in packages/workflow/src: schema.ts, trigger.ts (glob and trigger matching), and run.ts. Workflow files are read from .cadcamfun/workflows/ in the project tree.

Documentation and delivery

packages/web/src/pages/docs contains the documentation articles. src/layouts/DocsLayout.astro provides the shared article shell. Navigation and retrieval copy are in src/data/docsSidebar.ts and docsIndex.ts; shared package descriptions are in architecture.ts.

src/lib/docsMarkdown.ts converts rendered articles to Markdown for src/pages/llm.ts and the documentation assistant. Retrieval is in docsRetrieval.ts; assistant execution is in src/pages/api/docs-assistant.ts. Artifact parsing and storage helpers are in src/lib/docsArtifact.ts.

packages/web/script/dev.ts starts Astro and the local Studio process. studio-server.ts owns the local SQLite overview API. astro.config.mjs configures prerendering infrastructure and the local proxy; wrangler.toml declares Worker bindings.

Desktop compilation and release staging start in scripts/build.ts. CI and release workflows are under .github/workflows. See Release and updates for artifact generation and signing requirements.

Trace behavior across boundaries

1. Identify the endpoint in the resource reference and read its parameter, body, response, and error schemas.
2. Locate its HttpApi declaration in the API root composition. Some foundational resources, including projects, live directly under packages/api/src; other groups live under src/groups.
3. Find its handler under apps/sidecar/src/http. Read the current-user and resource checks before following its service or repository call.
4. For calculation, continue into core. For storage, continue through the repository and Database.query. For provider/network behavior, inspect the configured adapter.
5. Return to the desktop or mobile caller and inspect its envelope handling, session state, cancellation, and error display.

For example, a missing name in project creation is rejected in apps/sidecar/src/http/projects.ts; it is not a SQLite error. A portable CAM document mismatch is checked by apps/sidecar/src/services/cam-program.ts; parsing NC in the viewport cannot bypass it. A paired phone route refusal originates in the companion gateway's method/path policy.

Directory tree with file counts

apps/
  desktop/src/          app/ 13  features/ 280  pages/ 68  shared/ 44  viewport/ 25  i18n/ 1
  desktop/src-tauri/src commands.rs lib.rs main.rs menu.rs secrets.rs sidecar.rs tray.rs updater.rs
  sidecar/src/          http/ 34  repos/ 24  services/ 29  plugins/ 3   (+ main.ts, config.ts, layers.ts)
  mobile/               app/ 13  components/ 30  lib/ 21  hooks/ 2  modules/ 2
packages/
  core/src/             cad/ 80  cam/ 110  drawing/ 7
  ai/src/               actions/ 14  nikcli/ 27  tools/ 26  prompts/ 5  skills/ 2
  api/src/              groups/ (one file per group)  sdk/generated/  client/generated/
  db/                   src/ (index, schema, upgrade, migrate)  drizzle/ (4 migrations)
  vcs/ workflow/ plugin-sdk/ httpapi-codegen/ nikcli-plugin/ web/
scripts/                build.ts compile-sidecar.ts stage-release.ts updater-manifest.ts
                        release-helpers.ts release-ref.ts signing-config.ts smoke-sidecar.ts
.github/workflows/      ci.yml release.yml build-platforms.yml ios.yml

Desktop feature folders

Each folder under apps/desktop/src/features/ owns one product area's components, state and API calls:

admin  ai  analytics  auth  billing  cad  cam  chat  companion  costs  dashboard
legal  library  marketplace  mcp  organizations  plugins  profile  projects  settings  toolpaths

A feature calls the sidecar through the shared API client; shared widgets live in shared/ and the 3D scene in viewport/.

Where CAD concepts live in core

In 3D