TeamCraft documentation

TeamCraft is an open-source product lifecycle management (PLM) system written in pure Rust: one binary that serves a web interface, a JSON REST API and a command line, on top of PostgreSQL. It manages the engineering data of a team – items, revisions, CAD files and their versions, bills of materials, change orders – with the check-out / check-in discipline of an engineering vault.

Work in progress: there is no official release yet. TeamCraft is under active development (version 0.x). Features, the REST API, the configuration and the database schema can still change. You are welcome to try it out and test it, and please report what you find on GitHub. It is provided “as is”, without warranty of any kind (MPL-2.0, sections 6 and 7). Don’t use it for production data yet, and keep backups.

The main pieces

Platforms

TeamCraft builds with cargo alone on Linux, macOS and Windows; the only service it needs is PostgreSQL. Step-by-step guides: Linux · macOS · Windows.

TeamCraft is free software under the Mozilla Public License 2.0. Contributions are welcome; see CONTRIBUTING.md. Report security problems privately, as described in SECURITY.md.

Getting started

Try it on your laptop

Download the desktop app with local server from the Releases page (Windows x64, macOS Apple silicon, Linux x86_64), start it and click Try TeamCraft on this computer: the app starts a private server with its own database on your computer and opens the browser, where you create the administrator. With PostgreSQL installed, teamcraft local does the same on the command line. Details: Try it on your computer.

Install on Linux with Docker

curl -fsSL https://raw.githubusercontent.com/rudalabs/TeamCraft/main/deploy/install.sh | bash

TeamCraft and PostgreSQL run as containers; the script offers to create the administrator at the end. See Install with Docker.

Build and run

You need Rust (stable, via rustup) and PostgreSQL 16 or newer. The repository’s docker-compose.yml starts a development database that needs no password:

git clone https://github.com/rudalabs/TeamCraft.git && cd TeamCraft
docker compose up -d db
cargo run --release

TeamCraft applies its database migrations on start and listens on http://localhost:8080. The platform guides cover native PostgreSQL installations and the desktop app: Linux · macOS · Windows.

First start

1. Open http://localhost:8080. A server without accounts that listens on localhost offers Create the administrator – pick a username and a password (10+ characters). The form disappears afterwards.
2. Projects → New project group: every item belongs to one. The creator manages the group and adds the team members.
3. Admin → Users (admins): create accounts for your team, or connect single sign-on (see Users, roles and SSO).
4. Items → New item: choose the CAD file (s) first – the model, its drawing and a STEP export for the 3D preview. Name and type are taken from the first file (an assembly for .iam, .asm, .sldasm, …). The item is created together with its files; its first revision A is in work and checked out to you.
5. Check in, then release it with a change order.

Appearance: TeamCraft follows the light or dark appearance of your operating system. The menu under your name (top right) and Account → Appearance switch between System, Light and Dark; choose Dark to keep the dark look of earlier versions. The distribution skins (Arch, CachyOS, EndeavourOS, KDE, Kubuntu, openSUSE, Ubuntu) are dark. The choice is personal and also styles the login page in that browser.

Preferred CAD program: if your parts exist in several CAD formats, Account → Preferred CAD program shows the files of your program (and all neutral formats such as STEP) first and collapses the native files of other programs – see Files. The setting is personal and applies in the browser and the desktop app.

Keyboard: / or Ctrl+K (⌘K) jumps to the search field. The single-key / can be switched off under Account → Appearance → Keyboard (per browser).

Keyboard: / jumps to the search field (on the vault explorer: to its filter); in menus, Esc closes and the arrow keys move.

On a server that is reachable from other machines, create the first administrator from the command line instead:

teamcraft user create --username admin --role admin      # prompts for the password

Command line

Try it on your computer

You can try TeamCraft on your own laptop without a server, Docker or a database administrator. Two ways lead to the same result: a private PostgreSQL database and the TeamCraft server, both running only on your computer, with all data in one folder of your user account.

This is for trying TeamCraft out. It is not a way to run TeamCraft for a team: nobody else can reach the server, there are no backups and no TLS. For a team, use the Docker install.

With the desktop app (no set-up)

1. Download the desktop app with local server from the Releases page:

   System	File
   Windows 10 / 11 (x64)	TeamCraft-with-local-server_<version>_x64-setup.exe
   macOS (Apple silicon)	TeamCraft-with-local-server_<version>_aarch64.dmg
   Linux (x86_64)	TeamCraft-with-local-server_<version>_amd64.AppImage

   The installers are not code-signed yet: on Windows, SmartScreen shows More info → Run anyway; on macOS, open the app the first time with right-click → Open; on Linux, make the AppImage executable (chmod +x).

2. Start TeamCraft and click Try TeamCraft on this computer. The first start creates the database and takes a few seconds, at most about a minute on a slow disk.

3. Your browser opens. Create the administrator – pick a username and a password (10+ characters) – and confirm the sign-in of the app. You are now signed in, in the browser and in the app.

4. Continue with Getting started: create a project group, then an item with a STEP file, and open it in 3D.

The app starts the local server again each time you open it while it is the configured server, and stops it when you quit the app. change next to the server name on the sign-in screen (or File → Sign Out) connects the same app to any other TeamCraft server; the local data stays where it is.

The installer with local server is the regular desktop app plus two things: the server program (teamcraft-server) and PostgreSQL’s programs (postgresql/, with its licence in COPYRIGHT.txt). It installs over the regular desktop app. The regular installers stay small and do not show the button.

On the command line

With PostgreSQL 16 or newer installed (its server programs initdb, pg_ctl and postgres, not only the client), the server archive from the Releases page does the same:

teamcraft local

Open http://127.0.0.1:8080 and create the administrator. Ctrl+C stops the server and PostgreSQL.

Without --pg-bin, TeamCraft looks for PostgreSQL’s programs in this order: postgresql/bin next to the teamcraft program (the desktop download with local server), PATH, /usr/lib/postgresql/<version>/bin (Debian, Ubuntu), Homebrew (postgresql@<version>), Postgres.app, and C:\Program Files\PostgreSQL\<version>\bin on Windows – the newest version first. PostgreSQL refuses to run as root (sudo): start teamcraft local as your normal user.

Where the data is

The desktop app and teamcraft local use the same folder, so both see the same data:

Inside it:

postgres/         the database cluster
postgres.log      PostgreSQL's log
pg_ctl.log        output of the last `pg_ctl start` (why PostgreSQL did not start)
db-password       the generated database password (readable by you only)
vault/            the stored files

The desktop app writes the server’s own log to local-server.log in its settings folder. To start over, quit the app (or stop teamcraft local) and delete the folder. Nothing in it is backed up: for data you want to keep, use the Docker install with its backups.

How it is protected

• PostgreSQL and the server listen only on 127.0.0.1; other computers cannot connect. PostgreSQL gets a free port at every start and no Unix socket.
• The database password is random (32 characters), stored in db-password (mode 0600 on Linux and macOS), and checked with scram-sha-256, so other accounts on the same computer cannot use the database.
• The page that creates the administrator is only offered while no account exists and the server listens on this computer – the same rule as for every other first start.
• A second teamcraft local on the same folder refuses to start instead of stopping the running database.

When something goes wrong

• The button is missing – this is the regular desktop app; download the one with local server.
• “The local server stopped” / “did not start” – the message shows the end of the server’s log. postgres.log in the data folder has PostgreSQL’s side. The app replaces a port that another program took with a free one; teamcraft local names the port in use – choose another with --port.
• macOS blocks the server or PostgreSQL – the app is not notarised yet. If right-click → Open on the app was not enough, remove the quarantine flag once: xattr -dr com.apple.quarantine /Applications/TeamCraft.app.
• “TeamCraft already runs on …” – another teamcraft local (or the app in another window) serves the same folder; use that one, or stop it first.

Concepts

Items and revisions

An item is a part, assembly, document, software component, simulation or as-built record (one physical unit or lot, see As-built records) with a unique number – generated from the numbering scheme of its project group (built in: PRT-000042, ASM-…, DOC-…, SW-…, SIM-…, AB-…) or typed in by hand. Its state of development is kept in revisions A, B, …, Y, AA, … (I, O, Q, S, X and Z are skipped, as in ASME Y14.35). A revision carries the attributes (name, description, material, mass, unit cost), the files and the bill of materials.

Next to the number on the revision page, Copy number puts the item number on the clipboard (the item list has a small copy button per row), and Label opens a printable label with a QR code. The code holds the short link <public URL>/i/<number>, which opens the item’s latest revision after sign-in – for parts, fixtures and prototypes on the shelf. The QR code is also available as SVG (/items/{id}/qr.svg) for label printers.

Lifecycle

 WIP ──submit──▶ In Review ──all reviewers approve──▶ Released ──▶ Obsolete
  ▲                 │
  └──reject/withdraw┘

Only WIP revisions change, and only while they are checked out. Released data never changes – further work happens in a new revision (Revise).

Project groups and roles

| Role | May | | Viewer | read internal project groups and the restricted groups they belong to, raise and discuss change requests | | Viewer | read everything, raise and discuss change requests | | CAD editor | create and change items of the project groups they belong to, create project groups, review changes, triage and decide change requests on their groups | | Admin | everything, plus users, all project groups and lock overrides |

Every item belongs to a project group – a product or product line, a machine, a customer project, a building, a vehicle or a rover. CAD editors start their own groups and become their managers: managers edit the group and add or remove members. A group can also be bound to a group of the identity provider (administrators only); its members are then synchronised at every single sign-on.

A group is internal (everybody reads it) or restricted: then only its members – viewers included – and administrators see the group, its items, files and the changes about them; for everybody else it does not exist. Links from other groups show a Restricted item placeholder. Managers switch this on the group’s page; see Read permissions and restricted groups.

Item numbers

Each project group has a numbering scheme for the numbers TeamCraft generates when the number field is left empty – in the web UI, the REST API, the BOM import and Save as. Managers set it on the group’s page, where Preview shows the next number per item type before anything is saved.

Everything else is literal text from A–Z 0–9 . _ -. The built-in scheme is {TYPE}-{SEQ:6}; {PROJECT}-{TYPE}-{YYYY}-{SEQ:4} gives ROVER-PRT-2026-0007. Every distinct expansion counts on its own: a scheme with {YYYY} starts at 1 each year, one without {TYPE} shares the sequence between all item types, and groups with the built-in scheme share its counters. Changing the padding width keeps counting. When the next number is already taken (typed in by hand or imported), the counter continues after the highest existing number of the same pattern – so a new scheme can take over an existing numbering convention – and existing items never change their numbers.

Attributes and classification

Besides name, description, material, mass and unit cost, a revision can carry custom attributes that administrators define under Admin → Attributes: a label, a key for the API (vendor, length_mm), a type – text, number, yes/no or a choice list – an optional unit, the item types it applies to and its position in the forms. Values are edited with the other attributes while the revision is in work, frozen on release and copied by Revise and Save as. Key and type are fixed once created; deactivating an attribute stops offering it, stored values stay visible.

Every item also has a classification in its master data: in-house (the default), purchased or standard part – it can change at any time, like the project group.

The item list filters by classification and by one attribute: text and choices match a part of the value, yes/no attributes yes or no, numbers 12, >=10, <=20 or 10..20; an empty value finds every item that has the attribute. The search box also finds attribute values.

The BOM import fills both for the items it creates: a BOM structure or procurement column sets the classification (Normal, Phantom → in-house; Purchased, Kaufteil → purchased; Content Center, Normteil → standard part), and a column whose header is the label or key of an active attribute (Vendor, length_mm) fills that attribute. A value that does not fit – text in a number column, a choice that does not exist, an attribute that does not apply to the item type – is left out with a warning. The preview lists which columns become attributes and which are not imported; existing items are not changed.

Audit log

Every modification is recorded with user, time and details – shown on every revision page and, for admins, under Audit log.

Vault, check-out and check-in

TeamCraft works like an engineering vault: files are never edited in place. You check out a revision (take the exclusive lock), change attributes, files and the BOM, and check in – the new file versions are stored and the lock is released in one transaction. If anything fails, nothing changes.

The vault explorer

Vault in the top bar opens a three-pane explorer:

Every action returns to the explorer, so a typical session is: pick the folder, select the item, Check out, download the files, work in your CAD program, drop the changed files into Check in, done.

Browser downloads are for single files and for viewing. A browser saves files one by one into Downloads – without the folder structure an assembly needs, without knowing which version a file is and without read-only protection. For CAD work (assemblies, drawings, anything you will change and check in) use the desktop working folder: one folder per project group with the original folder structure, Get for whole assemblies, read-only files until you check out – see How files appear on your computer.

Adding files to an existing item

The Files card of a revision always says how to add files:

• Free revision in work: To add or replace files, check out this revision with a Check out and add files button – it checks out and returns to the card with the upload form.
• Checked out by you: the upload form; files can also be dropped onto the card (large files use the resumable chunked upload).
• Checked out by someone else: who and since when; files can be added after check-in (administrators can force-unlock).
• In review, released or obsolete: frozen. Revise (for editors) creates the next revision, which takes the files.
• Viewers and users outside the project group see no way in.

Simulations and parts show what typically belongs there (solver input, results, reports; CAD model, drawing, STEP). The desktop app has Add files… (see How files appear on your computer).

Rules

• Only revisions in work can be checked out, and only by CAD editors of the item’s project group.
• A new item and a new revision (Revise) are checked out to their author.
• Check in with files: files with the same name become the next version (Creo’s iteration suffixes bracket.prt.7 are folded into versions); identical content is recognised and not stored again.
• Every file has a folder inside its project group (chassis/brackets; empty = the top of the group). It is the file’s place in the desktop working folder, so assemblies find their parts. The folder import sets it from the scanned tree, uploads and check-ins may send it (folder, folders in the API), new versions keep it, and while the revision is checked out the Folder column of the revision page moves a file. Folders are relative: .., drive letters and names that are invalid on Windows are refused.
• Cancel check-out releases your lock at once – no dialog, nothing is uploaded. Force unlock (admins) releases someone else’s lock after a confirmation, is recorded in the audit log and notifies the owner (notification kind unlock).
• The revision page and the dashboard show how long a lock has been held (🔒 Max for 3 days), so forgotten check-outs stand out.
• Check in all (dashboard, Checked out by me) checks in every revision you hold without new files – the locks are released, the revisions keep their current files. Each revision is checked in on its own (own transaction, own audit record), so one failure does not block the others; the message lists what failed and why. Upload changed files with the revision’s own Check in first.

Concurrency: nothing is overwritten silently

The lock keeps two people from changing a revision at the same time. When a lock was broken (Force unlock) and someone else checked in meanwhile, the original owner’s files are out of date – checking them in would throw away the newer version. TeamCraft therefore checks every upload against the version it was based on (optimistic concurrency, as Vault and Teamcenter clients do):

• The forms of the revision page send the versions the page showed; the desktop app sends the SHA-256 of the version each file was copied from; API clients send bases (see the REST API).
• If a file moved on since, the check-in or upload is refused with 409 and a message such as hub.step changed on the server since you got it: your change is based on v1, the server has v2 by Erika (…). Nothing was stored – the whole check-in is rolled back, the lock stays yours. Get the current version, merge your changes and check in again.
• Identical content is never a conflict, and uploads without a base keep the plain last-writer-wins behaviour.

Per file, a workspace is in one of these states (desktop Workspace tab, …/file-status in the API):

• Uploads show a progress bar; Cancel upload stops the transfer immediately and nothing changes on the server.

Large files: chunked, resumable uploads

CAD assemblies and simulation results reach several gigabytes. Sending them in one request means starting over after every network hiccup, so API clients – and the desktop app and the web UI for files above 32 MiB – upload them in chunks:

1. POST /api/v1/uploads announces the file (revision, name, size, optionally its SHA-256, the base version and its folder in the project group – the desktop app sends the folder of the working folder, so the file keeps its place there). The server refuses at once what it would refuse later: a file larger than TEAMCRAFT_MAX_UPLOAD_MB, a revision you have not checked out, or a base the server file has moved on from.
2. PATCH /api/v1/uploads/{id} appends one chunk (at most TEAMCRAFT_UPLOAD_CHUNK_MB) at the offset the server confirmed last. A chunk at any other offset is refused with 409 and the server’s offset, so after a broken connection the client asks (HEAD/GET) and resumes there – bytes of an interrupted chunk that were never confirmed are cut off. Each chunk is on disk before its offset is confirmed.
3. POST /api/v1/uploads/{id}/finish – or the upload id in the uploads field of a multipart check-in – hashes the received file, checks size and SHA-256 (a mismatch resets the upload to offset 0), moves it into the content-addressed vault and stores the version through the same code as every other upload: check-out required, base-version guard, audit log, notifications, one transaction with the other files of the check-in.

The chunks are collected in uploads/ below the vault directory (the same file system as objects/, so the finished file is moved, not copied); only one chunk per request is held in memory, which is why TEAMCRAFT_MAX_UPLOAD_MB can be raised for large files without more memory. Uploads are private to the user who started them. An unfinished upload expires 24 hours after its last chunk; the server removes expired uploads and their data at start-up and every hour. Each user may have at most 16 unfinished uploads at a time, so the space they reserve stays bounded (16 × TEAMCRAFT_MAX_UPLOAD_MB per user). DELETE /api/v1/uploads/{id} cancels one at once.

In the browser the upload and check-in forms of the revision page and the vault explorer, and the New item form (its uploads have no revision yet and can only join the creation of an item), do the same on their own: files above 32 MiB go first in chunks (to /uploads, the same sessions, signed in with the browser session), the progress bar counts all files, and the form then stores them together with the small files and the comment in one step. A dropped chunk is sent again after a short wait (up to six times); if the connection stays away, or the page was closed or reloaded, choose the same files again and submit – the upload continues where the server stopped, the browser remembers the unfinished uploads per revision and file. Cancel upload removes them on the server. The New item form still sends its files in one request, within TEAMCRAFT_MAX_UPLOAD_MB; attach large files to the new revision afterwards.

Favorites, saved searches, Save As

• The star next to the title of a revision page keeps the item in Vault → Favorites (like Teamcenter’s Favorites). Favorites are personal.
• Saved searches: filter the item list, then Save this search – the named search appears above the list for one-click reuse (like Teamcenter’s Saved Queries).
• More → Save as… on a revision page creates a new item from it: the attributes and, optionally, the current files and the BOM. The new item starts with revision A, checked out to you; the source does not change.

Desktop working folder

The desktop app keeps a local working folder: one folder per project group that mirrors the folder structure of the files, one copy of each file (TeamCraft/ROVER/chassis/brackets/bracket.prt); the revision is metadata, not a folder level.

• Get copies an item with its BOM (revision rule latest or released) and the parts its CAD files reference; only missing and outdated files are downloaded, checked by SHA-256, with progress and cancel.
• Add files… (Files section, More ▾) copies picked files into the working folder of a revision (checking it out first) and lists them as new files in Check in….
• Files you have not checked out are read-only; Check out makes them writable, Check in uploads the changed ones and makes them read-only again.
• The workspace tab shows which files you changed, which are outdated or in conflict, name clashes (two items with the same folder and file name – never overwritten) and who holds the lock; Check in uploads exactly the changed files – based on the versions they were copied from. Opening an outdated file or one somebody else has checked out asks first.
• Check in all in the worklist checks in every check-out without local changes and lists the ones that still have changes.

See How files appear on your computer.

Files, versions and 3D preview

Versions and rollback

Every upload of a file name is a new version with an optional comment. The revision page lists the version history of every file; any version can be downloaded (name.v2.ext), previewed, or restored – a rollback that stores the old content as a new version, so history is never rewritten.

Large result files. A file can be set to keep only the latest version (⋯ → Keep only the latest version, while you hold the check-out): older versions are then removed after a grace period (default 7 days) as long as the revision is in work – released revisions keep all of their versions. See Data retention.

The vault is content-addressed (SHA-256): identical files are stored once, and teamcraft vault check --verify-hashes proves that nothing was altered.

File formats

TeamCraft stores files of any type and recognises the native and exchange formats of the common CAD, BIM, 3D and electronics programs – see Supported file formats. Recognised files are labelled with program and kind, get their registered content type, are searchable by program (Items → CAD program) and, where readable, scanned for the files they reference.

Preferred CAD program

When a part is kept in several CAD programs – an NX model next to a SOLIDWORKS and an Inventor copy, say – choose your program under Account → Preferred CAD program. On the revision page, in the detail pane of the vault explorer and in the Files tab of the desktop app, the native files of the other programs then move into a collapsed group below the list, e.g. 2 files in other CAD formats (SolidWorks, Inventor); one click opens it.

• A family is everything one program writes natively: for NX its parts, assemblies, drawings and simulation files (.prt, .sim, .fem, .afm); for Creo also its neutral and Creo View files; for CATIA also CGR and 3D XML. The families: SolidWorks, NX, Solid Edge, Inventor, Fusion, AutoCAD (DWG), Creo, CATIA, SpaceClaim, FreeCAD, SolidCraft, Rhino, Alias, OpenSCAD, Revit, Navisworks, MicroStation, Archicad, SketchUp, Blender, Maya, 3ds Max, Cinema 4D, Modo, Houdini, KiCad, Altium and Eagle.
• Neutral and exchange formats are never collapsed: STEP, IGES, Parasolid, JT and PLM XML, DXF, meshes (STL, 3MF, 3DS, …), visualisation formats, point clouds, IFC, Gerber, simulation decks and results, documents and images.
• Only a revision that has at least one file of your program is grouped; any other revision lists its files as before.
• It is display only and personal: nothing is hidden from the search, downloads, Pack and Go, the REST API or other users. The default, All CAD programs alike, keeps the plain list. The REST API returns the setting as preferred_cad on GET /api/v1/me and each file’s family as format_info.family.

3D preview

Meshes, point clouds and STEP models open in a WebGL viewer in the browser and in the desktop app. Drag to rotate, wheel or pinch to zoom, arrow keys to turn, double-click to reset; Z up / Y up switches the convention. Below the model, Section X / Y / Z cuts it open along a plane: the slider moves the plane through the model (its position is shown in model units), flip keeps the other side – for a look inside housings and assemblies. Measure picks two points on the model (click, don’t drag) and shows their distance and its X, Y and Z parts in model units; the decimal places (0–6) are remembered in the browser and apply to the section position too. Measured points are on the visible surface, so a section shows inner distances such as wall thickness. Compare with … (on the preview page, when there is something to compare) lays another version of the file – or the file of the same name in another revision of the item – over the model as a translucent red ghost: red shows where the other model sticks out, so added and removed material is visible at a glance; sections and measuring work on both.

Add note pins a note to a point of the model for a design review: click the point, write the note. Notes belong to the shown version of the file, appear as blue points with a list below the model, and everyone who may read the file sees them and adds their own – also viewers. A note is removed by its author or an administrator; adding and removing are recorded in the revision’s history (annotation.add / annotation.remove). The REST API has the same notes under /api/v1/file-versions/{id}/annotations.

The server converts a file once, in a separate process with a time limit, and caches the result next to the vault; uploads start the conversion in the background so the first viewer does not wait. Everything is pure Rust: STEP is read and tessellated with the truck B-rep kernel (or from the tessellated geometry of AP242 files), the mesh readers are part of TeamCraft. Export STL (in the toolbar on the view) saves the shown triangles, e.g. for 3D printing. The same conversion computes the shape signature of the similar part search.

While the model loads, the canvas says so, and when there is nothing to show the reason appears on the canvas (and in the line below it) – in the web UI and in the desktop app alike: the server’s conversion error (for example a damaged or unsupported file), an empty, cut-off or invalid model, a graphics driver without WebGL 2 or one that could not compile the shaders, a model too large for the graphics memory, or a 3D view the graphics driver stopped (WebGL context lost). A preview never ends as a silently empty canvas.

When a STEP preview shows only part of the model, the line below the viewer says partial preview: N of M faces – the missing faces use geometry the kernel cannot tessellate. Details: STEP in the 3D preview.

Simulation results show the outer surface of the mesh with a colour scale (viridis), the range of the field above the canvas and, when the file has several fields, a selector – see Simulations.

Previews of native CAD files

Native CAD files (Inventor, Solid Edge, SolidWorks, NX, Creo, CATIA, …) are proprietary; TeamCraft does not read their exact geometry (see Research: previews of native CAD files). The exceptions are NX, SOLIDWORKS, Inventor, CATIA V5 and Creo. The first four save a tessellation of every part into the file: NX in a documented format (JT 9), SOLIDWORKS (2015 and later) as the display lists it draws the part with, Inventor as the triangle lists of its graphics segment, and CATIA as the visualisation data it draws on screen (see Research: 3D preview of CATIA V5 parts). Creo stores no tessellation, but its exact faces with every edge already sampled; TeamCraft triangulates those faces itself – planes, cylinders, cones, tori, spline, fillet and ruled faces (see Research: 3D preview of Creo parts), and puts Creo assemblies together from their parts (see Research: 3D preview of Creo assemblies).

TeamCraft shows that tessellation in the 3D viewer, refined along the exact surface normals stored with it, so round faces stay round.

An assembly of NX, SOLIDWORKS or Inventor and a CATIA product are put together from their part files. Check the parts in, under their file names, either in the assembly’s revision or as items of their own. The assembly then shows every component in its place, sub-assemblies included (see Research: 3D preview of NX parts, 3D preview of SOLIDWORKS files, 3D preview of Inventor files).

A CATIA product stores no file names, only an id of each component’s document. TeamCraft finds the component among the CATIA files of the product’s revision by that id, whatever the file is called now; a renamed or copied part is still found. Otherwise it looks for <part number>.CATPart (or .CATProduct) by name, as above (see Research: 3D preview of CATIA V5 products). Keep parts whose part number differs from their file name in the product’s revision.

These components are left out:

• components that are not in TeamCraft;
• NX components on layers the assembly hides;
• SOLIDWORKS components that are suppressed or hidden;
• Inventor components that are hidden or suppressed in the assembly.

CATIA products show hidden components, too: TeamCraft does not recognise them yet.

Rhino models (.3dm, Rhino 1 to 8) are shown from the meshes Rhino saves with them: mesh objects, the render meshes of polysurfaces and extrusions, block instances in their places; SubD objects are refined from their control net. Hidden objects and hidden layers are left out. A model saved without render meshes (Save Small, or very old files) has no 3D preview and shows the picture Rhino stored instead (see Research: 3D preview of Rhino models). Fusion designs (.f3d) carry the triangles Fusion draws on screen; TeamCraft shows them, refined the same way (see Research: 3D preview of Fusion designs).

SketchUp models (.skp, SketchUp 3 to the current version) open in the 3D viewer as well: SketchUp stores plain polygons, so TeamCraft triangulates the faces (holes included) and places every component and group, nested ones too, in millimetres. Hidden faces, hidden components and everything on a hidden tag (layer) are left out; colours and textures are not shown. A file with only edges and no faces keeps its stored picture (see Research: 3D preview of SketchUp models).

For the rest TeamCraft shows what other PLM systems show:

• JT files (.jt, version 10) carry parts and assembly in one file: the 3D preview shows every instance in its place, and the file’s picture is rendered from it (see Research: 3D preview of stand-alone JT files).
• A picture of the 3D preview for NX, SOLIDWORKS and Inventor parts and assemblies, CATIA parts and products, Creo parts and assemblies, Rhino and SketchUp models and Fusion designs. It replaces the image stored in the file and is a 512 × 512 PNG with a transparent background, drawn once and cached. An assembly’s picture is drawn again when one of its parts changes. Drawings, and assemblies none of whose parts are in TeamCraft, keep the stored image.
• The preview image stored in the file. Inventor drawings and presentations (.idw, .ipn), Solid Edge (.par, .psm, .asm, .pwd, .dft), NX assemblies and drawings (.prt, a JPEG) and SolidWorks files (up to 2014 in their OLE container, from 2015 on in a compressed section that TeamCraft inflates) carry a picture the CAD program wrote when saving. It appears next to the file on the revision page and in the desktop app (GET /api/v1/files/{id}/thumbnail). Only the image is read; files saved without one simply show none.
• 3D from a STEP export. Attach a STEP export next to the native file. The desktop app on Windows creates it with your own Inventor or Solid Edge – the STEP button in the workspace or the option at check-in, like the Inventor add-in of Autodesk Vault or the Solid Edge integration of Teamcenter. It uses your licence (student licences included, within their terms); TeamCraft contains no Autodesk or Siemens software.

Full-text search

The item search ranks matches in numbers, names, materials, descriptions and file names, and in the text inside STEP and IGES files (product names, authors, organisations), plain-text files (with their decimal numbers), the text layer of PDF reports and the text of HTML reports (table rows as lines; scripts, styles and hidden elements skipped). PDFs and HTML files are read in an isolated child process with size, time and memory limits; scanned PDFs have no text layer (there is no OCR).

BOM, references and change propagation

Bill of materials

A revision’s BOM lists child items with find numbers, quantities and notes. The BOM page expands the structure over all levels with mass and cost roll-up and three revision rules:

The roll-up adds the entered masses. The centre of gravity and the inertia tensor of the structure, computed from the 3D files of the parts, are on the Mass properties page – see Mass properties.

Working with a large structure

For a big product (hundreds or thousands of lines across several project groups) the BOM page offers:

• Fold and unfold – every line that has lines below it has a ▾ / ▸ button (keyboard operable, aria-expanded); Collapse all and Expand all sit above the table. This needs JavaScript; without it every line stays visible.
• Levels – Levels: 1, 2, 3, 4, 5, All (?depth=n) lists only the first n levels, also without JavaScript, and the link can be shared. A line at the last level shown has a +n marker with the number of lines hidden below it. Mass and cost always cover the whole structure, not just the levels shown. It combines with the revision rule (?rule=).
• Group column – the project group of each line, linked to the group page. A line you may not see (a restricted group) stays a placeholder and shows no group.
• Group filter – Group (?group=CODE, only groups that occur in the structure are offered) keeps the lines of that group (highlighted) and the path from the top to them, so they stay in context; other lines below a match are left out unless they lead to a match too. With a level limit as well, the filter applies first. An unknown or hidden code gives “not found”.

The CSV and Excel exports and Pack and Go ignore levels and group: they always contain every line. The desktop app’s structure tab does not have these controls yet.

Where-used shows the parents of an item; All levels on the revision page opens the where-used page, which walks up through the sub-assemblies (1, 2, 3, 5 or all levels). Cycles are rejected. The BOM exports as CSV and as Excel workbook (which the BOM import reads back), and Pack and Go downloads a revision with the files of its whole structure as ZIP (<item>_<revision>/, bom.csv, manifest.json with SHA-256 per file). For every released revision the manifest also names the change order that released it and who approved it when (released_by: change, title, release time, approvals); a change order the downloader may not see is only marked restricted.

Creating a BOM from the CAD references

An assembly uploaded as a file has no BOM, although the server already knows which part files it uses (the References tab). Create BOM from CAD references… on the BOM card of the revision (also offered as a hint while the BOM is empty) shows what the BOM would be, one row per child:

• item, name, quantity and where it comes from – CAD instances (NX: the placed instances of the component, hidden layers left out; SOLIDWORKS: the instances in the component tree without exclude from BOM; STEP assemblies with external part files: the assembly occurrences of each file) or assumed 1 (the file does not tell; the line gets the note quantity not known from the CAD file – check it);
• the CAD file that references it;
• a status: new line (ticked), already in the BOM, differs (BOM 2, CAD 4 – changed only when you tick it and Also change the quantity), or circular (refused, as when adding a line by hand).

Only assembly files count (NX files only when they have component instances, STEP files only when their occurrences lead to external part files); a drawing’s link to its model stays a drawing of reference. Referenced files TeamCraft does not have are listed as not in TeamCraft and never created; parts in project groups you cannot see are only counted. Add the ticked lines needs the revision checked out by you (the page offers Check out and create) and adds all lines in one transaction. The REST API has the same two steps: GET …/bom/from-references returns the plan, POST …/bom/from-references with {"children": ["PRT-000004"], "update_quantities": false} applies it.

Comparing BOMs

Compare… on the BOM page lists the lines that were added, removed or changed (quantity, find number, notes) between two revisions – by default the previous revision of the same item; any other revision can be chosen, and the API also compares by code (GET …/revisions/B/bom/compare?with=A).

Levels: All levels compares the whole structure: every child is resolved with the chosen revision rule, the children of two matched lines are compared the same way, and an added or removed sub-assembly brings its whole sub-tree. A child that now resolves to another revision counts as changed. When one of the two revisions is released, the default rule is As released: a released parent uses the child revisions it was released with, an in-work one the newest released children, so comparing two revisions shows exactly which parts went into the new one; otherwise the default is Latest. Latest and Latest released resolve a child by its item alone – both sides then get the same child revision and sub-tree, and only the direct lines can differ. In the API: depth=all and rule=latest|released|as_released (same default). The Excel download contains the level and the revisions too.

Alternates, supersession and replacing a part

The card Alternates and replacement on the revision page holds two relations of the item itself (not of one revision – they stay true for old assemblies too). Changing them needs edit rights in the item’s project group.

• Alternates are items that may be built in instead of this one in every assembly – same form, fit and function, e.g. a second source of a purchased part. Two-way (the default) also makes this item an alternate of the other one; that needs edit rights in the other item’s group too, otherwise add it one-way. The other item then lists it under may be replaced by.
• Supersession says: do not use this item for new designs any more, use its successor. An item has at most one successor, and a chain of successors never leads back to the item. The revision page of a superseded item shows a notice, BOM lines that use a superseded item are marked Superseded by …, and adding one to a BOM still works but says so. Superseding changes no BOM and no lifecycle state; making the old revisions obsolete stays a change order’s job.

Replace in assemblies on the where-used page puts another item (by default the successor, otherwise an alternate) in place of this one. The preview lists every assembly whose latest revision uses the item directly and what will happen to it:

A revision that was not checked out is changed directly, like check out, edit, check in; one checked out by you stays checked out. Older revisions keep their BOM. Every replaced line is recorded in the history of the assembly (bom.replace). Assemblies in groups you cannot see are only counted.

References

Besides the BOM, revisions reference other items: drawing of, specification for, references. CAD files are scanned for the files they reference (assemblies, drawings, STEP, KiCad; ASCII and UTF-16 paths as written by SolidWorks, Inventor, Solid Edge, CATIA, …; NX parts and SOLIDWORKS 2015+ files through their containers, see Formats) and matched against the vault: referenced files that are not in TeamCraft are flagged and the missing BOM lines are suggested. The other direction warns before damage: removing a file that CAD files of other items still reference names them (up to three, then a count) in the confirmation, so a part still used in an assembly or drawing is not deleted by accident. Deleting an item is refused while it is used in a BOM.

Change propagation

When a change releases a new revision (or a revision becomes obsolete), every dependent – via BOM, references, CAD file references or as the basis of a simulation – is flagged Check needed. A CAD editor acknowledges it with a note (form, fit and function unchanged) or revises and releases the dependent, which resolves the check and propagates one level further. Every change shows this impact analysis before it is approved.

Dependents to check on the dashboard (and in the desktop app) groups the open checks by the dependent revision: one header per assembly, drawing or simulation (ASM-000002/A Electronics enclosure – 4 changes to check) with Open, Revise and Acknowledge all…, and one compact row per source below it – the item that changed, released or obsolete via which change, and the link (BOM line, CAD file reference, drawing, specification, reference, simulation basis) – each with its own Acknowledge…. Acknowledge all… resolves exactly the checks shown with one note, in one step; checks resolved by someone else in the meantime are skipped, and every acknowledged check is recorded in the item’s history. The revision page shows its open checks the same way.

Finding similar parts

Before you model a new part, check whether one like it already exists. TeamCraft compares the shape of 3D models – no AI, no training data, the same answer every time – and lists parts of similar shape and size with a reason you can check.

Where you see it

• Revision page → Similar parts (below Files): up to six parts with a score, the matching file and a one-line explanation, e.g. extents 118 × 40 × 8 vs 120 × 40 × 8, shape distribution 94 % similar. On a brand-new part (only revision A, in work) the section is called Similar existing parts: if one fits, reuse it instead of creating a new item. It is a card on the page, not a pop-up: it appears whenever the revision has a file it can compare, and stays hidden otherwise. Right after Items → New item with a STEP or mesh file the card first says Comparing the shape … reload the page in a moment – the page does not refresh itself, reload it once the comparison is done.
• Desktop app: the revision overview has a Compare the shape in the browser button that opens this card in the web UI; the app itself shows no list.
• REST API: GET /api/v1/items/{number}/revisions/{code}/similar (REST API).
• AI assistants: the MCP tool find_similar_parts (MCP server); find_duplicate_files is its sibling for byte-identical copies.

The comparison needs a 3D model with a preview: STEP, a mesh (STL, OBJ, PLY, OFF, 3MF, AMF, glTF/GLB, 3DS), an NX part (.prt with its JT lightweight representation), a CATIA V5 part (.CATPart with its visualisation data) or a Fusion design (.f3d with its display scene). Other native CAD files are compared through their STEP export – attach one. NX assemblies are not compared (they hold no shape of their own), and neither are point clouds. Simulation result files (VTK, VTU, VTP, CalculiX FRD) have a 3D preview too and are currently compared like parts.

How it works

When a 3D file is attached or checked in (or first shown), the preview process computes a small shape signature of its mesh, once per file content:

Two parts are compared with

• shape = 1 − ½ · Σ |difference of the D2 histograms| (100 % = same form),
• size = exp(−2 · mean |ln(extent ratio)|) over the three extents (100 % = same size; 5 % larger in every direction gives about 90 %, twice the size about 25 %),
• score = shape × size.

Hits below 50 % are not shown; each item appears once (its best file), and only its latest revision counts. Units are the file’s model units (usually millimetres); a part exported in inches is therefore “smaller”.

Ignore scale (ignore_scale=true in the API and the MCP tool) compares the proportions (middle and smallest extent relative to the largest) instead of the extents, so scaled variants – M6 and M8 versions of a part – score like copies.

Everyone who can sign in sees the hits, exactly like the item search: items of a restricted project group appear only for its members and administrators – for everybody else they are neither shown nor counted, even with identical file content.

Limits

The signature looks at the outer form. Parts that differ only in small features (a hole more, a different chamfer) score high – that is the point of the search, but it is no proof that they are interchangeable. Mirror images score as the same shape. Very different tessellations of the same part (a coarse STL vs a fine STEP) agree on extents and differ a little in the shape distribution.

A STEP file with a partial preview (some faces use geometry the kernel cannot tessellate, see Files) gets no signature: area, volume and shape distribution of a model with holes would compare it wrongly. It is neither searched from nor found as a hit; the similar-parts panel says why.

The search is fast for large vaults: an indexed prefilter on the extents (within a factor of three) or proportions keeps at most 2000 files, which are scored in memory.

Files stored before this feature get their signature in the background when their revision page or 3D view is first opened (the page then says reload in a moment), or all at once with teamcraft vault signatures (see Operations; --convert also converts files that were never previewed).

Mass properties (mass, CG, inertia)

TeamCraft computes the mass, the centre of gravity (CG) and the inertia tensor of an assembly – a vehicle, a rocket, a robot – from the 3D files of its parts, the densities of their materials and the masses you measured. Nobody has to load the whole assembly in the CAD system to get the numbers: open the assembly revision and choose Mass properties (on the revision page next to the BOM, or on the BOM page).

The method and its limits are described in the research note Mass properties from exported meshes.

The workflow

1. Export every part in the assembly frame. In the CAD system, export each part as STL (or 3MF, OBJ, STEP …) in the coordinate system of the whole assembly or vehicle, not in the part’s own frame. TeamCraft then only adds the parts up – no placements, no CAD assembly file needed. A part used several times (four fins) is exported once with all its instances in one file; set Units shown in the file to 4.
2. Attach the files to the part revisions as usual. Attach the files of one part to a part revision, in as many formats as you like. The geometry file is then picked automatically (STL, 3MF, OBJ, PLY, OFF, AMF, glTF, 3DS, then STEP, then the lightweight data in NX, SOLIDWORKS, JT and Rhino files; the native format of your preferred CAD program first among the native ones) and the page says so: Geometry: box.stl (chosen automatically; 2 other formats of the same model). Files belong to one model when their names agree apart from case, _, -, spaces, the extension and a trailing rev-X (box.prt, Box_rev-B.SLDPRT, box.stp). If the revision holds files of several different parts, TeamCraft does not guess – see Geometry ambiguous.
3. Name the material. The material attribute of the revision (e.g. Aluminium 7075-T6) is looked up in the material library, ignoring case. The Material field of New item and Edit revision (and of the desktop app) suggests the library while you type, with the density next to each name; picking a suggestion enters exactly the library name. Free text stays allowed – for a bought part with a measured mass, say – but a name that is not in the library shows a hint, and the mass properties report a missing density. A density override in the mass settings wins over the library – for 3D-printed parts with partial infill, for example.
4. Enter measured values for bought parts and weighed sub-assemblies: mass, optionally the CG and the inertia tensor about that CG.
5. Check the result on the mass properties page and export it as CSV or JSON for the flight simulation, the structural analysis or the balancing.

Where each number comes from

For every revision the first source that applies is used:

Lines below a measured assembly are shown as covered by measured parent. An assembly’s own 3D file and entered mass are not added to the sum of its lines (they would count the parts twice); enter a measured mass to replace the sum.

A BOM line with quantity n adds n units. In the common frame these units sit at the same place unless the file shows them all: a line whose quantity differs from the units shown in the file is flagged copies stacked at the same place – the mass is right, the CG and the inertia usually are not.

Geometry ambiguous

A plausible but wrong number is worse than none, so a revision whose 3D files belong to several different parts (typically an assembly attached as one item: the parts, the assembly and the neutral JT or STEP file) does not get the mass of whichever file sorts first. Its source is geometry ambiguous, it adds nothing to mass, CG and inertia, and the totals are flagged incomplete: N files of M different parts – choose the geometry file in Mass settings, or split the parts into BOM lines. The same applies to a part revision inside an assembly. An entered mass still counts (without position).

• TeamCraft suggests the likely whole assembly: the file that references other files of the revision and is referenced by none of them, else the file named like the item (number or name). The Mass settings card offers a one-click Use NIST mtc crada assembly.jt (the revision must be checked out); the choice is stored like a manual one. It is a suggestion only – nothing is used without the click.
• A JT 10 file of the assembly is often the best choice: it is the one file with every part placed in the assembly frame (the NX assembly .prt has no geometry of its own). For the NIST box assembly its volume matches the sum of the 36 placed part files to within 1 %.
• The file selector lists the candidates grouped by model, the likely assembly first, and marks the file in use as automatic or chosen; Automatic restores the automatic pick.
• The better fix is usually to model the assembly as an assembly: one item per part with the part’s files, and BOM lines with quantities (see The workflow).
• REST, the JSON export and the MCP tool carry geometry per line and root_geometry: choice (automatic, chosen, ambiguous), the file, the number of other formats, the candidates by model and the likely file. The CSV has the columns geometry_file and geometry_choice.

Warnings

• open mesh – edges with one triangle only (holes): the volume is not well defined. Fix the export (closed solids only).
• inconsistent orientation – some triangles face inwards.
• non-manifold edges – bodies touching along an edge or duplicated faces; usually still correct.
• inside out – every triangle faced inwards; TeamCraft flipped the mesh.
• no density – no material, or the material is not in the library.
• no position – a mass without CG (entered mass, measured without CG): counted in the total mass, left out of the CG and inertia.
• restricted lines – items of project groups you are not a member of are left out, like in the BOM roll-up.
• The entered mass attribute differs by more than 5 % from the computed mass.

Units and conventions

• The length unit is set per file: millimetres by default (glTF: metres), metres or inches. Results are always SI: kg, m, kg·m².
• The CG and the tensors are in the frame of the geometry files.
• The inertia tensor is given about the CG and about a reference point you enter (x,y,z in metres, e.g. the nose tip), in tensor form: the off-diagonal entries are the negative products of inertia, Ixy = −∫ xy dm. The principal moments are listed as well.
• Accuracy: a mesh approximates curved surfaces from inside. With an export chord tolerance of 0.01–0.05 mm the error is far below that of handbook densities; an icosphere of 1 280 triangles is 0.9 % light, one of 20 480 triangles 0.05 %.

Mass settings

The Mass settings card on the page holds, per revision: the geometry file with its length unit and number of units shown, the density override, and the measured mass, CG, inertia tensor and a note (scale, data sheet, date). Changing them needs the revision checked out, like every other attribute; Revise carries them over to the next revision.

Material library

Admin → Materials (/materials) lists the densities. Every signed-in user can read it; administrators add, rename and remove materials. Names are unique ignoring case. Removing a material does not change any revision; their masses then report a missing density.

Exports and interfaces

• CSV and JSON from the Export menu of the page (the totals, both tensors and every line with its source and warnings). Like the BOM downloads they follow the project group’s download switch.
• REST: GET /api/v1/items/{number}/revisions/{code}/mass-properties?rule=&ref=x,y,z and GET /api/v1/materials (REST API).
• MCP: the read-only tool get_mass_properties (MCP server).

Limits

• Placements (transforms per BOM line) are not stored: parts exported in their own frame cannot be combined yet.
• Overlapping bodies in one file are counted twice.
• Point clouds and simulation results have no volume.
• Measured values can only be changed in an in-work revision.

Change requests, change orders, reviews and notifications

Change requests (ECR) → change orders (ECO)

A change request (ECR, ECR-000001) is the step before a change order: somebody found a problem or has an idea – on the shop floor, in a simulation, in a test, in purchasing – and asks for a change. Every signed-in user may raise one, viewers included, and everybody may comment on it. A change order (ECO, CHG-000001) is the engineering work that answers it: it carries the new revisions through review to the release.

 anybody signed in                     CAD editors of the affected project groups / admins
 ─────────────────                     ──────────────────────────────────────────────────
 Request change… ──▶ New ──▶ In Triage ──▶ Accepted ──▶ change order (ECO): create one with the
  (revision page,     │          │                       in-work revisions, or link an open one
   file row, desktop) │          │     ──▶ Deferred ──▶ In Triage (taken up again)     │
                      │          │     ──▶ Rejected                                    │ released
                      └──────────┴──▶ Withdrawn (by the requester, before the decision) ▼
                                                                                Implemented

1. Raise – Request change… on a revision page, on a file row, in the Requests list, or in the desktop app on a revision tab or a workspace file. Give a title, the problem and the proposed solution, a reason (defect, improvement, cost, manufacturing, supplier, safety, customer, other), a priority and optionally a date it is needed by. The revision and the file name are filled in. Screenshots, mark-ups and PDF reports can be attached (PNG, JPEG, GIF, WebP or PDF, up to 10 MiB each – the type is checked by the content, not the name). The CAD editors of the project group of the item and the watchers of the item are notified; the requester watches the request.
2. Discuss – everybody comments in the discussion thread; the requester, the assignee, everybody who commented and the watchers are notified.
3. Triage – a CAD editor of an affected project group (or an admin) starts the triage (and is assigned if nobody is), assigns it to the engineer who will do the work and decides:
   • Accept – the change will be made;
   • Defer – not now (reason required); take up again later;
   • Reject – no change (reason required). While no item is named, any CAD editor may triage; once the request is decided, an item is added only by a member of its project group (or an admin). A group can keep requesters from deciding their own requests (Review policy, see Read permissions).
4. Implement – an accepted request gets its change order: Create change order creates a draft with the in-work revisions of the affected items (items without a revision in work are listed – revise them and add the revision to the draft), or Link an existing open change order. The change order runs through review as usual.
5. Implemented – when a linked change order is released, the request becomes implemented in the same transaction, and everybody involved is told.

The requester can withdraw the request while it is New or In Triage. The revision page shows the open requests on its item (with their number on the Request change… button); the dashboard and the desktop worklist list the requests assigned to me and my open requests. Every step is in the audit log and in the status history of the request.

Change orders

A change collects one or more revisions in work, a title, description, priority and reviewers.

1. Draft – the author adds revisions (Release via new change… on a revision page) and reviewers – or the draft is created from an accepted change request.
2. Submit – the revisions move to In Review; they are frozen.
3. Each reviewer approves or rejects with a reason. Reviewers must be independent (see Separation of duties below).
4. When everybody approved, all revisions are released together, and the accepted change requests the change implements become implemented. A rejection sends them back to WIP; fix, reopen and resubmit – or cancel the change (takes effect at once).

A change can also retire released data: add an obsolete or supersede line for an item under Affected revisions (On release). When the change is released the revision becomes obsolete in the same step – a supersede line also declares the item superseded by its successor, and its watchers are told. A project group can require this way for obsoleting (Review policy, see Permissions); then the direct Mark obsolete and Supersede buttons answer 409.

Release readiness

A change releases a whole product at once. Before it can be submitted, every revision in it is checked against what it depends on:

The Release readiness card of a draft change lists them. Add puts a single in-work revision into the change. Add all to this change adds all of them, and level by level their own unreleased dependencies, in one step. Dependencies that are in review in another change have to be released there first. Dependencies of a project group you are not a member of are skipped by Add all; a member has to add or release them. The desktop app does the same with Include unreleased dependencies in the Release… dialog (on by default).

Separation of duties

Nobody reviews work they did themselves. TeamCraft refuses a reviewer who

• created the change order (the author),
• submitted it, or prepared it as an administrator for the author (added items or reviewers, edited or submitted the draft – read from the audit log), or
• changed the revisions under review: created a revision, uploaded a file to it, or has a logged check-in, revision, file, BOM (including BOM import and replace) or reference edit on it.

The rule is checked when a reviewer is added (400), when the change is submitted (409, naming the reviewer to remove) and again when a reviewer decides (403), because people can edit a draft after they were added. An administrator can still act for the author, but then cannot also review that change. The rule is always on; a team needs at least one person who did not touch the files.

One user alone cannot release. On a test server or a fresh installation with a single account, every change stays a draft: the author is never their own reviewer, and there is no administrator override – a release that one person approved for themselves would not be a release (#291). Create a second account (Admin → Users, a CAD editor) to try the review, or keep the change as a draft until a colleague can review it. The desktop Release… dialog says so when nobody else in the project group can review, offers the draft instead, and refuses the own user name before anything is created. A draft that cannot be submitted is never a dead end: its reviewers can be added and removed by user name, and it can be cancelled (web, desktop, DELETE /api/v1/changes/{n}/reviewers/{username}, POST /api/v1/changes/{n}/cancel).

The user who submitted a change is stored in changes.submitted_by. Changes that were already in review when the rule was introduced keep working: only the author is refused on those until they are withdrawn and submitted again.

Signing off a decision

A reviewer may state what their approval means (Meaning of your sign-off, e.g. approved as design owner; meaning in POST /api/v1/changes/{number}/review). When the server asks for a fresh sign-in (TEAMCRAFT_APPROVAL_REAUTH, see Configuration), the review form also asks for the password – or offers Sign in again for single sign-on accounts – and a decision without it is refused. The change page shows how each decision was signed off (password, single sign-on or an API token with the approve scope) and the stated meaning.

Review rounds and absent reviewers

When a change is withdrawn or reopened after somebody decided, the decisions of that round are kept (table change_review_rounds) and the next submit starts a new round. The change page shows the current round in the Reviewers card and the earlier ones under Earlier rounds.

A reviewer who has not decided yet but no longer can (account deactivated, role below editor, or not a member of a restricted group of an affected item) is marked Cannot decide. While the change is in review, the author or an administrator can replace any pending reviewer by another eligible user; the other decisions are kept, the substitute is notified and the audit log gets change.replace_reviewer. The substitute must pass the same checks as a new reviewer (editor role, four-eyes rule, sees every item).

Suggested reviewers

Next to the reviewer picker of a draft change, TeamCraft suggests up to five people who know the affected items, each with a one-click Add and the reasons in plain text. The suggestions come from the history TeamCraft already keeps – no AI, the same data always gives the same order:

Each source counts at most a few times per person, so one busy source cannot outweigh the others. Only active CAD editors and admins – the users who may review – are suggested, never the author, never the administrator who is preparing the change and never someone already assigned. People who changed the affected revisions know the item best but cannot review it: they are listed after the others as knows the item, cannot review without an Add button. The desktop app shows the same suggestions on the tab of a draft change, the REST API has GET /api/v1/changes/{number}/suggested-reviewers and AI assistants the MCP tool suggest_reviewers. Suggestions never assign anybody.

Notifications

The bell lists review requests, decisions, releases, checks needed, change requests and news about watched items, changes and change requests (Watch on any of their pages). Optionally TeamCraft sends them by e-mail (SMTP) and to Mattermost (a direct message from the TeamCraft bot to you, never into a channel). Every user chooses channels and mutes kinds on the account page; delivery runs from an outbox, so a slow mail server never delays a request.

Mattermost messages arrive as a direct message from the TeamCraft bot, with the full title and text; nothing is posted into a channel. Enter your Mattermost username on the account page if it differs from your TeamCraft login. If it is wrong (or your Mattermost account is deactivated), the notification shows Mattermost failed with the reason on the page Notifications, for example Mattermost user “xy” not found – check your Mattermost username. Send a test on the account page checks the setting.

With e-mail switched on, CAD editors also get a digest of the change requests waiting for triage – one e-mail per project group, by default once a day: the requests raised since the last digest that are still New, and the numbers of the older ones that still wait. No new request, no e-mail. The digest also appears in the bell’s list, already marked as read. Mute E-mail digest of new change requests … on the account page if the immediate notifications are enough.

Other systems – CI, ERP, CAM, a team channel – can react to releases, reviews and change requests through event webhooks, which administrators set up.

Simulations (FEA, CFD)

TeamCraft manages the analyses that belong to a design next to the design itself: which part revision was analysed, with which file, what came out – and whether that is still valid after the design changed.

A simulation is an item

Create an item of type Simulation (numbers SIM-000001, …) with New item, or through the link in the Simulations card of a part. One simulation item is one analysis, e.g. Bracket – static, LC1–LC3 or Pump housing – modal. It has the usual lifecycle, revisions, check-out/check-in and change orders. Its files are the model, the solver deck, selected results, the report and pictures; TeamCraft recognises the common model and result formats (VTK, CalculiX, Nastran, ANSYS, Abaqus, OpenFOAM, Fluent, STAR-CCM+, CGNS, Exodus II, LS-DYNA, …) but does not parse them.

Fluent, STAR-CCM+ and Simcenter 3D files

• Simcenter 3D (NX CAE): .sim, .fem and .afm are recognised as NX simulation files by the SPLMSSTR container NX writes them in. The Nastran deck Simcenter 3D writes as .dat (SOL, CEND, BEGIN BULK, a $ comment naming Nastran or Simcenter) is a Nastran input deck; .f06, .f04, .pch and .op2 are Nastran results. A text .fem is an OptiStruct/HyperMesh deck, not an NX FE model.
• Fluent: case, data and mesh files – legacy (.cas, .dat, .msh), gzip-compressed (.cas.gz, …, checked by the gzip magic) and HDF5 (.cas.h5, .dat.h5, .msh.h5, checked by the HDF5 signature) – plus the project (.flprj), CFD-Post data (.cdat), journals (.jou), transcripts (.trn) and report files (report-file-*.out).
• STAR-CCM+: the .sim (when its beginning names STAR-CCM+), the solution history (.simh) and macros (.java files that name STAR-CCM+ or import its API – other Java sources stay unclassified).

None of the binary files (.sim, .simh, .op2, HDF5, legacy binary data) is parsed beyond its first bytes. The text files – transcripts, report files, journals, macros, .f06/.f04/.pch – are read as text for the search, the assistant and the extraction templates (below).

Based on – what was simulated

The Based on card of a simulation revision lists the revisions it was computed with, each with a role:

Add a basis by item number, revision code (empty = latest revision) and, optionally, a file name: TeamCraft then pins the current version of that file, so the simulation records exactly which file version it used. Like BOM lines the basis links belong to the simulation revision: they change only while it is checked out, Revise copies them, and they are frozen when the simulation is released.

New simulation from a part or assembly. On the page of a part or assembly revision, New simulation based on PRT-000002/A (card Simulations and the More menu) opens the new-item form prefilled from that revision: the basis line with a role select (geometry by default), the type fixed to Simulation, the name Simulation – <name of the basis>, a description with the basis revision and material, and the project group of the basis (or your first group when you may not create items there – the form says so). Unit, classification, material, mass and cost do not apply to a simulation and are hidden; the item number is generated from the group’s scheme (the hint shows the next one). Creating adds the basis link in the same transaction: the current version of the STEP file of the basis revision (else its first CAD file) is pinned, without a file the revision alone is linked. You land on the basis card of the new simulation, which is checked out to you. A basis you may not read behaves like a missing one: the plain form is shown and nothing of it is echoed. Further bases are added on the Basis card.

The part or assembly shows the other side in its Simulations card: every simulation whose latest revision is based on it, with state, failed results and whether it is up to date.

Out of date

A simulation is out of date when, for one of its bases,

• a newer revision of the basis item was released,
• the basis revision became obsolete, or
• the pinned file has a newer version (or the pinned version was deleted).

The reason is shown next to the basis (PRT-000012/C was released (simulated: B)). A basis in a restricted group that the reader may not see shows no reason (see Read permissions). Releasing or obsoleting a basis also flags the simulation for a check through the normal change propagation: the simulation shows Check needed, its author and watchers are notified, and the change’s impact analysis lists it. Acknowledge the check with a note when the result is still valid (fillet change outside the stressed region), or revise the simulation, re-run it, update the basis and the results and release it – that resolves the check.

Releasing the basis revision itself (the simulation was based on an in-work revision that is now released) only flags the simulation when a pinned file has changed since; without a pinned file TeamCraft cannot tell.

Results

The Results card holds the key numbers of the run: name, value, unit, optional lower and upper limit, load case, solver and solver version. A value passes when lower limit ≤ value ≤ upper limit (limits inclusive, either may be empty) and fails otherwise; values without limits are informative. The card summarises failed and passed values; the part’s Simulations card shows the number of failed values.

Values are edited in the table while the simulation revision is checked out, or imported from a CSV or Excel table:

name,value,unit,limit_low,limit_high,load_case
Max. von Mises stress,182.5,MPa,,250,LC1
Safety factor,1.37,,1.5,,LC1
First eigenfrequency,2.35e2,Hz,200,,modal

Optional columns: solver, solver_version, note. Semicolons, tabs, decimal commas and German column names (Kennwert, Wert, Einheit, Untergrenze, Obergrenze, Lastfall) work too; min/max are accepted as limits. A value with the same name and load case is updated, new ones are appended; Replace all values removes the values that are not in the file. CSV on the card exports the table in the same layout.

Solver scripts write their results through the REST API (PUT …/simulation/results replaces the set in one transaction; see the REST API).

Solver summary of a file

For solver output a one-line summary appears next to the file on the revision page (and in the vault explorer): solver and version, how the run ended (converged, END OF JOB, fatal), the last iteration or time step, and the number of FATAL and WARNING lines. It is made at check-in from the first and the last 64 KiB of the file only, so the counts cover those two windows, not the whole file – the line says so. Supported: Fluent transcripts (.trn) and report files, Nastran .f06 and decks (SOL), STAR-CCM+ macros (.java) and batch logs (.log/.txt that name STAR-CCM+). The summary is a hint read from a user-written file, never a verified result; the MCP tools mark it as untrusted data. The rules follow public documentation and typical output and are not yet checked against real files of these programs; a file that does not match shows no summary. Files stored before the feature have none until they get a new version.

Values from files at check-in

Two bounded ways fill the table without typing – neither reads big result files:

The exchange file. A file named teamcraft-results.json or teamcraft-results.csv (at most 1 MB) checked in with the simulation revision sets the values in the same transaction as the check-in, with an audit entry:

{ "results": [
  { "name": "Pressure drop", "value": 388.25, "unit": "Pa", "limit_max": 500, "load_case": "nominal" },
  { "name": "Max. von Mises stress", "value": 182.5, "unit": "MPa", "limit_min": null, "limit_max": 250,
    "solver": "CalculiX", "solver_version": "2.21", "note": "" }
] }

A bare array works too. name and value (a number) are required; unit, limit_min, limit_max, load_case, solver, solver_version and note are optional; other keys are refused. The CSV has the columns name,value,unit,limit_min,limit_max,load_case (see above). A value with the same name and load case is updated. A malformed file refuses the whole check-in with the place of the problem (results[1].value must be a number, Row 3: …, JSON line and column) – nothing is half-written, the revision stays checked out.

Extraction templates. Managers of a project group (and administrators) define templates on the group’s page, or through the REST API. A template finds one number in a small text file (.txt, .csv, .log, .out, .dat, .rpt, .html, Fluent .trn and .jou, Nastran .f06, .f04 and .pch, STAR-CCM+ .java, … – the first 2 MB are read, and with pick = last the last 2 MB of a larger file as well). An HTML report is not read as markup: the template sees the text TeamCraft extracted from it (see below), one line per table row with the cells separated by |, so Maximum stress \| ([-+0-9.eE]+) \| MPa finds the row Maximum stress | 152.4 | MPa, and a csv template reads such a table with | as the separator (always for an HTML file, whatever the title and paragraphs above the table contain; an empty header cell keeps its column).

Example: Pressure drop:\s*([-+0-9.eE]+)\s*Pa on *.log. Regular expressions run in linear time (no backtracking) and are limited in size, so a hostile pattern or file cannot hang the server. The value is shown with its source (solver.log:412) in the Solver column. For an HTML report the line number refers to the extracted text – the text read_file_text shows –, not to the line in the HTML file. A template that does not match does nothing; templates belong to one group and apply to simulations of that group only. Values typed in by hand are overwritten by a template or the exchange file with the same name and load case on the next check-in.

A value found in the end of a large file shows its place counted from the end (run.trn: line 3 from the end), because the lines before it were not read.

Fluent report files. A report file (report-file-0.out, written by the report definitions of a run) looks like this:

"report-def-0-rfile"
"Iteration" "pressure-drop" "flow-time"
("Iteration" "pressure-drop" "flow-time")
1 2.53e+02 0.001
2 2.49e+02 0.002

A table template with csv_column = pressure-drop and pick = last reads the value of the last row (2.49e+02); with csv_key_column = Iteration and csv_key_value = 500 it reads the row of iteration 500 instead. STAR-CCM+ exports its monitors and reports as CSV (csv method). For Simcenter 3D / Nastran a regex template on the .f06 works for numbers that stand on one line; the tables in the middle of a large .f06 are better written to an exchange file by a post-script.

Values from a report (assistant)

A CFD or FEA report is usually a PDF or an HTML page. TeamCraft reads the text of both when they are uploaded, so the assistant can read it with read_file_text:

• PDF: the text layer, in an isolated process with a time, size and memory limit: at most 32 MB, 100 pages and 200 000 characters. Scanned PDFs have no text; there is no OCR.
• HTML (.html, .htm – the report generators of many FEA/CFD tools write them): the readable text, in the same isolated process and with the same limits (the first 16 MB of the file, 200 000 characters). A table row becomes one line with the cells separated by | (Equivalent (von Mises) stress | 0.0213 | 152.4 | MPa); numbers, signs, exponents and units stay as written, character references (°,  , °) are decoded. Scripts, styles, comments, embedded (base64) images and hidden elements (hidden, aria-hidden="true", inline display:none / visibility:hidden) are skipped – hidden text is not part of the report and could carry instructions for the assistant. The charset comes from a byte order mark or <meta charset>, else UTF-8, else Windows-1252. Only the HTML file itself is read: images, style sheets and linked pages (a report with a report_files/ folder) are never fetched or followed – attach a sub-page as its own file if its numbers are needed. MHTML (.mht) and ZIP-packed reports are not read.
• Text (.txt, .csv, .tsv, .log, .md, the solver logs, report files and scripts .out, .trn, .jou, .f06, .f04, .pch, .java, …): the text itself, line by line with its decimal numbers (the first 4 MB, 200 000 characters). A larger file keeps its end as well – the last 64 KiB (at most 50 000 characters) after the marker [… middle of the file left out …] – where a solver writes its status and final values.

The Fill with AI… button on the Results card (shown to editors of the group when the server has an assistant and the group has not switched the assistant off) opens a box: What to extract (the values you want, optional – empty means every key number of the report), Limits to use (optional, for example “upper limit 250 MPa for stress”, applied only where it fits a value you named) and the report files to read (PDF, HTML or text, all ticked). Propose values is the request for drafts. Values you asked for that the report does not contain are reported as Not found and are not proposed; numbers are taken as written, never converted. Proposing works without a check-out, accepting needs it.

The quick action Fill result values from the report on the simulation page (drafts must be allowed) – or the MCP tool propose_result_values – proposes the key numbers the report states. A proposal is a draft: it names the file version and quotes the text it was read from (the quote must stand in the report, so numbers cannot be invented from nothing) and appears under Proposed from reports on the Results card. A CAD editor of the group accepts it (the revision must be checked out to them, as for any value; the value then shows the file as its source) or rejects it. The assistant never writes a final value and never releases anything; every proposal, acceptance and rejection is audited. Compare every number with the quote before accepting – the model can misread a table.

Results in 3D

Result files in open formats open in the browser’s 3D viewer like CAD previews – no ParaView needed. View result in 3D on the Results card (or 3D next to the file) shows the outer surface of the mesh coloured by a result field, with the field’s minimum and maximum above the canvas.

How the preview is made:

• Surface. Volume elements (tetrahedra, hexahedra, wedges, pyramids, quadratic ones by their corner nodes) contribute only the faces no other element shares; shells and polygons are drawn as they are, beams and lines are not. Interior nodes are dropped.
• Fields. Point data is shown as it is: one-component values directly, vectors as magnitude, six- or nine-component tensors as von Mises equivalent. Cell data is averaged to the nodes (shown as name (cells)). Up to eight fields are carried; the viewer offers them in a selector, the active scalars of a VTK file (or STRESS for .frd) first. A CalculiX block that occurs for several increments shows the last increment. Nodes without a value are grey. Units are shown when the file names them – VTK and FRD files usually do not.
• Limits. Up to 20 million nodes and cells; surfaces with more than two million triangles are thinned out evenly (gaps are visible), surfaces with more than eight million are refused. Collapsed elements (a hexahedron written as a wedge, …) are matched by their distinct corner nodes. Structured grids (.vts, .vtr, image data), time-step collections (.pvd, .vtm), binary .frd, Exodus II and CGNS are not previewed – export the step you want to show as .vtu (ParaView: Save Data, OpenFOAM: foamToVTK, CalculiX: *NODE FILE, OUTPUT=ASCII or ccx2paraview).

Like all previews, the conversion runs once per file version in a separate process with a time limit and is cached; damaged files show an error message instead of a model.

Large results

Result files can be huge, and TeamCraft does not read them fully. A file above TEAMCRAFT_PREVIEW_MAX_RESULT_MB (default 64 MB) is stored and downloadable but gets no 3D preview (the page says so); smaller ones are converted in an isolated process with a time and memory limit. Numbers are never extracted from solver output on their own. To get the key figures into the Results table, type them in, import a CSV/Excel table, or let a script or an agent fill them in from a report. For pictures, attach rendered images (PNG, JPEG or WebP, at most 8 MB each): they appear as a small gallery on the Results card of the revision.

Comparing results

Compare with another revision on the Results card puts the values of two revisions of the simulation side by side – matched by name and load case, with the difference, the relative change and the pass/fail status of both.

Finding simulations by their results

The item list (Result values and Result name in the filter bar, result= and result_name= in the URL and in GET /api/v1/items) looks at the result values of the latest revision of simulations:

result_name is a case-insensitive “contains” on the value name and can be combined with result (the same value must match both), the type, project, state and text filters. An unknown result is refused by the REST API. Only items the user may read are found and counted: restricted groups stay out of the list and its total.

The dashboard shows a card Simulations to check: simulations the user may read whose latest revision (not obsolete) has a failed value or is out of date (see above), ten at a time, with a link to the search. Bases the user may not see never make a simulation appear out of date.

Limits of version 1

• Result values are not extracted from solver result files (by design: large results are never parsed fully) – use the exchange file, templates on small text files, a CSV/Excel table or the REST API; VTK, VTU/VTP and .frd files are previewed in 3D (see above), the other result formats are stored and recognised, not parsed.
• Large result files go through the normal upload (TEAMCRAFT_MAX_UPLOAD_MB); chunked, resumable uploads and a retention rule for intermediate results are open work.
• The desktop app shows simulation items and their files; creating a simulation from a part revision (web: done) and checking out the basis files are planned.

As-built records

Real hardware is rarely built exactly to the design: a bore ends up a little too large and is accepted, a purchased part is replaced by a second-source part, a weld is reworked. An as-built record keeps what one physical unit really is, next to the design it was built to. The background and how other systems solve it are on the research page As-built records.

A unit is an item

An item of type As-built (numbers AB-000001, …) is one physical unit or one lot. It has the usual lifecycle, revisions, check-out/check-in, files (photos, measurement reports, a 3D scan, the traveller) and change orders. A new revision of the as-built item is a new state of the same unit – after a rework, a repair or a retrofit; the older revision stays for traceability.

On top of that an as-built revision carries

• a build record – the design revision (part, assembly or software) the unit was built to, the serial or lot number, the build date and a note;
• deviations – how the unit departs from its design and what was decided;
• its BOM – the regular BOM of the revision, holding what was really installed.

Like BOM lines, build record and deviations belong to the revision: they change only while it is checked out by you, Revise copies them, and they are frozen at release.

Recording a built unit

On a part, assembly or software revision, the Built units card has Record a built unit: serial or lot number, build date, optionally the item number, name, note and project group of the new as-built item. TeamCraft creates the as-built item (revision A, checked out by you) with its build record and, for an assembly, a copy of the design’s BOM – in one step. Edit that BOM to what was really installed; Compare BOM with the design shows the differences.

An as-built item created with New item starts without a build record; enter it in the Built to card of the revision (item number and revision of the design – empty means its latest revision).

Rules:

• The serial number is unique per design item (letters compared without case). The revisions of one unit share it; another unit with the same serial is refused and named (or called “another unit” when it is in a group you may not read).
• The design revision may be in work, in review or released – prototypes are often built before the release. An obsolete design revision is refused for a new unit or a new build record (“record the unit against a current revision of the design”). A unit that was already built to a revision that later became obsolete keeps its record and may still correct serial, date and note.
• The as-built item may live in another project group than the design. Copying the BOM out of a restricted group needs a manager of that group, as for Save as.

Deviations and their disposition

Each deviation has a kind (dimension, material, component, process, other), the feature (e.g. Bore Ø12 H7), what was designed and what was built (text, e.g. 12.000 +0.018/0 → 12.035), a note and the disposition:

An as-built revision holds at most 1000 deviations.

Release

A change order with an as-built revision cannot be submitted while that revision has no build record or an open deviation. The engineering decision on the deviations is the review of the change order itself.

A project group can ask for more: with A reviewer confirms each “use as is” deviation in its review policy, a reviewer of the change order confirms every use as is concession on its own (Confirm in the deviation table) before their approval counts, and the person who recorded the deviation cannot confirm it. See Read permissions and review policies.

The design side

The Built units card of a part, assembly or software revision lists the units built to any revision of the item – the latest revision of each unit, with serial number, the design revision it was built to, open deviations and a Newer design marker when a later design revision was released after the one the unit was built to. Units in groups you may not read are only counted. A design item that units were built to cannot be deleted.

When you may read the unit but not the design (the design is in a restricted group), the build record shows a “restricted item” placeholder instead of the design’s number, name and revision.

What is not included

• Pack and Go (…/package) of an as-built revision contains its files, BOM and manifest like any other revision, but not the build record and the deviations; read those with GET …/as-built (REST) or get_revision (MCP) and keep the export next to the ZIP if another system needs them.
• Not yet: retrofit campaigns (change propagation to built units), serial numbers on as-built BOM lines, numeric tolerance checks and the import of measurement reports.

REST API and assistants

The endpoints are listed in the REST API reference. The MCP tool get_revision returns as_built for an as-built revision and built_units for a design (MCP server).

Desktop app

TeamCraft Desktop (desktop/, Tauri 2) is a rich client for Linux, macOS and Windows: a navigator tree of the project groups, object tabs (overview, files, structure, where used, references, graph, changes, history, 3D viewer), a worklist with check-outs and reviews, and a local working folder:

• New (Ctrl/Cmd+N) creates an item together with its files: choose the CAD files first, name and type follow from the first one;

• Check out takes the lock, copies the files into the working folder and makes them writable. For an assembly it also downloads every part of its structure that is missing (latest version, read-only) – only the assembly is locked; parts you changed locally, or whose place is taken by another file, are never overwritten and are listed in the report (Settings → Workspace switches this off);

• Files / All items / Structure in the navigator head: Files shows the folders and files of the project group as in its working folder (see below); Structure shows, per project group, the assemblies and the parts no BOM uses; an assembly expands into its parts one level at a time with quantity, state, lock owner and ⧉ N for a part used in several assemblies;

• Get… on a revision copies the item with everything it consists of – its BOM resolved with a revision rule and the parts its CAD files reference – so the assembly opens in the CAD program (see below);

• the download icon next to Projects in the navigator (Tools → Get Project Groups…) copies the files of every item of chosen project groups into the working folder – for new team members;

• the folder icon next to it (Tools → Import CAD Folder…) brings an existing CAD folder in: scan first (nothing is uploaded), then one item per part or assembly with its drawings and exports; every file keeps its folder, so the working folder later looks like the original tree. An interrupted import continues where it stopped – an item whose files did not arrive is completed, none is created twice; the app remembers per project group what it imported, so the same folder can also be imported into another group. BOM lines come from the references in the assembly files – for NX also from .prt files (such an assembly is imported as a part item, NX does not tell parts and assemblies apart by the file type). Their quantity is how often the assembly places the part where the file tells it (SOLIDWORKS 2015+, NX, Inventor and STEP assemblies with external part files; instances excluded from the BOM and suppressed Inventor occurrences do not count, a part that is only placed that way gets no BOM line but stays referenced); for other formats (Solid Edge, …) it is 1 with the note check the quantity – set the real quantities with Import BOM… from the CAD program’s BOM export. Help → How to Import a CAD Folder is the step-by-step tutorial (Pack and Go, unique file names, check and release);

• Import BOM… (in the Structure tab and the More menu of a revision you have checked out, or Tools → Import BOM as New Assembly…) reads a BOM exported by the CAD program – CSV, Excel, ODS or a STEP assembly – with the same column recognition as the web import: the preview shows the lines, how many items are new or existing and the notes (for example a quantity that is not a number); Import adds the lines in one step, creating the missing items. Part numbers from the file or New numbers (the group’s numbering scheme), and whether items with the same number are reused, are chosen in the dialog;

• Quantities from CAD… (next to Import BOM…) compares the BOM with the instances counted in the revision’s CAD files (SOLIDWORKS 2015+, NX, STEP assemblies with external part files): missing lines and lines whose quantity differs – such as the quantity 1 of an assembly imported before the counts existed – are ticked; Apply adds and corrects them in one step (the same plan as Create BOM from CAD references… in the web UI). A quantity the CAD file does not tell never replaces an existing one;

• the Graph tab draws a navigable reference and BOM graph around the revision: the focused item in the middle, its BOM children and references below (ref), the assemblies that use it above (uses). Every node is a card with the item’s preview image, file name and number. Node colour is the lifecycle state (the legend names them), node size (and the ⚙ badge) the item’s own BOM complexity; the small ×n in the top-left corner of a child is how many instances of it the assembly contains (summed over its BOM lines, ×1 included). Click a node to go to it: the tab becomes that item – a sub-assembly shows its own graph, anything else its overview – and ← Back, always in the same place (left of the tab row), leads back the way you came, one step per click; clicking the assembly you came from is the same step back. A click on the item in the middle opens its own overview. Ctrl+click (⌘+click on macOS) opens a node in a tab of its own instead. The mouse wheel zooms on the cursor, dragging pans – also when the drag starts on a card, which then does not open – and a double-click on the background fits the graph again; while previews are still loading the view fits itself until you zoom or pan. Large assemblies (more than 8 neighbours on a side) are laid out in rows, and only the first 48 neighbours get a preview and their complexity (one request each), the rest keep a basic card. The graph is drawn by the app itself (SVG with an HTML layer for the cards, no external engine), in the colours of the chosen skin;

• the Workspace tab shows per file where it is, whether it is up to date, modified, outdated, in conflict, new, missing or a name clash, whether it is read-only, and who holds the lock for how long; opening an outdated file or one somebody else has checked out asks first;

• Check in… uploads the selected files as new versions and releases the lock – based on the versions they were copied from, so a version somebody else checked in meanwhile is never overwritten (see Concurrency) – and makes the files read-only again; files above 32 MiB are sent in resumable chunks – a dropped connection resumes where it stopped (see Large files). The dialog stays open with the progress while the check-in runs, and Cancel stops it at any point until the last byte is sent: before the next STEP export, between two chunks of a large file (the chunks on the server are discarded – a cancelled upload starts over next time) or half-way through the request with the small files. Nothing is stored then, the revision stays checked out to you and your local files are untouched. Once every byte is sent the server finishes the check-in on its own; the dialog says so (too late to cancel);

• Check in all in the worklist first lists the check-outs with local changes (modified or new files) and offers to check them in first with their files; Only the others checks in just the check-outs without local changes. Check-outs with a conflict always stay checked out – merge them in their Workspace tab. Sign out (and Change server) asks the same before it signs you out: Check in and sign out, Park and sign out or Sign out anyway;

• Park… (Workspace tab, More ▾, and a button of the check-in dialog) uploads the ticked files as new versions but keeps your check-out – work in progress is on the server even if your computer is lost, and nobody else can change the revision meanwhile. Same conflict check as a check-in; an empty comment is stored as Work in progress (parked, still checked out);

• when somebody else released your check-out (an administrator, or a manager of the group with a reason), the Workspace tab says Released by X; your local changes are kept and need a new check-out, with the date and the reason – until the revision is checked out again;

• Dependents to check (worklist and home) shows one line per dependent revision with the number of changes it has to be checked against; the arrow lists them (a click opens the item that changed). On the home page every dependent has Open, Revise and Acknowledge all… (one note for all of them, see Change propagation) and an Acknowledge… per change;

• Request change… on a revision tab and Request… on a file (Files and Workspace tabs) raise a change request with the item, revision and file name filled in and an optional screenshot or PDF; the worklist lists the requests assigned to you and your open ones;

• on Windows with Inventor or Solid Edge installed, STEP (workspace) and the check-in option create STEP exports for the 3D preview with that program; the Files tab shows the preview image stored in native files.

• with a Preferred CAD program set on your account page in the web UI, the Files tab of a revision collapses the native files of other CAD programs (see Files); the app reads the setting at sign-in.

• Agent (rail, View → Agent, Ctrl/Cmd+4, or Agent in a revision or change tab) is the app’s one place for AI. It runs on one of two backends, decided by the server’s policy and your choice:

  • Company AI – the server’s assistant, configured by the administrator (the key stays on the server). It is the Ask TeamCraft conversation of the web UI, inline in the Agent tab: it knows the last revision (and its section, BOM with revision rule), change order or change request tab you opened, offers quick actions that fit it (Draft release notes, Check before release, Brief me for this review …), has the Allow drafting checkbox, Cancel and New conversation, and keeps one conversation on the server that survives restarts.
  • Local agent – an AI agent on your computer that you set up under Settings → Agents…, for example Claude Code through its ACP adapter or Gemini CLI. None is set up by default. The app starts the agent in the workspace folder and gives it TeamCraft’s tools with your rights. The conversation streams in the tab, with tool calls, the agent’s plan, permission prompts (Allow once / Reject), Cancel and quick prompts (release notes, release check, change review, worklist triage). Through the app the agent may only read text files in the workspace folder; it gets no write access and no terminal.

  When the server offers both, Company AI / Local agent in the Agent toolbar switches between them (each keeps its own conversation); the app remembers the choice per server and user, and starts with the local agent if you have set one up, otherwise with the company AI. If the administrator turned local agents off (TEAMCRAFT_LOCAL_AGENTS=off), the Agent view runs on the company AI only, the app ends a running agent and refuses to start one; with no company AI configured either, the view says that AI is switched off by the administrator. The app asks the server again when the Agent view opens, every minute and before every message to a local agent, so a changed setting takes effect without a restart. See ACP agents.

Sign-in runs through the browser (single sign-on or password, confirmed on a TeamCraft page) or with a personal access token. The app keeps the token in the system keychain (Windows Credential Manager, macOS Keychain, GNOME Keyring or KWallet on Linux). Where there is none, it uses a file only your user account can read and says so at the start and in Settings. An address with plain http:// to another computer gets a warning when you connect: the token and all data would cross the network unencrypted – use the https:// address of the server. The app uses the same skins and 3D viewer as the web interface; the models are converted by the server, and Loading or the reason a model cannot be shown appears on the canvas of the 3D viewer tab (see Files). Settings → Appearance: TeamCraft (the default) follows the light or dark appearance of the operating system and switches with it, TeamCraft Light and TeamCraft Dark stay fixed, the distribution skins are dark. Settings → Change password… changes the password of a local account (it asks for the current one; wrong ones count like failed sign-ins, and your web sessions end); single-sign-on accounts do not see it.

The window is built for daily work: object tabs on top, under them the toolbar of the open object with its one next step filled (see The toolbar) and the rare tools under More. The navigator shows a state as its symbol (a check: released, a ring: in review, a half-filled ring: in work, – obsolete, the name in the tooltip); the search field is Ctrl+F (⌘F).

Moving tabs: drag an object tab to a new place (a bar shows where it lands; the tab keeps its state, and a plain click still just selects it). Without a mouse: Ctrl+Shift+PageUp / PageDown move the active tab left or right, Ctrl+PageUp / PageDown (or Ctrl+Tab / Ctrl+Shift+Tab) switch to the previous or next tab, and the arrow keys move between the tabs when the tab strip has the focus. The right-click menu of a tab offers Move to start, Move to end, Close, Close others and Close tabs to the right.

The toolbar

The toolbar sits right below the tab strip and acts on the active tab. Its buttons are grouped, and they keep their place whatever state the object is in; a button that does not apply right now is greyed out, and its tooltip says why (for example Check out first or Already in change order CHG-000002). The one highlighted button is the most likely next step:

The working folder of your check-out is looked at again whenever the tab is shown or the app window gets the focus back – save in the CAD program, switch back, and Check in… is highlighted.

• revision tab: Lock (Check out, or Check in… and Cancel check-out / Force unlock while checked out) · Work (Edit, Get…, Open folder) · Lifecycle (Release…, Revise) · Collaborate (Request change…, Watch, Agent);
• change tab: Review (Approve change highlighted, Reject – the comment field of Your review goes with it, required for a rejection) while your review is pending · Lifecycle (Submit for review, highlighted on your draft – disabled with the reason as tooltip while the draft has no revision or no reviewer –, Withdraw, Cancel change for a draft or rejected change, at once) · Collaborate. On your draft the Reviewers panel has Add reviewer (user names, any CAD editor or administrator – not you), Remove per reviewer and the suggested reviewers;
• change request tab: Triage (Start triage or Create change order highlighted, Take up again) · Requester (Attach…, Withdraw) · Collaborate.

Release… creates a change order for the revision – with its unreleased dependencies by default – assigns the reviewers you tick (the other CAD editors of the project group) or type under Other reviewers (user names of any CAD editor or administrator) and submits it. Your own user name is refused before anything is created (four-eyes principle). When nobody else in the group can review, the dialog says so and creates a draft instead of submitting – a release always needs a second person, so a server with a single account cannot release (see Separation of duties). If a revision or a reviewer is refused, the half-made draft is cancelled again and nothing is left behind; only a refused submit (for example an unreleased dependency) keeps the complete draft and opens it.

Rare actions are in More ▾ at the end: Pack and Go…, Open in browser, Refresh (F5) and Mark obsolete…. The menu works with the keyboard: Enter, Space or ↓ opens it, ↑/↓, Home/End move, Enter runs the action, Esc closes it and returns to the button; a click outside closes it too.

The Overview of a revision shows At a glance next to the properties: the preview image stored in an Inventor, Solid Edge, SolidWorks or NX file (with the way into the 3D viewer) and the number of files, BOM lines, where used, references, change orders and open change requests – a click opens the matching sub-tab.

Projects (the rail button below Agent, Ctrl/Cmd+5) is where you choose the active project group: your groups first, then the others. CAD editors create a new group there (New – you become its manager; tick Restricted to keep it to its members), and the page offers Get… (copy groups into your workspace) and Import CAD folder…. The choice is kept on this computer.

Home is a file browser of the active group, in three views:

• Files (the view Home starts with): the folders of the group and the files in them, as in its working folder – folders first, then the files by name the way a file manager orders them (without regard to case, Part2 before Part10), each with the state and the lock of its item. The file name comes first and the number and revision after it, so a narrow navigator cuts the number, not the name. A folder opens its own level – a large group is never loaded as a whole, and a folder with more than 500 files offers show … more. The files are those of the latest revision of every item; items without files are listed below the files at the top of the group. The number next to the order is the rows of the whole group. A click on a file opens its item;
• All items: every item in one list, the name first (the first 500 by number);
• Structure: the assemblies with their parts.

Files and All items are sorted by name (or by number, type or state – the choice is kept). Change… goes back to Projects. New and Import CAD Folder… start with the active group. With a server older than the Files view, Home shows All items instead.

Home, Projects, Refresh and the dialogs that offer project groups (New, Get Project Groups…, Import CAD Folder…) load the groups and your memberships from the server again, so a group created or joined in the web UI shows without restarting the app.

Keyboard: Ctrl/Cmd+N new item, Ctrl/Cmd+F search, F5 refresh, Ctrl/Cmd+1/2/3/4/5 Home, Worklist, Changes, Agent, Projects, Ctrl/Cmd+W close the tab, Ctrl/Cmd + + / - / 0 (or Ctrl + mouse wheel) zoom.

How files appear on your computer

There is one working folder per project group, and inside it the files sit in the same folders as in the original CAD tree – one copy of each file. The revision is information TeamCraft keeps about the file, not a folder level:

Documents/TeamCraft/                     ← the workspace (Settings → Workspace)
├── ROVER/                               ← project group
│   ├── chassis/
│   │   ├── chassis.asm                  ← ASM-000001 rev. B, checked out by you (writable)
│   │   └── brackets/
│   │       ├── bracket.prt              ← PRT-000001 rev. A (read-only)
│   │       └── bracket.step             ← new STEP export next to it
│   └── drawings/
│       └── chassis.drw
├── LANDER/
│   └── …
└── .teamcraft/
    ├── state.json                       ← per file: item, revision, file id, version, SHA-256, checked out
    └── migration.log                    ← what the move from the old layout did

The folder of a file is stored with it on the server (Folder on the revision page, folder in the API). The folder import sets it from the scanned tree; uploads without a folder put new files at the top of the group, and a file keeps its folder when new versions arrive. While a revision is checked out, the revision page can move a file to another folder.

Read-only rule. Files you have not checked out are read-only on disk (the read-only attribute on Windows, no write permission on Linux and macOS). CAD programs then open them read-only, and nobody edits a file that cannot be checked in. Check out makes the files of the revision writable; Check in uploads the changed ones and makes them read-only again; Cancel check-out does the same without uploading. Files you changed are never made read-only or overwritten by TeamCraft.

Check-out of an assembly. The lock is taken on the assembly only; its structure is then fetched like Get does under the latest rule, in the same progress dialog. Per file: missing – downloaded read-only; up to date – skipped; an unchanged older copy – updated; changed here, checked out by you, or a different file at the same place – kept untouched and listed (kept – your local changes, name clash). Cancelling leaves no partial file. Add files. Add files… (Files section and More ▾ of a revision) takes files from a file picker, checks the revision out first if you have not, and copies them into its working folder – the originals are never moved or changed. New files go into the revision’s main folder or a sub-folder of it. A file with the name of an existing file becomes its next version and asks first (unticked files are not added). The copies appear as new files in Check in… – also files with an unrelated name, which TeamCraft remembers in .teamcraft/added.json until they are checked in – or tick Check in now. The Files section explains why the button is disabled: checked out by someone else (add after check-in), in review, or released (frozen: Revise and add the files to the new revision). Dropping files onto the window is not supported yet.

Get. Get… on a revision resolves its structure on the server – the multi-level BOM with the revision rule you choose (latest: the newest revision of every part, also in work; released: the newest released revision) plus the items whose files its CAD files reference (an assembly names its parts, a drawing its model) – and downloads only what is missing or outdated, compared by SHA-256. Every file is checked against its SHA-256 after the download and recorded at once, so a Get that was cancelled or interrupted continues where it stopped – also inside a large file: the bytes already received stay next to the file (<name>.<sha>.teamcraft-download, ignored by the working folder), the next Get asks the server only for the rest and checks the SHA-256 of the whole file before it puts it in place. A file that changed on the server meanwhile is downloaded completely again. The status bar shows the progress with a Cancel button.

Nothing is overwritten.

• A file you changed locally is kept (and listed) when the server has a newer version – conflict in the Workspace tab.
• Two items with a file of the same folder and name (chassis/bolt.prt in two items) cannot share one place: the second is reported as a name clash and not downloaded. Give one of them another folder on the revision page.
• A file in the way that did not come from TeamCraft is reported the same way.

Why not the browser? A browser download saves single files into the Downloads folder: no folder structure, so the CAD program cannot find the parts of an assembly; no record of which version a file is, so changes cannot be checked in safely; and no read-only protection. Browser downloads are fine for one file or for looking at something – CAD work goes through the desktop working folder. Pack and Go (ZIP) is for sending a structure to someone outside TeamCraft: after the save dialog a progress dialog shows how much has arrived, and Cancel stops it – also while the server is still packing. The ZIP is written under a temporary name next to the target and renamed only when it is complete, so a cancelled or failed Pack and Go never leaves a half ZIP behind.

Moving an older workspace. Earlier versions of the app kept one folder per revision, <group>/<item>/<revision>/ (and before that <item>/<revision>/). After the sign-in the app finds these folders and offers to move the files to their places in the new layout. Files whose place is already taken by a different file, and older revisions of an item whose newer revision takes the place, stay where they are; files you changed are moved first. Identical copies are removed, emptied old folders too, and every step is written to .teamcraft/migration.log.

Install or run it

The installers of every version are on the Releases page (see Download in the README for the file of each system). From source:

cd desktop
cargo run            # Linux needs the WebKitGTK development packages

The platform guides list the system packages.

Try TeamCraft on this computer

The downloads with local server (Windows x64 -setup.exe, macOS .dmg, Linux .AppImage, named TeamCraft-with-local-server_…) also contain the server, as teamcraft-server, and PostgreSQL’s programs. Their connect screen offers Try TeamCraft on this computer below the server address:

1. The app starts teamcraft-server local – a private PostgreSQL cluster and the server, both only on 127.0.0.1 – and waits until it is ready (the first start creates the database).
2. The server’s address http://127.0.0.1:<port> becomes the app’s server, and the browser sign-in opens. On the first start the browser shows Create the administrator; afterwards it continues to the confirmation of the app’s sign-in.
3. While the local server is the configured server, the app starts it again at every launch (the splash says Starting the local TeamCraft server …). It keeps the port, so the address and the token stay the same; if another program took the port meanwhile, the app picks a free one and follows.

The server stops when the app ends – also when it crashes: the app keeps a pipe to the server’s standard input open, and the server shuts itself and PostgreSQL down when it closes. Its output goes to local-server.log in the app’s settings folder; the data is in the per-user data folder shared with teamcraft local – see Try it on your computer. The regular installers do not show the button.

Update notice

Once a day at most, the app asks GitHub for the latest TeamCraft release. If it is newer than your version, the status bar shows TeamCraft x.y.z is available – a link to the release page in your browser. The app never downloads or installs anything itself; install the new version as you installed this one. × hides the notice until the next version; Settings → Updates switches the check off (for example on computers without internet access).

Crash reports

When the app crashes – a panic in the app, an uncaught error in its user interface, or a session that ended without closing normally (for example the web view crashed, the app hung and was force-quit, or the computer lost power) – it writes a report into the crash-reports folder of its settings directory. Before the report is written, the home folder (and with it your user name), server addresses and sign-in tokens are removed. The report holds no item data and no files.

At the next start a dialog shows the whole report:

• Report on GitHub… opens a new issue at the TeamCraft repository in your browser, prefilled with the report. You read it, add what you were doing, and submit it yourself; a GitHub account is needed. The full text is also copied to the clipboard, in case the link had to shorten it.
• Copy puts the report on the clipboard, for example for an e-mail.
• Delete report removes it without sharing.

Nothing is ever sent without that choice. Closing the dialog keeps the report for the next start. Don’t ask again (or Settings → Crash reports) stops the question; the reports then stay on the computer only. Background and the alternatives that were considered: Crash reports from the desktop app.

Ask TeamCraft (assistant)

Ask TeamCraft is an optional assistant built into the server. An AI model (Claude, or an OpenAI-compatible or local model, as configured by your administrator) answers questions about your PDM data. It looks things up with the same tools that the MCP server offers to external AI clients, and it uses your rights. It answers on the server, so nothing has to be installed on your computer.

It is meant for the reading and summarising work around a release, not for CAD generation:

Ask also covers change requests and simulations, for example:

• “What problems were reported on PRT-000012?” – open and closed change requests on the item with their discussion.
• “Prepare my request triage” – a summary of the change requests assigned to you with a suggested next step (like the MCP prompt triage_requests).
• “Which simulations are out of date after yesterday’s release of PRT-000012?” – the simulations based on it and why they no longer match.
• “Summarise the results of SIM-000003 rev B vs A” – changed, added and removed result values with delta and pass/fail.
• “What does the spec of PRT-000012 say about the coating?” – the assistant reads the text that TeamCraft extracted from the attached files for the search (STEP and IGES strings, text, CSV, JSON, XML, KiCad and similar formats, the text layer of PDF reports and the readable text of HTML reports with table rows as lines; not images, scanned PDFs or binary CAD files). It can read only files that you may open.
• “Draft a change request from my notes: …” – with drafts allowed (see below), the assistant raises the request; otherwise it shows what the request should contain.

Open it with the sparkle icon in the top bar (desktop app: the Agent view on Company AI, Ctrl/Cmd+4). You can add your own words to a quick action, e.g. “focus on the weld seams”. The answer shows the tools that the assistant used. Item numbers in the answer link to the item. The assistant remembers the conversation: see The sidebar.

The sidebar

Ask TeamCraft lives in a sidebar on every page of the web UI. The sparkle icon in the top bar unfolds a drawer on the right. It stays open while you move around, Esc closes it, and your browser remembers whether it was open (a small localStorage entry, nothing is sent to the server for that). Drag the left edge or use the arrow keys on it to change its width. On a phone it is a full-screen sheet.

The icon is only there when an administrator has configured the assistant.

In the desktop app the same conversation is the Company AI backend of the Agent view (Ctrl/Cmd+4; see ACP agents): a panel in the Agent tab instead of a drawer, with the same context chip, quick actions, drafts checkbox and conversation. Its context is the last revision, change order or change request tab you opened.

It knows the page you are on

Every page tells the drawer where you are. Above the question box a context chip shows it, for example PRT-000009/A · bom (latest released):

Click × on the chip to ask without sharing the page (add it back undoes that; moving to another page resets it). Quick actions under the chip fit the page: on a revision Draft release notes, Check before release, What breaks if I change this?, Are the simulations still valid?; on a change order Brief me for this review; on the dashboard What needs my attention. Words like “this” or “here” in your question mean the page you are on.

The page context is only a hint. The server looks every identifier up with your rights before the assistant sees it. An item, change or group you may not read is dropped exactly as if it did not exist: it does not appear in the chip, the answer, an error message or the conversation.

One conversation that stays

Your questions and the answers form one conversation that survives navigation, reloading and signing in again. Under each question the drawer shows where you asked it (asked on PRT-000009/A · bom). A follow-up such as “and which of those are released?” works. New conversation deletes it.

• Only the text of your questions and of the answers is stored (with the quick action and the page label) – never the data that the tools returned. A follow-up looks things up again with your rights of that moment, so nothing you lost access to comes back through a tool. (Your own earlier answers are part of the conversation and stay visible to you.)
• Only you can read it. Administrators see in the audit log that a question was asked (who, which quick action, tools, token counts) but never its text, and there is no administrative view of conversations.
• An idle conversation is deleted after 30 days (TEAMCRAFT_ASSISTANT_RETENTION_DAYS); deleting a user deletes the conversation.
• While an answer is on its way the drawer shows that it is working and offers Cancel; a cancelled question is not stored.
• The answer does not stream in: it appears when it is complete.

What it can and cannot do

• Read-only by default. It can read what you can read and nothing else.
• Drafts only when you allow them. CAD editors can tick Allow drafting change orders, change requests and comments. The assistant can then create a draft change order, add revisions to one of your drafts, raise a change request or comment on one – only when your question asks for it. It never submits, approves, releases or makes anything obsolete, and it never triages, accepts, defers or rejects a change request. Those decisions stay with people. (Viewers raise and discuss change requests themselves in TeamCraft, or through their own MCP client.)
• Opens the 3D preview for you. Ask “show me the bracket from the rover arm in 3D”: it finds the item (with the MCP tool open_3d_preview) and shows an Open 3D preview button under its answer, which opens the browser’s 3D viewer of the best 3D file of that revision (STEP first, then meshes and native lightweight models). When several items match, it lists them and asks which one you mean instead of guessing; when the revision has no file the viewer can show, it says so. The button only ever points to TeamCraft’s own viewer page (/files/<id>/preview): the server checks the link before it is shown, and the sidebar checks it again. It appears under the fresh answer only – the stored conversation keeps the text. In the desktop app’s Agent view (company AI) the button opens the revision tab on its 3D viewer with that file.
• Check the answer. It is generated by an AI model from the data that the tools return. Numbers, states and quantities come from TeamCraft, but check them before you rely on them.
• Limits. One question may take up to 12 model steps (configurable) and 4 minutes. Ask a narrower question when a limit is reached.

Privacy

The assistant is off unless an administrator configures an AI provider and an API key (see Configuration). Without one no data leaves the server, and the buttons are hidden.

When it is on, your question, the instruction of the quick action, where you are (the identifiers and search text of the page, only what you may read), the earlier messages of your conversation and the results of the tools it calls are sent to the AI provider that your administrator configured. The dialogs name it (provider and host). Which one receives the data depends on the setup:

The data includes item names, descriptions, BOM lines, change order and change request texts (with their comments) and simulation result values. Files and attachments are not uploaded; only their names and metadata are. The API key stays on the server. Browsers and the desktop app never see it, and the server never sends it to another host than the configured one. The audit log records each run (assistant.run): who asked, which quick action, the length of the question, the provider and model, the tools used, the page kind and identifiers, and the token counts. The audit log never stores the question, the answer or the search text. The conversation itself (question and answer texts) is stored in the TeamCraft database, readable only by its owner, and deleted after the retention time or with New conversation. The terms of the provider (retention, training use) apply to what it receives: choose the provider and the plan accordingly.

API

GET  /api/v1/assistant          → {enabled, provider, model, host, actions: [{id, label, needs}]}
POST /api/v1/assistant
     {"action": "release_check", "context": {"item": "ASM-000003", "revision": "B"}}
     {"question": "Where is PRT-000012 used?", "allow_drafts": false}

Page context and conversation

context accepts the page context the sidebar sends; every field is optional and an unknown or invalid one is dropped (except item, revision and change, which answer 400 when malformed):

{ "kind": "bom",                 // dashboard, items, item, revision, bom, where_used, compare,
                                 // change, changes, request, requests, simulation, project,
                                 // projects, search, vault, notifications, other
  "item": "PRT-000009", "revision": "A",
  "change": "CHG-000004", "request": "ECR-000002", "project": "ROVER",
  "view": "bom",                 // section or tab: lowercase letters, digits, - and _
  "rule": "released",            // revision rule of a BOM view
  "query": "bracket", "filters": {"state": "released"},   // text typed on the page
  "selected": "PRT-000010",      // the selected row
  "shown": ["PRT-000010", "PRT-000011"] }                 // rows shown, at most 25 are kept

The identifiers are hints: the server resolves each with the caller’s rights and drops what the caller may not read, exactly like an identifier that does not exist. The answer then carries context: {kind, label}, the resolved page (PRT-000009/A · bom (released)).

When the run called open_3d_preview, the answer carries links: at most three {action: "open", kind: "preview3d", url, label, item, revision, file}, where url is always the relative path of this server’s 3D viewer page (/files/<uuid>/preview) – the server drops any other URL. Clients show them as buttons; the field is left out when there are none, and the stored thread does not keep it.

With "thread": true the question joins the caller’s conversation: the earlier messages are quoted to the model, and the question and the answer are stored (text only). Without it the call is stateless as before.

GET    /api/v1/assistant/thread  → {messages: [{role, text, action, context_kind, context_label, created_at}], retention_days}
DELETE /api/v1/assistant/thread  → {deleted: true}   # new conversation

A conversation belongs to the token’s user. These endpoints take bearer tokens only; the web sidebar uses GET /assistant/thread, POST /assistant/chat and POST /assistant/thread/reset with the session cookie (same-origin only), which are not part of the REST API.

action is one of ask (default, needs question), release_notes and release_check (need context.item, optional context.revision), impact, simulation_status and result_values (need context.item), review_brief (needs context.change) and attention. The answer contains answer.text (markdown), answer.truncated, tools ([{name, ok}]), steps, model and the token counts. GET /api/v1/me reports capabilities.assistant. While the assistant is off the POST endpoint answers 404. When the AI service is overloaded or busy it answers 503.

ACP agents in the desktop app

Ask TeamCraft runs on the server with the administrator’s provider and key. In the desktop app it is one of two backends of the Agent view (Company AI); the other is an agent on your own computer (Local agent). When the server offers both, Company AI / Local agent in the Agent toolbar switches between them. Each keeps its own conversation: the company AI’s is stored and audited on the server, the local agent’s lives in its process on your computer. The app remembers the choice per server and user and starts with the local agent if you have set one up, otherwise with the company AI.

The local agent speaks the Agent Client Protocol (ACP), which connects clients to agents on your computer, for example Claude Code (through its ACP adapter) or Gemini CLI. The desktop app is the ACP client. The server needs no API key for this. The agent uses its own sign-in or key with its own provider.

Your administrator can turn local agents off for the whole server (TEAMCRAFT_LOCAL_AGENTS=off, see Local agents), so that AI use goes through the company AI, Ask TeamCraft, instead of AI tools of your own (data-loss prevention: the organisation’s provider and contract, the key only on the server, every question in the audit log and within the assistant’s limits). The server then refuses every MCP client, also one you set up with your own token, and the desktop app ends a running agent and refuses to start one – it asks the server again when the Agent view opens, every minute and before every message, so this needs no restart. The Agent view (Ctrl/Cmd+4) then runs on the company AI, automatically and without a local option, with a short note that your organisation provides its AI centrally – or, if no assistant is configured, says that AI is switched off by the administrator (local agents off, no company AI).

Set it up

1. Settings → Agents… (or Agent in the navigation rail → Set up an agent…). No agent is set up by default, and TeamCraft never installs or starts one on its own.

2. Add an agent. The presets only fill in the fields:

   Agent	Program	Arguments	Needs
   Claude Code	npx (Windows: npx.cmd)	-y @zed-industries/claude-code-acp	Node.js; npx downloads the adapter from npm the first time; sign in with claude once or set ANTHROPIC_API_KEY
   Gemini CLI	gemini	--experimental-acp	npm install -g @google/gemini-cli, then sign in once with gemini

   Any other program that speaks ACP over stdio works too. Desktop apps often do not see the PATH of your shell (macOS in particular). If the program is not found, enter its absolute path, for example /opt/homebrew/bin/gemini. Package names change: check the adapter’s own documentation if npx reports an unknown package.

3. Open Agent (rail, View → Agent, Ctrl+4; if it shows the company AI, click Local agent in its toolbar), pick the agent and press Start.

Working with it

• The conversation is a tab of its own. Answers stream in as they are written. Tool calls appear in the conversation and in the navigator with their status (waiting, running, done, failed). The agent’s plan is shown in the navigator if the agent shares one.
• Context: each message tells the agent which revision or change order you last had open. The Agent button in a revision or change toolbar opens the agent with that object as context.
• Quick prompts use the server’s MCP prompts: Release notes and Release check for the open revision, Review this change for the open change order, Triage my worklist anywhere.
• Permission requests of the agent show up in the conversation with Allow once and Reject. The desktop app never grants an “always” permission.
• Read-only TeamCraft tools need no prompt. When the agent asks to run one of TeamCraft’s own read-only MCP tools (search, get an item or a BOM, where-used …), the desktop app answers allow once by itself. The tool list marks such a call Allowed automatically (read-only). Nothing is widened by it: the agent calls the tool with your token, and the server answers with your rights only – a restricted group you are not in stays “not found”, as in the web UI. Everything else still asks: TeamCraft’s write tools (draft change orders, comments, result proposals), tools of any other MCP server, the agent’s own tools (files, commands), and every request the app cannot identify for certain (see below). To be asked every time, tick Ask before read-only TeamCraft tools under Settings → Agents…; it applies to a running agent at once.
• Model: if the agent offers a choice of models, the navigator shows a Model picker under the agent. The list is the agent’s own. It depends on the agent’s provider, sign-in and plan, and TeamCraft adds or checks nothing. The model switches between answers, not during one. The desktop app remembers the pick per agent and selects it again at the next start if the agent still offers it. Agents that offer no choice show no picker.
• Cancel in the toolbar stops the running turn. Stop in the navigator ends the agent process. Signing out stops it too.

What the agent can reach

• TeamCraft’s tools with your rights. The desktop app passes the server’s MCP endpoint (<server>/api/v1/mcp) to the agent when the session starts, with your desktop sign-in (the personal access token) as the Authorization header, and marks the connection with X-TeamCraft-Client: desktop-agent (so the server can say precisely why it refuses it when local agents are off). The agent can do in TeamCraft exactly what you can do through the MCP tools: read, and draft change orders. It cannot submit, approve or release. An agent without support for MCP over HTTP gets no TeamCraft tools; the navigator says so.
• The workspace folder. The agent runs in your workspace folder (its working directory). Through the desktop app it may only read text files there (fs/read_text_file, at most 4 MiB). Paths outside the folder are refused, also when a symbolic link points outside.
• No writing and no terminal through TeamCraft. The desktop app does not offer the ACP capabilities fs/write_text_file and terminal. Changes to CAD data should go through check-out and check-in, with versions, locks and an audit trail. An agent that edits files behind the PDM’s back would bypass that. A terminal would give the agent a shell through the desktop app.
• But it is your program. The agent process runs with your operating system rights. These limits apply to what it asks the desktop app to do. Its own built-in tools (editing files, running commands) are governed by the agent’s own permission requests, and the desktop app shows those to you. Answer them with care.

Your messages and the data the agent looks up go to the agent’s AI provider under the agent’s own terms. TeamCraft’s audit log shows the MCP tool calls as yours.

Protocol details

The desktop app speaks ACP version 1 (JSON-RPC 2.0, one message per line, at most 8 MiB per message) and calls initialize, session/new (with the workspace folder as cwd and TeamCraft as an http entry in mcpServers), session/prompt and session/cancel. For the model picker it reads the session’s configOptions (the select option of category model, set with session/set_config_option) or, from agents that only send that, the older unstable models field (set with session/set_model). It handles session/update (message and thought chunks, tool_call, tool_call_update, plan, config_option_update), session/request_permission and fs/read_text_file. It answers every other agent request with “method not found”. At most 8 file reads run at once and at most 16 permission requests wait for an answer; further ones are refused or answered with cancelled. Stop closes the agent’s input and ends the process, so an agent that npx or cmd started as a child process of its own ends too. If the agent asks for a sign-in first (auth_required), sign in once in a terminal with the agent’s own command and start it again. The code is desktop/src/acp.rs.

Which permission requests are answered without a prompt (desktop/src/autoallow.rs). At the start of a session the app asks the server for tools/list with your token and keeps the names marked annotations.readOnlyHint: true (a name listed twice is left out) for that session – nothing is hard-coded. A session/request_permission is answered with its allow_once option only if all of these hold:

• the session got TeamCraft’s MCP server from the app (registered as teamcraft; an agent without MCP over HTTP may have a teamcraft server of its own, so then everything asks), and the list loaded;
• the request names a tool of exactly that server, in one of the forms agents use: mcp__teamcraft__<tool> (Claude Code and its ACP adapter, in toolCall.title or toolCall._meta.claudeCode.toolName; also toolCall._meta.toolName), <tool> (teamcraft MCP Server) or teamcraft__<tool> (Gemini CLI). A bare get_item names no server and asks; Gemini CLI usually titles a call with its arguments, so its requests mostly still ask;
• every name in the request agrees – one that names another server or another tool makes it ask;
• the tool’s kind is other (or missing) both in the request and in the tool call the agent announced before, so mcp__teamcraft__get_item as the title of a terminal command or file edit asks;
• the tool is in the read-only list, and the request offers allow_once (allow_always is never chosen).

The app asks the agent’s question and trusts its answer about which tool runs, as with every permission prompt: the agent could call tools without asking at all. What a read-only tool returns is decided by the server.

Manual test tour

A 20-minute walk through every feature on a local server (docker compose up -d db && cargo run, then http://localhost:8080). Use two browsers (or a private window) for the two-person steps.

1. Accounts and project groups

1. Create the administrator on the login page (first start only).
2. Users → New user: erika (CAD editor) and rolf (CAD editor), vera (viewer).
3. Sign in as erika. Projects → New project group ROVER – erika is its manager. Add rolf as member. (The tour builds a rover with wheel hubs; any product works the same way – a pump, a gearbox, a conveyor, a machine.)
4. Account → Appearance (or the menu under your name): System follows the light or dark appearance of your operating system, Light and Dark stay fixed; the distribution skins (Arch, KDE, Ubuntu, …) are dark. The choice is remembered for the login page as well.

2. Items, check-out and check-in

1. Items → New item: choose hub.step and hub.stl as files – the name hub and the type part are filled in; change the name to Wheel hub, project group ROVER. The item is created with both files; revision A is in work and checked out to erika (lock badge).
2. Open 3D view for each file. The STEP model is tessellated on the server – try Export STL.
3. Vault → My check-outs: the item is listed; select it, Check in a changed hub.step with a comment. The upload shows a progress bar; try Cancel upload on a large file – nothing changes.
4. As rolf: the item is read-only while erika holds the lock; after the check-in rolf can Check out. Cancel check-out releases it at once.

3. Versions and rollback

1. On the revision page, open the version history of hub.step, download v1.
2. Restore v1: it becomes v3 – history is never rewritten.

4. Structure

1. Create an assembly Rover and add the hub to its BOM (find number 10, quantity 4). Open the BOM page; switch the revision rules.
2. Upload an assembly file that references hub.step (e.g. a STEP assembly): the references are listed and matched.
3. Pack and Go (ZIP) on the BOM page.

5. Change and release

1. As erika: Release via new change…, add rolf as reviewer, Submit.
2. As rolf: the bell shows the review request; Approve. The hub is released; dependents get Check needed.
3. Revise the released hub: revision B is in work and checked out.

6. Viewer, API, audit

1. As vera: everything is readable, nothing editable.
2. Account → API tokens: create one and call curl -H "Authorization: Bearer <token>" http://localhost:8080/api/v1/me.
3. As the administrator: Audit log lists every step of this tour.

7. Operations

curl -s localhost:8080/healthz → ok, /readyz → database and vault status, teamcraft vault check --verify-hashes.

Install with Docker

The quickest way to run TeamCraft on a Linux server: one script sets up the TeamCraft container and a PostgreSQL container with Docker Compose. Nothing is built on your machine – the image ghcr.io/rudalabs/teamcraft comes from GitHub’s container registry for linux/amd64 and linux/arm64.

TeamCraft has no release yet (version 0.x). Until there is one, the installer uses the development image edge, built every night from the main branch. Keep backups (see below).

Install

You need Docker Engine with the Compose v2 plugin (docker compose version).

curl -fsSL https://raw.githubusercontent.com/rudalabs/TeamCraft/main/deploy/install.sh | bash

The script asks for sudo where it needs it and then:

1. checks Docker and Compose (it never installs Docker on its own; with --install-docker it offers to install the distribution’s packages);

2. picks the version – the newest release, or edge while there is none;

3. writes the installation to /opt/teamcraft:

   File	Contents
   docker-compose.yml	the two services, replaced on every upgrade
   .env	TEAMCRAFT_VERSION and TEAMCRAFT_BIND for Compose
   teamcraft.env	the server configuration – created once, then yours (mode 600)
   secrets/db_password	the generated database password – never printed

4. pulls the images, starts them and waits until /readyz answers;

5. offers to create the first administrator on the command line.

To read the script first, download it and run it from the file – the same options work in both cases (… | bash -s -- --user):

curl -fsSLO https://raw.githubusercontent.com/rudalabs/TeamCraft/main/deploy/install.sh
less install.sh
bash install.sh --dry-run      # prints every step, changes nothing
bash install.sh

From a checkout, ./deploy/install.sh uses the compose file of the checkout.

The first administrator

The installer offers to create it right away and asks for the password. Later, or after an unattended installation:

cd /opt/teamcraft
sudo docker compose exec teamcraft teamcraft user create --username admin --role admin

The Create administrator form on the login page of a local installation (cargo run) is not offered here: inside the container the server listens on all interfaces, so it cannot tell whether the page is opened from the same computer. Alternatively set TEAMCRAFT_BOOTSTRAP_ADMIN_PASSWORD in teamcraft.env for the first start (used only while there are no accounts), or sign in with single sign-on.

Every other teamcraft command works the same way: sudo docker compose exec teamcraft teamcraft user list, … vault check.

Configuration

Edit teamcraft.env (every variable: Configuration) and apply it with sudo docker compose up -d. The database connection, the listen address inside the container and the vault directory are set in docker-compose.yml and take precedence.

The published port is TEAMCRAFT_BIND in .env. The default 127.0.0.1:8080 reaches only the server itself – put a reverse proxy in front (below), or publish the port to the network and tell TeamCraft its address, which every form is checked against:

sudo bash install.sh --bind 0.0.0.0:8080 --public-url http://plm.example.org:8080

Reverse proxy and TLS

For anything beyond a test, serve TeamCraft over HTTPS through a reverse proxy on the same host, keep the default 127.0.0.1:8080 binding, and set TEAMCRAFT_PUBLIC_URL=https://plm.example.org (that also turns on Secure cookies). With Caddy, which gets the certificate itself:

plm.example.org {
    reverse_proxy 127.0.0.1:8080
}

With nginx, allow large uploads (client_max_body_size 512m;, matching TEAMCRAFT_MAX_UPLOAD_MB) and pass Host and X-Forwarded-Proto. TeamCraft sends Strict-Transport-Security itself when TEAMCRAFT_PUBLIC_URL is https. The cross-site check accepts the Host and X-Forwarded-Host the proxy passes: let the proxy overwrite X-Forwarded-Host (never pass on the client’s), and note that a web form post without Origin and Referer is refused. Caddy sets X-Forwarded-Host itself; with nginx: proxy_set_header X-Forwarded-Host $host;.

Upgrade

Run the installer again – it downloads the compose file of the new version, pulls the image and restarts; configuration, password and data stay:

curl -fsSL https://raw.githubusercontent.com/rudalabs/TeamCraft/main/deploy/install.sh | bash
# or a specific version:  … | bash -s -- --version 0.3.0

Database migrations are applied on start. While TeamCraft is 0.x, read the release notes before an upgrade and take a backup first.

Backup and restore

The data lives in two Docker volumes: teamcraft-server_db (PostgreSQL) and teamcraft-server_vault (every uploaded file; vault/previews/ is a cache). Back up both together, plus the installation directory (it holds the database password). The image has no PostgreSQL client tools, so teamcraft backup (Operations) does not run inside the container; dump through the database container instead (sh -c: the dump is written as root, because /opt/teamcraft belongs to root):

cd /opt/teamcraft
sudo sh -c 'docker compose exec -T db pg_dump -U teamcraft -Fc teamcraft > teamcraft-db.dump'
sudo docker run --rm -v teamcraft-server_vault:/vault:ro -v "$PWD":/backup alpine \
  tar -czf /backup/teamcraft-vault.tar.gz -C /vault --exclude=./vault/previews .

Restore into a fresh installation (same or newer version):

cd /opt/teamcraft
sudo docker compose stop teamcraft
sudo docker compose exec -T db pg_restore -U teamcraft -d teamcraft --clean --if-exists --single-transaction < teamcraft-db.dump
sudo docker run --rm -v teamcraft-server_vault:/vault -v "$PWD":/backup alpine \
  tar -xzf /backup/teamcraft-vault.tar.gz -C /vault
sudo docker compose start teamcraft
sudo docker compose exec teamcraft teamcraft vault check

The vault is content-addressed and append-only, so incremental file backups of the volume directory (docker volume inspect teamcraft-server_vault) work well too.

Image tags

The image is built from the repository’s Dockerfile by GitHub Actions only (.github/workflows/release.yml): a small distroless runtime (glibc, CA certificates, time zones, no shell) that runs as an unprivileged user, with a HEALTHCHECK through teamcraft healthcheck. The compose file also makes its root file system read-only and drops all capabilities.

Uninstall

curl -fsSL https://raw.githubusercontent.com/rudalabs/TeamCraft/main/deploy/install.sh | bash -s -- --uninstall

This removes the containers and keeps the volumes and /opt/teamcraft, so running the installer again brings everything back. --uninstall --purge deletes the volumes and the directory as well, after a confirmation.

Troubleshooting

Configuration

TeamCraft is configured with environment variables; all are optional for a local test with the development database of docker-compose.yml. Every variable can also be read from a file by appending _FILE (TEAMCRAFT_OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc), which is how container secrets are passed. For local development TeamCraft also reads an optional, git-ignored secrets/.env file in the working directory.

Configuration files are read on start, in this order; a variable that is already set (in the environment or by an earlier file) is kept:

In the Docker installation the variables go into teamcraft.env; the image sets TEAMCRAFT_BIND_ADDR=0.0.0.0:8080 and TEAMCRAFT_VAULT_DIR=/var/lib/teamcraft/vault, and docker-compose.yml sets the database connection with the password from a Docker secret (TEAMCRAFT_DB_PASSWORD_FILE=/run/secrets/db_password).

Values are validated on start; an invalid value stops the program with a message naming the variable. A TEAMCRAFT_* variable that TeamCraft does not know (usually a typo) is ignored but logged as a warning with the nearest known name (unknown environment variable … is ignored; did you mean …?; <NAME>_FILE forms are checked by NAME). A test keeps this page and the variables read by src/config.rs in sync.

Server

The server (teamcraft serve) logs to standard output; the other commands (migrate, user, vault, backup, …) log to standard error, so that their output can be read by scripts.

Database (PostgreSQL 16+)

Start-up waits up to 20 s for the database, then stops with the reason. Migrations run automatically (teamcraft serve --no-migrate skips them).

Files

Chunked uploads (Large files) hold one chunk in memory and write it to uploads/ in the vault directory, so TEAMCRAFT_MAX_UPLOAD_MB can be raised for multi-gigabyte CAD or simulation files (e.g. 20480) without more memory; a single multipart request (small files, the web UI’s New item form) still has to fit this limit as a whole, and a reverse proxy in front must allow request bodies of one chunk (client_max_body_size ≥ TEAMCRAFT_UPLOAD_CHUNK_MB) – or of the largest multipart upload. Make sure the vault’s disk has room for the unfinished uploads too: each user may hold 16 of them for 24 hours. Storage quotas per user and for the whole vault are set with the CLI, see Storage quotas.

Malware scanning

With a scanner, every file is sent to clamd (INSTREAM) before it is moved into the vault – uploads, check-ins, chunked uploads, imports. Infected content is refused (400, the signature name in the message) and never stored; a chunked upload starts over. When the daemon cannot be reached, the upload is refused with 503 instead of stored unscanned. ClamAV is a separate service (e.g. the clamav/clamav image next to TeamCraft); raise its StreamMaxLength together with TEAMCRAFT_CLAMD_MAX_MB to scan large CAD files too.

Encrypted backups

See Backups. Losing the passphrase means losing the backup – keep it apart from the backups themselves.

Data retention

Files keep every version unless someone sets a file to keep only the latest version, so the defaults change nothing for existing installations. See Data retention.

3D preview limits

The 3D preview converts a file in a separate teamcraft preview-mesh process with a time limit (at most two at a time). A file above the size cap of its kind is never opened: no conversion starts, the page says it is too large for a 3D preview, and the refusal is cached (raising the cap takes effect at once). The process also runs with a memory limit; a file that needs more fails with a message instead of taking the host down. Large simulation results are stored as they are, never parsed fully – see Simulations.

The same process limits protect the text extraction of PDF and HTML reports (teamcraft text-extract: at most 32 MB per PDF and 100 pages, the first 16 MB of an HTML file, 60 s, the memory limit below).

The memory limit (RLIMIT_AS) is enforced on Linux; on macOS the system may ignore it, and on Windows it is not enforced (the size caps and the time limit still are). Every variable also exists as NAME_FILE.

Sign-in

Sign-off of review decisions. With TEAMCRAFT_APPROVAL_REAUTH a reviewer confirms a decision on the change page with the account password, or – for single sign-on accounts – with Sign in again, which sends them to the identity provider with prompt=login and max_age=0; the provider’s auth_time must be at most five minutes old, and the confirmation counts for 10 minutes. API tokens are not asked: reviewing needs the approve token scope (write tokens get 403). Every decision records how it was signed off (session, password, sso or token) and an optional stated meaning (“approved as design owner”), shown on the change page, in GET /api/v1/changes/{number} and kept with earlier review rounds. A wrong password counts like a failed sign-in (user.password_failed, throttled); a fresh SSO sign-in writes user.reauthenticate.

Failed password sign-ins are counted per username and per client address for 15 minutes from the first failure; when a counter is full the sign-in page answers 429 Too Many Requests with Retry-After – even for the right password – until the 15 minutes have passed. A successful sign-in clears the username’s counter. The counters live in the memory of each server process (a restart clears them). Behind a reverse proxy on the same host or an internal network, the client address is the last X-Forwarded-For entry, the one the proxy added; a client that talks to the server directly is counted by its own address. Sign-in, failed sign-in and sign-out are in the audit log (user.sign_in, user.sign_in_failed, user.sign_out).

Notifications (optional)

Mattermost: a bot account for direct messages

Notifications reach Mattermost only as a direct message to the person, never in a channel. TeamCraft signs in as a bot account and uses the REST API: it looks the user up by name (GET /api/v4/users/username/…, cached for ten minutes), opens the direct channel bot ↔ user (POST /api/v4/channels/direct) and posts (POST /api/v4/posts). In Mattermost the messages come from the bot (shown with the BOT tag), and every user has one conversation with it. A direct message can only be read by its recipient, so it carries the full title and text, also for restricted project groups – unless the group switched notification content off, then only a generic text and the link are sent.

Set up the bot once:

1. In Mattermost: System Console → Integrations → Integration Management: Enable Bot Account Creation must be on.
2. Integrations → Bot Accounts → Add Bot Account: username e.g. teamcraft, display name TeamCraft. A bot needs no role beyond Member and no channel or team membership: it only has to read user profiles and open direct messages, which every account may do. Do not give it a system role.
3. Create a token for the bot (Create New Token), keep it in a file that only the server reads, and set TEAMCRAFT_MATTERMOST_URL and TEAMCRAFT_MATTERMOST_BOT_TOKEN_FILE. Both are required together.
4. Check it from Account → Notifications: switch Mattermost on, save and press Send a test (the test notification is delivered like every other).

Users enter their Mattermost username on their account page (empty = their TeamCraft login). If it is unknown or the Mattermost account is deactivated, the chat delivery of that notification is marked failed at once, with the reason (for example Mattermost user “xy” not found – check your Mattermost username) shown under Notifications; it is never posted into a channel instead. The bell and the e-mail are not affected. A rejected token (HTTP 401), a missing permission or a server error is retried like any delivery (five attempts with the usual pause) and then marked failed, with the reason.

The server URL is set by the administrator only. The client follows no redirects (the token must not travel to another host) and ignores proxy variables. The error webhook MATTERMOST_ERROR_WEBHOOK stays an ordinary channel webhook: it is for administrators, not personal.

Deprecated webhook mode. With only TEAMCRAFT_MATTERMOST_WEBHOOK set, notifications still go out as before (a mention in the webhook’s channel, or with TEAMCRAFT_MATTERMOST_DIRECT=true a direct message that appears to come from the person who created the webhook), the server logs a deprecation warning at start-up and the account page says so. Everybody in the channel reads the mentions, which is why restricted groups show only a generic text there. See Upgrading.

The change request digest is an e-mail per project group to its CAD editors and admins with the requests raised since the previous digest that are still New, and how many older ones still wait for triage. Nothing is sent when no new request came in. Every user can mute it on the account page (E-mail digest of new change requests …). The server remembers per user and group up to when the digests reached (table request_digests), so a restart or a second server never sends a period twice; the e-mail goes through the same outbox, retries and access checks as every notification.

Event webhooks

Administrators register outgoing webhooks on the web page Webhooks or through the API (Event webhooks). These variables limit where they may send to:

By default webhooks reach public addresses only. An on-premises ERP or CI server is internal, so list it: TEAMCRAFT_WEBHOOK_ALLOWED_HOSTS=erp.corp.example,ci.corp.example.

Assistant (optional)

The built-in assistant (Ask TeamCraft) is off until an API key is configured, or, for a local model server, until the provider openai-compatible and its base URL are set. While it is off the buttons are hidden and /assistant and POST /api/v1/assistant answer 404. Every variable also works as NAME_FILE (the file’s contents).

With only TEAMCRAFT_ANTHROPIC_API_KEY (and optionally the model and the steps) everything works as it did before these variables existed. The startup log shows assistant=<provider>:<model>@<host>, never the key.

Where the questions go, and what is done about the key:

• The base URL comes only from this configuration, never from users, the admin pages or anything a model or tool returns. Internal hosts are allowed on purpose, so a model server inside the network works (the webhook protection against internal addresses is for URLs that users enter and is not used here).
• Redirects are not followed. An answer that redirects is an error, so the key is never sent to a second host. A user name or password in the URL, a query and a non-http(s) scheme are rejected at startup.
• A warning is logged at startup when a key would be sent over plain http to a host that is not this computer (localhost, 127.0.0.0/8, ::1). Use https for anything else.
• The server honours HTTPS_PROXY / NO_PROXY. A firewall with an egress allow-list must let the server reach the API host.

Check the setup with teamcraft assistant check (run it with the same environment as the server; it needs no database). It sends one small request with one tool and reports whether the server is reachable, the key is accepted, the model exists, the model calls the tool and the server reports token counts. Many local models are served without tool support: this is how you find out before your users do. A server that reports no token counts still works, but the token limit of a run cannot count its calls (the step and time limits still apply, and the audit record says usage_reported: false). The check never prints the key.

Fixed limits per question: 800 000 tokens in total. Each question is recorded in the audit log (assistant.run: user, quick action, question length, provider, model, tools used, token counts, usage_reported, the page kind and identifiers, whether it was asked in the conversation and the outcome – cancelled when the client closed the connection before the answer – never the question or the answer).

Local agents

The desktop app can run an AI agent on the user’s own computer (its Agent view, see ACP agents), and users can connect other MCP clients (an assistant set up by hand, the teamcraft mcp bridge) with a personal access token. Such agents send the user’s questions and the TeamCraft data they look up to the agent’s own AI provider, under the user’s own account and terms.

Company AI instead of shadow AI. For data-loss prevention an organisation can turn local agents off and offer its own AI centrally: the provider configured under Assistant – Anthropic, OpenAI or Azure OpenAI with the company’s contract and key, or a model server inside the network (Ollama, vLLM …). Users then work with Ask TeamCraft in the web UI and with the Agent view of the desktop app, which runs on that assistant (Company AI); the key stays on the server and never reaches a client. Every question runs with the user’s rights, is recorded in the audit log (assistant.run, without the question or the answer) and is bounded by the assistant’s limits (steps, tokens, time, questions at the same time). Admin → AI (/admin/ai) shows the setting, the MCP endpoint’s state and the configured provider, model, host and limits – never the key, only whether one is set.

Like every variable it also works as TEAMCRAFT_LOCAL_AGENTS_FILE. The startup log shows local_agents=allowed|off. Changing it needs a restart of the server; the desktop app picks it up at its next sign-in or window reload and checks it again before every agent start.

What off does:

• POST /api/v1/mcp answers every call with 403 and a JSON-RPC error naming this setting, whoever sends it and with whichever token (administrators included): the desktop app’s agent, the teamcraft mcp bridge, an agent the user set up by hand, an older desktop app. Without a valid token the answer stays 401. The built-in assistant is not affected: it calls the same tools inside the server, not over this endpoint. Refusals are not written to the audit log (they change nothing).
• GET /api/v1/me reports capabilities.local_agents: false and capabilities.mcp: false. The desktop app then ends an agent that is still running and refuses to start one (in the app’s Rust code, not only in the user interface). Its Agent view – the app’s one place for AI – runs on the company AI instead: with an assistant configured (TEAMCRAFT_ASSISTANT_*), questions go to the server’s assistant automatically, with no local option shown (the key never reaches the app); without one the view says that AI is switched off by the administrator. Settings → Agents shows the same explanation. A desktop app older than this setting still offers its local agent, but the agent gets no TeamCraft tools: the endpoint refuses it.
• The desktop app marks the MCP connection it hands to a local agent with the header X-TeamCraft-Client: desktop-agent. It only picks the wording of the refusal; leaving it out does not get a call through.

What off does not do – it is cooperative enforcement, not a barrier against a determined user: it does not close the REST API (/api/v1/…) to a user’s own personal access token. A program the user writes, or another MCP client or agent that wraps the REST API with that token, still reads and writes with that user’s rights and can hand what it reads to an AI provider of the user’s choice. Nor can a server stop anyone from copying what they see into another tool. The complement is scoped personal access tokens: give an agent a read_only or mcp_only token (see API reference). A written usage policy, the token list of each user (Account → API tokens, revocable by administrators) and the audit log (writes are recorded under the user’s name) are the controls for the rest.

Tests

MCP stdio bridge (client side)

Only teamcraft mcp, the bridge for AI assistants that run on a user’s machine, reads these. The server does not (see MCP server).

Users, roles and single sign-on

Local accounts

Administrators create accounts under Users or on the command line (teamcraft user create --username erika --role editor --project PUMP). Passwords are hashed with Argon2id; sessions and API tokens are stored as SHA-256 hashes only.

A release needs two people. Nobody reviews their own change order (four-eyes principle, with no administrator override), so a server with a single account – a test installation, or the first administrator alone – can create changes but never release them. Create at least one more CAD editor (teamcraft user create --username reviewer --role editor) before trying a release; see Separation of duties.

Roles

A project group can be restricted to its members: everybody else – viewers and CAD editors who are not members – gets “not found” for the group and everything in it. Viewers who are members read it. See Read permissions and restricted groups for the full rules, what outsiders see of links into a restricted group, the delay of memberships synchronised from the identity provider and what stays visible on a shared instance.

Single sign-on (OpenID Connect)

Any OIDC provider with the authorization-code flow works (Authentik, Keycloak, Entra ID, Google, …). Register the redirect URI <TEAMCRAFT_PUBLIC_URL>/auth/oidc/callback and set:

TEAMCRAFT_OIDC_TOKEN_IDLE_DAYS (1 to 3650) caps the API and desktop tokens that single sign-on users create from then on: a token without an expiry, or with a longer one, expires after that many days without use instead (every use renews it); a shorter fixed expiry stays. A leaver who is removed only at the identity provider then loses their tokens after that many idle days. Existing tokens keep their lifetime. The API tokens card of My account tells SSO users about the limit.

Back-channel logout. Register <TEAMCRAFT_PUBLIC_URL>/auth/oidc/backchannel-logout as the client’s back-channel logout URI (OpenID Connect Back-Channel Logout 1.0). When the provider ends a user’s session – or the user is removed there – it posts a signed logout token; TeamCraft checks it against the provider’s published keys (jwks_uri, RS256 or ES256), ends all of that user’s browser sessions, audits it (user.idp_logout) and notes the time, which the report of SSO users without sign-in shows (see Leavers removed only at the identity provider). The token must name the user (sub); tokens with only a session id (sid) are refused, and so is a token more than five minutes old. A refused token is answered with 400 and logged; an unknown subject with 200. Keys the cache does not know yet are fetched again (key rotation), at most once a minute. API and desktop tokens are not touched, and the account stays active – deactivate the user (Offboard and deactivate) for that.

Accounts are created at the first sign-in; the role follows the groups at every sign-in. A project group bound to an IdP group (Projects → group → Edit, administrators) gets its members synchronised at every sign-in; manually added members stay. A synchronised membership stays one when its holder is made a manager (Demote lowers it again), and it cannot be removed in TeamCraft while the user is active (it would return at the next sign-in): remove the user from the IdP group, unlink the group or deactivate the user instead. A deactivated user’s synchronised membership can be removed (see When someone leaves).

Item owners and handing over a leaving user’s work

Every item has an owner, the person responsible for it. It starts as the creator and is shown in the master data of the item page. The managers of the item’s project group and administrators change it (Change next to the owner); the new owner must be an active CAD editor or administrator who may read the item. Every change is audited (item.owner).

When somebody leaves, an administrator opens the user and uses Hand over work. In one transaction TeamCraft moves to the chosen person:

A message after the run gives the counts and the first objects that stayed with the old user and why (numbers of groups the administrator may not read are shown as “restricted item”): the receiver cannot read the object (restricted project group), already reviews the change order, or may not review it under the four-eyes principle (author, preparer or someone who changed the revisions). Every moved object gets its own audit entry (item.owner, change.handover, change_request.handover, change.review_handover) plus one user.handover entry with the counts. Decisions already made, released changes and closed requests keep the original names. One run moves at most 1000 objects of each kind; the message says when to run it again.

When someone leaves

Teams with a high turnover (student teams, early-stage startups) lose members every season. Deactivating a user ends their sessions and disables their API and desktop tokens; their check-outs, change orders, reviews and memberships stay.

See what they hold first. Users → user → Everything … still holds (/users/{id}/holdings, GET /api/v1/users/{id}/holdings, or teamcraft user holdings --username lena on the server) lists in one place the user’s check-outs with their age, the change orders they wrote that are still open (draft, in review, rejected), the reviews that wait for them, the open change requests assigned to and raised by them, the items they own, their memberships with the source – flagging the groups in which they are the only active manager – and their API tokens with last use and expiry. The report is read-only and filtered by the rights of whoever reads it, not the leaver’s: a check-out in a group the leaver was removed from is still listed. Administrators see every group they can read; for a group whose need-to-know policy hides its content from them the report gives only the number of check-outs. A manager of a project group opens the same report from the group’s member list (holds…) and sees only what lies in the groups they manage, without the tokens. Each list shows at most 200 entries next to the full count.

Offboard in one step. Users → user → Offboard and deactivate (or POST /api/v1/users/{id}/offboard, or teamcraft user deactivate --username lena on the server) deactivates the user and, in the same step:

• hands the work over to a successor you choose – items, draft and rejected change orders, open change requests and pending reviews (as Hand over work above) – and their manager roles: the successor becomes a manager of every group the leaver managed (added as a member where needed), the leaver stops being one (project.manager_handover per group);
• revokes the API tokens (ticked by default): they are deleted, so activating the account again does not bring old tokens back (token.revoke_all);
• releases the check-outs (ticked when there are any), each in its own transaction and audited like Release all.

Deactivation, hand-over and token revocation run in one transaction; the check-outs are released afterwards and the message reports both. If the user is the only active manager of a group and no successor is named, the step is refused until you confirm that the group is left without an active manager (administrators can still manage it). An administrator cannot offboard themselves, and the last active administrator is kept. Every run is audited (user.offboard, with the choices). On the command line the options are --hand-over-to USERNAME, --release-checkouts, --revoke-tokens and --confirm-no-manager; the command exits with 2 when a check-out could not be released and is recorded as system in the audit log. The plain Active checkbox of the profile still deactivates without any of these steps.

Or work through these steps by hand, in this order:

1. Keep at least two active administrators. TeamCraft refuses to deactivate or demote the last one. If nobody with the admin role is left, whoever has a shell on the server creates one: teamcraft user create --username rescue --role admin (break glass).
2. Before they go, the leaver uses Check in all on the dashboard and checks in the local changes of their desktop working folder. Work that was never checked in exists only on their computer. The desktop app lists check-outs with local changes before Check in all and before signing out and offers to check them in; Park… puts work in progress on the server without giving up the check-out, so it survives a lost laptop. After a forced release the former holder’s Workspace tab says who released it; their local files stay and need a new check-out.
3. Hand over their work (administrators): Users → user → Hand over work moves item ownerships, draft and rejected change orders, open change requests and pending reviews (see above).
4. Release the remaining check-outs. Administrators use Users → user → Check-outs → Release all. The managers of a project group use Release N check-outs in the group’s member list – for members who are deactivated and, under Former members still holding check-outs, for people who are no longer members. Each release is audited (revision.checkout_forced_release); one refused release does not stop the others. A lock held by somebody who is still an active member (on leave, or simply gone quiet) a manager releases one revision at a time with Release with reason on the revision page; the reason is audited and the holder is told it. Revisions of a need-to-know group that hides itself from administrators (admin_read = none) are left out for administrators: a manager of that group releases them.
5. Pending reviews: a change order cannot be submitted while one of its reviewers is deactivated – remove them and add someone else. For a change already in review the author (or an administrator) replaces the pending reviewer (Substitute for), which keeps the other decisions.
6. Change orders of a deactivated author: besides administrators, a manager of every project group the change touches may withdraw, reopen or cancel it, or take it over (Take over on the change page; audited as change.handover). Whoever takes it over is its author and can no longer review it (four-eyes principle).
7. Group managers: Demote in the member list lowers a manager to a plain member, also for memberships synchronised from the identity provider. At least one active manager must remain (only administrators may demote or remove the last one); deactivated managers do not count. Administrators see the groups left without an active manager – or whose managers have neither signed in nor used a token for 90 days – under Groups without an active manager on Project groups (GET /api/v1/projects/manager-gaps); the hourly housekeeping notifies them once per group when that happens.
8. Revoke their tokens on the user page.
9. Deactivate the user. For SSO users both are needed: remove them at the identity provider and deactivate them in TeamCraft (SSO users without sign-in on Users finds those who were only removed at the provider, see below). A synchronised membership of a deactivated user can then be removed by the group’s managers (SSO refuses deactivated users, so it cannot come back); an active user’s synchronised membership still can only end at the identity provider.

Leavers removed only at the identity provider

Removing someone at the identity provider does not deactivate them in TeamCraft: their account, memberships, check-outs and tokens stay until an administrator offboards them. Three things help when the IdP is where people leave:

• The report. Users lists, under SSO users without sign-in, every active single sign-on user who has neither signed in nor used an API or desktop token for 90 days and still holds memberships, tokens or check-outs, with the last sign-in, the last activity and when the IdP last logged them out. Each row links to the user (Offboard and deactivate) and to what they hold. Administrators only; shown when SSO is configured.
• Tokens that expire on their own. With TEAMCRAFT_OIDC_TOKEN_IDLE_DAYS (for example 30), new API and desktop tokens of SSO users stop working after that many days without use.
• Back-channel logout. Registered at the provider (see Single sign-on), it ends the leaver’s browser sessions the moment the provider logs them out or removes them, instead of after TEAMCRAFT_SESSION_TTL_HOURS.

Automatic deactivation through SCIM is not supported; see the research note Deprovisioning through the identity provider.

The end of a season

When many members leave at once – the end of a term in a student team – the managers of a group use Season handover (link above the member list, /projects/{id}/season) instead of going person by person. The page lists every member with their last activity (sign-in or use of an API or desktop token), check-outs in the group, manager flag and member until date. Tick members inactive since a date ticks the deactivated and the inactive ones and those whose member until has passed; adjust the ticks, then run:

1. the new lead becomes a manager;
2. the ticked members’ check-outs are released – with a reason (10 to 500 characters), which each holder is told and which is audited; without a reason only the locks of deactivated and former members are released;
3. member until is set (or cleared) for the ticked members – only a flag, nobody is removed automatically;
4. the ticked members are removed (an IdP-synchronised membership only once its user is deactivated);
5. the ticked managers are demoted – last, so a manager who steps down can still run the steps above; at least one active manager must remain unless an administrator runs it.

Every step goes through the same checks as the single action and is audited on its own; a refused step is listed in the result and does not stop the others.

Read permissions and restricted project groups

Every item belongs to a project group (or to none). A group is either

• internal – the default: every signed-in user reads it, its members edit it; or
• restricted – only its members (of any role, viewers included) and administrators see the group and anything in it: items, revisions, files and their versions, previews, BOMs, references, simulations, change orders and change requests about them. For everybody else it does not exist: they get exactly the “not found” a missing object gives.

The background and the alternatives that were considered are in the research note Read permissions for project groups.

Effective rights

Items without a group are readable by everyone and editable by every CAD editor (unchanged). A read-only member of a restricted group is a member with the global viewer role; there is no per-group read/write level.

Restricting a group

Project groups → the group → Details → Visibility: Restrict to members or Open to all users. Managers of the group and administrators may do this; the change is recorded in the audit log (project.visibility). A group can also start restricted (checkbox when it is created, or "visibility": "restricted" in POST /api/v1/projects). Add viewers as members to give read-only access. Linking a group to an identity-provider group (oidc_group) stays with administrators, because it grants read access.

Need to know: administrator access

By default an administrator reads every restricted group. A restricted group can limit that (Project groups → the group → Need to know, managers and administrators; PUT /api/v1/projects/{code}/policy {"admin_read": "implicit" | "with_reason" | "none"}):

• implicit – today’s behaviour, the default (also when no policy was ever set);
• with a reason – an administrator who is not a member sees the group as “not found” until they open an elevation with a written reason (10 to 1000 characters; POST /api/v1/projects/{code}/elevations, or the form on the group page). It lasts 60 minutes, can be ended early (DELETE …/elevations) and is audited (project.elevate, with the reason). The group’s managers get a notification, and the group page lists every elevation with administrator, reason and time;
• none – administrators still manage the group (members, policy, the settings on the group page) but read nothing in it. An administrator cannot add themselves as a member or make themselves a manager: a manager of the group does that. There is no elevation under none.

Every change of the policy is audited (project.policy, with the previous value) and notifies the other managers. The policy applies to restricted groups only and needs at least one member who is a manager, so the group can be recovered; opening the group to all users makes the policy inert. While a policy is in force, an administrator who is no manager member can still add or remove other members, tighten the policy and rename the group, but cannot loosen the policy, open the group to all users, link another identity-provider group, add themselves or become a manager (403): those would undo the policy in one call. What an administrator can still do is limited by design: add another user (a manager sees it in the audit log), see that the group exists (code and name), and change operator-level things (database, backups, the command line) outside the application. A group linked to an identity-provider group before the policy was set keeps that link, so an administrator in that IdP group is a member. Webhooks cannot be scoped to, or redirected for, a hidden group; their deliveries are not shown. The elevation history keeps the username when an account is deleted; deleting the group deletes its history (the audit log keeps the records). The rule is part of the actor’s hidden groups (access::hidden_of_user), so every guard, the audit feed, change orders, notifications and the assistant honour it without a check of their own. This is step 1 of #151; the conditions on membership (step 2), the interface switches and the read log (steps 3 and 4) and the access review (step 5) follow below.

Conditions on membership (need to know, step 2)

Membership can be made not enough: Need to know: conditions on membership on the group page (managers and administrators; PUT /api/v1/projects/{code}/policy with the fields below) adds conditions every reader must meet as well. A reader who does not meet them is treated as a non-member – the group, its items, files and changes answer “not found” – and that holds for administrators too (they still manage the group). Nothing is set by default.

• Required claims ("required_claims": [{"claim": "site", "values": ["main-office", "partner-workshop"]}, {"claim": "nda", "values": ["true"]}]; on the page one per line, site = main-office, partner-workshop): every condition must hold, each with one of its values, in the claims of the user’s last single sign-on (ID token and userinfo; compared without case; a list claim such as groups needs one of its entries). A change at the identity provider applies at the next sign-in. TeamCraft keeps only the claims that some group’s conditions name (users.idp_claims), so a user signs in again after a new claim condition is set. Local accounts have no claims and never meet a claim condition.
• Allowed networks ("allowed_networks": ["10.20.0.0/16", "2001:db8::/32"]): the client address must be in one of the ranges – the same address as the sign-in throttle (the peer, or the entry the reverse proxy added to X-Forwarded-For; see Reverse proxy and TLS). A request whose address is unknown is outside.
• Maximum sign-in age ("max_signin_age_hours": 12, 0 removes it): the group is visible only for so many hours after signing in – the start of the web session, and for tokens, the desktop app and notifications the user’s last sign-in. A person removed at the identity provider (or from the group’s IdP group) therefore loses the group at the latest then, even with a session that is still running (F7 in the threat model) – or at once, when the provider sends a back-channel logout.

Claims and the sign-in age are part of the SQL that builds a user’s hidden groups (access::hidden_of_user), so they apply to every channel, to change orders and to notification recipients; the network and the session’s own age are checked per request by the sign-in extractors and again at every step of an assistant run. A member refused by a condition is audited once per session or token (project.access_refused, with the reason and the address). The access review shows the conditions and, per member, whether they met them at their last sign-in; the evidence CSV carries both.

Setting conditions that would hide the group from yourself (your address outside the ranges, a claim your last sign-in did not have, a sign-in older than the age) is refused (409), so a manager does not lock the group away by mistake. Adding a condition, a narrower range, fewer accepted values or a shorter age is tightening, open to managers and administrators; anything else is loosening, for the managers while administrators are limited by the administrator policy. Every change is audited (project.conditions, old and new) and tells the other managers.

Interface switches and the read log (need to know, steps 3 and 4)

A restricted group can also close channels through which its data could leave the web UI, and can log who reads it (Project groups → the group → Need to know: interfaces and read log, managers and administrators; PUT /api/v1/projects/{code}/policy). Everything is allowed and nothing is logged by default; the switches build on a restricted group and are inert when the group is opened.

{"interfaces": {"mcp": false, "webhooks": false}, "read_log": true, "log_retention_days": 365} – every field is optional. Switching an interface off or the log on is open to managers and administrators; allowing an interface again, switching the log off or changing the retention is, while administrators are limited by the administrator policy above, for the managers (like loosening that policy). Every change is audited (project.interfaces, old and new values) and notifies the other managers. The in-app notification list and the notification e-mails of other groups are not affected by notification_content.

Read and download log. With read_log on, the group writes access_log entries (separate from the audit log): who (user name kept as text), when, the channel, the kind, the object (number or file name, kept as text), what read it (the tool, for tool reads) and the client address (with the same reverse-proxy rule as the sign-in throttle).

Kinds: view (an item or revision page, the same data over the API, or a read tool), download (a file or file version), package (Pack and Go), export (a BOM CSV or Excel file), workset (a desktop Get). A tool read is one view of the item the tool was asked for, with the tool name as its detail (read_file_text: spec.txt names the file); searches, lists, change orders, write tools and failed tools log nothing, and the assistant’s own comparison calls (the taint check) are not logged. Repeated reads of the same object by the same user through the same channel within five minutes are one entry, so a resumed or ranged download is logged once. A read that cannot be logged does not happen (a tool answers with an error). Groups that do not log write nothing. A Pack and Go, BOM export or desktop Get writes one entry for every logging group inside the structure, not only for the root item’s group; a refused one writes nothing. The managers and administrators read the log, but only while they may read the group (an administrator shut out by admin_read gets “not found”; the labels are item content). The group page shows the newest 50 entries; The whole log, with filters (/projects/{id}/access-log) filters by user, kind, channel, object (part of the number, file name or tool), and a date range, 100 entries a page. The REST API pages the same way: GET /api/v1/projects/{code}/access-log?user=&kind=&channel=&object=&since=&until=&limit= answers {"entries": […], "next": id}; pass next as before= for the following page (null on the last). Times are RFC 3339 or YYYY-MM-DD (a date until includes that day). Not logged: thumbnails and 3D previews.

Retention and purge. log_retention_days (1 to 36500, empty = keep) is applied by teamcraft access-log purge (run it from cron or a timer): without options each group’s own retention, --project CODE limits it to one group, --older-than-days N deletes everything older than that instead. Every run is audited (access_log.purge, with the count). The database backup contains the log.

Access review

Managers of a restricted group and administrators open Access review on the group page (/projects/{id}/access-review). It lists every member with the account role, the role in the group, the source (added by hand or synchronised from the identity provider), whether the account is active, the last sign-in (flagged when there was none for 90 days) and the date the membership began, then the administrator policy (with the number of active administrators who are not members) and the administrator elevations with their reasons. I reviewed the access confirms the review with an optional note: the confirmation is dated, audited (project.access_review), tells the other managers and stores the member list as it was, so the question “who had access at the time” is answered later (GET /api/v1/projects/{code}/access-review/{id}). The evidence report is a CSV (one row per member, elevation and confirmed review, formula-safe) or the same data as JSON (GET /api/v1/projects/{code}/access-review, with ?format=csv for the CSV). The page is for restricted groups only; elevations are listed up to the newest 100 and reviews up to the newest 50 (the audit log keeps all).

Review schedule. Review the access every (days) (under Interfaces and read log, {"review_interval_days": 90}, 1 to 3650, 0 removes it) makes the review periodic: the group is review due when no review was confirmed within the interval (a group never reviewed is due at once). The flag shows on the group list (for the group’s managers and administrators), on the group page and on the review page, which also names the next due date; the report and the CSV carry the schedule. The hourly housekeeping reminds the group’s managers (an access_alert notification, which cannot be muted; the active administrators when the group has no manager) once when the review becomes due and again after each further interval without one; every reminder is audited (project.review_reminder). A shorter interval is tightening, a longer one or none is loosening (managers only while administrators are limited by the policy).

Moving an item out of a restricted group, or copying it with Save As into another group, needs a manager of the source group or an administrator – both declassify the item.

Review policy per project group

By default every reviewer of a change order must approve. A manager of a project group (or an administrator) can set a policy on the group page (Review policy) or with PUT /api/v1/projects/{code}/review-policy ({"min_approvals": 2, "required_reviewers": ["carl"], "role_group": "QA", "obsolete_requires_change": false}; GET shows it to anybody who sees the group):

• Minimum approvals – this many approvals release the change; empty means all reviewers. A single rejection always rejects the change.
• Required reviewers – people who must be reviewers of every change that touches the group and approve it.
• Role group – another project group (e.g. QA); at least one approval must come from one of its members.

A change that touches several groups must meet the policy of each: the strictest minimum applies (a group without a value wants all reviewers), the required people and role groups add up. submit refuses a change that cannot meet them (409, naming what is missing: too few reviewers, a required person who is not a reviewer, no reviewer from the role group; a required person who may not review it, e.g. its author, gets a message of its own); the outcome of the review uses the same policy when a reviewer decides, so reviewers who have not decided yet stay pending once the change is released. The policy is read at decision time, not frozen at submit, but only the parts the assigned reviewers can still meet count (reviewers change in Draft only), so a policy edit after submit cannot strand a change in review. Deactivated people and people below the editor role do not count. Items without a project group count like a group without a policy: all reviewers must approve. A role group the reader cannot see is never named: the policy shows it as hidden and the submit message says “a required role group”. Changes are audited (project.review_policy, with the previous values). Step 2 of #152.

Obsolete and supersede only through a change order

Obsoleting a released revision is final and flags its dependents, and a supersession tells designers not to use an item any more. By default one CAD editor of the group can do both at once. The same form (Review policy on the group page) has a checkbox, obsolete_requires_change in the API (PUT /api/v1/projects/{code}/review-policy; omitted: unchanged, default off), that moves both through review:

• With the setting on, Mark obsolete and Supersede on items of the group answer 409 for everybody, administrators included. Other groups are not affected.
• A change order can carry an obsolete or supersede line next to its release lines (change page, On release; POST /api/v1/changes/{number}/items with {"item": …, "action": "obsolete"} or {"item": …, "action": "supersede", "successor": "PRT-000012"}; the revision defaults to the item’s latest). It needs a released revision that is in no other open change; a supersede line needs a visible successor item, not the item itself and no circle (400/409). The lines are allowed in every group, the setting only forbids the direct way.
• The policy of the group (minimum approvals, required reviewers, role group) applies to the change; nothing happens before the last approval. Then, in the same transaction as the release, each revision becomes obsolete (impacts on dependents, revision.obsoleted webhook and notification as for a direct obsolete) and a supersede line also records superseded by. If a line cannot be applied any more (the revision was obsoleted in the meantime, the supersession would close a circle) the approval fails with 409 and the whole release stays undone. Rejecting or withdrawing the change changes nothing on the released revisions.
• Supersede notifies the watchers of the superseded item, whether declared directly (with the setting off) or through a change order. Watchers who may not see the successor get the text without its number; the change page shows such a successor as restricted.

Step 3 of #152.

Requesters do not decide, concessions are confirmed

Two more checkboxes of the same form, both off by default (requester_cannot_decide and concessions_need_review in PUT /api/v1/projects/{code}/review-policy; omitted: unchanged):

• Requesters do not decide their own change requests. The person who raised a change request on items of the group cannot accept, reject or defer it (403, administrators included); another CAD editor of the group does. The request page and GET /api/v1/change-requests/{number} show can.decide = false for them.
• A reviewer confirms each “use as is” deviation. For an as-built revision of the group in a change order, every deviation with the disposition use as is is a concession that a reviewer of that change confirms on its own (Confirm in the deviation table, POST /api/v1/as-built-deviations/{id}/confirm) before any approval counts – approving earlier answers 409 and names the deviations. The person who recorded the deviation cannot confirm it (four-eyes). Changing a deviation clears its confirmation, and Revise copies deviations unconfirmed. The audit log records as_built.concession_confirm.

Step 9 of #152.

What outsiders see of links

A visible item can point to a restricted one, and the other way round:

Change orders and change requests

They have no group of their own. A change order is visible to administrators, its author, its reviewers and to everybody who can see every affected item (a draft without items: author, reviewers, admins). A change request is visible to administrators, the requester, the assignee and to everybody who can see every affected item (a request without items: everybody). Inside a visible change or request, rows of items the reader cannot see are placeholders.

Reviewers and assignees must be able to see every affected item; TeamCraft refuses others – also when an item is added later to a change with reviewers or to a request with an assignee. Submitting, reviewing and reopening a change needs the same – an author or reviewer who lost membership can still withdraw or cancel, but not approve blind. Adding a reviewer, assigning a request and the reviewer suggestions need it as well: whether somebody can see a hidden item would tell who belongs to its group, so an author who cannot see every item gets no suggestions and cannot add reviewers. A change cannot be submitted while one of its reviewers is deactivated.

Only the author of a change order and administrators edit, submit, withdraw, reopen or cancel it. When the author is deactivated, a manager of every project group the change touches may also withdraw, reopen or cancel it, or take it over (it becomes theirs; audited as change.handover). A change without items, or with an item outside any group, has no such manager.

Notifications, e-mail, chat, webhooks, assistant

• Notifications are created only for recipients who may read their subject, evaluated per recipient. A text that also names other items or a change order (the revisions of a change, the change that released an item or implemented a request) is replaced by a shorter text without them for recipients who may not see all of them.
• Notifications are checked again when they are read: after a group was restricted or a membership removed, the older notifications about it disappear from the list and the unread count, and pending e-mails and chat posts about it are not sent (marked skipped). They come back with the access. Pending e-mails and chat posts to a user deactivated since are not sent either. The groups of the items a notification names are stored with it (migration 0026), so it stays hidden from non-members after such an item is deleted.
• With the deprecated webhook mode (TEAMCRAFT_MATTERMOST_DIRECT=false, posts in a shared channel), notifications about restricted groups show only “new TeamCraft notification” and the link – decided when the post is sent, so a group restricted after the notification was queued counts. E-mail and Mattermost direct messages of the bot go to one recipient and carry the full text.
• A webhook sees its own group and the internal groups; a webhook for all groups receives no events of restricted groups. Scope a webhook to the group to get them (see Event webhooks). The revision.released event of a visible revision released by a change that also holds restricted items comes without the change object. A queued delivery whose group is restricted before it is sent is not sent (status failed, “Not sent: a project group of the event was restricted after it was queued”).
• The MCP server and the built-in assistant use the user’s rights, so they see the same as the user. The assistant sends what a member reads to the configured model provider. It reads the user’s rights again before every tool call, so a membership removed during a run applies at once.
• Text other users typed (request comments, names, notes) reaches the assistant and may try to make it copy restricted content into a comment or a draft that those users can read. Once a run has read something that a reader outside the user’s restricted groups would not get (that reader is also somebody else: what the user sees only as author, reviewer, requester, assignee or admin counts, and so does their worklist – also for a user who is in no restricted group), the page the question was asked on is such an item or change order, or a draft the assistant created or extended holds such content, the assistant’s text-writing tools (create_change_draft, create_change_request, comment_change_request) refuse for the rest of the run. External MCP clients act for the user without this check – the same caution applies as to any agent working with the user’s rights.

When changes take effect

Memberships and roles are loaded on every request (web, API tokens, desktop, MCP): removing a member takes effect on the next request. Nothing is deleted – watches and favorites of the lost items are hidden and come back with the access, check-outs stay (the removal message says how many). A manager of the group (or an admin) cancels them on the revision page or with POST /api/v1/items/{number}/revisions/{code}/cancel-checkout: managers may release the check-outs of users who are no longer members of the group or who are deactivated. An active member’s check-out a manager releases only with a reason (10 to 500 characters): Release with reason on the revision page, or {"reason": "…"} as the body of the request. The reason is stored in the audit log (revision.checkout_forced_release) and told to the holder in their notification; without one the release is refused (403). Other members cannot release it at all. Release N check-outs in the member list releases all of one person’s check-outs in the group at once (each audited on its own); administrators release everything a user holds from the user page. Season handover (/projects/{id}/season) does the same for many members at once, with one reason for all of them, and also sets member until, removes and demotes – each step with the rules of the single action. See When someone leaves and The end of a season.

Memberships synchronised from the identity provider change only at the user’s next SSO login; a user removed from the IdP group keeps access until then, and indefinitely with an API token. Revoke the user’s tokens or deactivate the user as well. Such a membership stays synchronised when its holder is made a manager (Demote lowers it again), and TeamCraft refuses to remove it while the user is active (it would come back at the next SSO login): remove the user from the IdP group, or have an administrator unlink the group or deactivate the user. Once the user is deactivated, a manager or administrator can remove it: SSO refuses deactivated users, so it cannot come back. A group needs at least one active manager; deactivated managers do not count when a manager leaves, is removed or is demoted (administrators may still do so). A manually added member who is also in the linked IdP group comes back (synchronised) at their next SSO login after being removed.

Files already copied to a desktop working folder stay on that computer; the desktop app marks such revisions as “No longer accessible” and never syncs them again.

Upgrading

Migrations 0024 to 0028 run on start and need no action: 0024 adds the visibility (every existing group stays internal, so nothing changes until a group is restricted), 0025 to 0028 add and back-fill what audit entries and notifications name. Take a backup first, as before every upgrade. Behaviour that changes for everybody, also without a restricted group:

• Placeholder rows (“Restricted item”) exist only once a group is restricted; for internal groups BOMs, references and notes look as before.
• An item of a restricted group that is listed on a change request cannot be deleted until it is removed from the request. Deleting an item of an internal group removes it from its requests and records that in their history.
• A webhook for all groups stops receiving events of a group once it is restricted – scope a webhook to the group before restricting it if a receiver needs them.
• Before restricting a group that shares the default numbering scheme, give it its own scheme (see below), or the shared counter keeps telling how many items it creates.

What stays visible

These are inherent to a shared instance and documented on purpose:

• Item numbers, project group codes and change/request numbers are unique across the instance: choosing a taken one says so (“already in use”, the BOM import says “not available”).
• The shared default number counter shows how many items other groups create. Give restricted groups their own scheme, e.g. {PROJECT}-{TYPE}-{SEQ:4}. A restricted group with a scheme of its own counts in a private counter: another group whose scheme expands to the same text (also one saved before the restriction, or for a later year or month) counts on its own, its numbering preview never shows the restricted group’s numbers, and no scheme is refused because of a restricted group. The private counter starts where the shared one stood when the group was restricted (numbers everybody could see then) and is merged back when the group is opened again. A generated number that is already taken by an item the user may see is skipped; one taken by a hidden item stops the creation (“already in use; change the scheme or enter a number”) instead of skipping on, so another group’s scheme tells of one existing number at a time, like typing a number in does – never how many there are, and it does not use up the restricted group’s numbers. (The built-in shared scheme keeps skipping: its counter is past every generated number, so it only meets typed-in numbers.)
• A BOM line that would close a cycle is refused even if the cycle runs through restricted assemblies (“would create a circular BOM structure”): the structure must stay a tree for everybody.
• Change and request numbers are one sequence for all groups.
• Where-used and referenced-by counts show that restricted items use an item – its owner needs to know before making it obsolete or deleting it.
• Audit entries written before this feature (migration 0024) are shown as stored; their numbers were visible to everyone at the time. Migrations 0025 and 0026 mark the older impact, change and request entries with the items and changes they name (also items listed in the details that have left the change or request since), so these are redacted like new ones. Older notifications get their subject (item, change, request) from their link (migration 0027) and the items and change orders their text names from the numbers in it (migration 0028, e.g. the released source of an impact notice), and are hidden like new ones; only those whose subject and named objects have been deleted since stay as they are.
• Response times and caches: the preview meshes and shape signatures are stored per file content (SHA-256) for the whole instance. Somebody who uploads a file with exactly the same bytes as one in a restricted group can tell from how fast its preview and its similar-parts card are ready that the content exists already – they hold the file themselves, and no hidden item is named.
• Audit entries and notifications remember the groups of the items they name when they are written (migration 0026). They stay redacted for non-members of those groups after the item is deleted or moved out of the group. An item of a restricted group that is an affected item of a change request cannot be deleted (remove it from the request first), so deleting it never makes a hidden request visible; a member who cannot see that request learns that one exists. Items of internal groups hide no request and are deleted with their request rows; each such request records the removal (with the item’s note) in its history and tells its people, without telling the deleter about requests they cannot see.
• Response times of hidden and missing objects are not equalised.
• Backups and the command line contain everything (operators). /admin/audit omits and redacts entries about groups hidden from the administrator by a need-to-know policy.

Event webhooks

Webhooks connect TeamCraft to the rest of the toolchain: when a revision is released, export the BOM to the ERP, start the CAM job, post to the channel. An administrator registers a URL for a set of events; TeamCraft then sends each event as a signed JSON POST. The format is generic – any CI server, ERP connector, automation tool or small script can receive it.

Webhooks are managed on the page Webhooks (administrators only, next to Users) or through the REST API. Creating, changing, deleting, rotating the secret, sending a test and retrying are recorded in the audit log (with the receiver’s host, never the full URL or the secret).

Events

A webhook can be limited to one project group: it then receives only events about items of that group (for a change: any of its revisions; for a change request: any affected item). The revisions list of a change event then holds only that group’s revisions.

Restricted project groups: a webhook is treated as a reader that sees its own group and the internal groups. A webhook for all groups receives no events of restricted groups, and a webhook limited to one group receives no events that touch another restricted group (a change with revisions of two restricted groups goes to neither). To forward the events of a restricted group, limit a webhook to that group. The forms warn when restricted groups exist. revision.released of a revision the webhook may see, released by a change that also holds restricted items, comes without the change object. A queued delivery whose project group is restricted before it is sent is not sent: it is marked failed with “Not sent: a project group of the event was restricted after it was queued”.

Payload

Every payload has the same envelope plus the objects of the event. Objects carry their identifiers, a web_url for people and an api_url for the REST API. File contents and secrets are never part of a payload; fetch files through the API with a token of a dedicated user.

{
  "event": "revision.released",
  "id": "0b7c3c4e-6a55-4b86-9c1e-3a5d2b8f1e07",
  "occurred_at": "2026-11-05T09:41:12.315Z",
  "actor": { "username": "rolf" },
  "revision": {
    "id": "5f0e…", "item_id": "a1c2…", "item_number": "PRT-000042", "item_type": "part",
    "code": "B", "label": "PRT-000042/B", "name": "Bracket", "state": "released", "project": "ROVER",
    "web_url": "https://plm.example.org/revisions/5f0e…",
    "api_url": "https://plm.example.org/api/v1/items/PRT-000042/revisions/B"
  },
  "change": {
    "id": "c9d1…", "number": "CHG-000007", "title": "Thicker flange", "priority": "normal",
    "status": "released", "author": "Erika Muster",
    "web_url": "https://plm.example.org/changes/c9d1…",
    "api_url": "https://plm.example.org/api/v1/changes/CHG-000007"
  }
}

id identifies the event (the same for every webhook that receives it). The URLs are built from TEAMCRAFT_PUBLIC_URL when the request is sent. A typical ERP connector reads revision.api_url, appends /bom?rule=released and imports the structure.

Request

POST <your URL>
Content-Type: application/json
User-Agent: TeamCraft-Webhooks/<version>
X-TeamCraft-Event: revision.released
X-TeamCraft-Delivery: 3e1f2a9c-…            (the same for every retry of this delivery)
X-TeamCraft-Signature: sha256=<hex HMAC-SHA256 of the body, keyed with the secret>

Answer with any 2xx status within 10 seconds – queue longer work (a CAM job) instead of doing it in the request. The response body is ignored and not stored. Redirects are not followed: configure the final URL.

Checking the signature

The secret (tc_whsec_…) is shown once when the webhook is created or the secret is rotated; afterwards only a hint (tc_whsec_…1a2b) is visible. Compute HMAC-SHA256 over the raw request body with the secret as key (its UTF-8 bytes, prefix included) and compare it with the header in constant time. Reject requests whose signature does not match.

Shell (e.g. a CI step that received the body in $BODY):

expected="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$TEAMCRAFT_WEBHOOK_SECRET" | sed 's/^.*= //')"
# `[ a = b ]` stops at the first differing byte; comparing hashes of both
# values leaks nothing usable about the expected signature.
[ "$(printf '%s' "$expected" | sha256sum)" = "$(printf '%s' "$SIGNATURE_HEADER" | sha256sum)" ] \
  || { echo "bad signature" >&2; exit 1; }

A shell variable cannot hold every body byte for byte (command substitution drops trailing newlines, NUL bytes are lost); for anything beyond a quick check, verify the raw body in a real program.

Python:

import hashlib, hmac

def verified(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    # bytes, not str: compare_digest raises TypeError for non-ASCII text
    return hmac.compare_digest(expected.encode(), header.strip().encode())

Rust (crates hmac, sha2 and hex):

#![allow(unused)]
fn main() {
use hmac::{Hmac, Mac};

fn verified(secret: &str, body: &[u8], header: &str) -> bool {
    let Some(hex_sig) = header.strip_prefix("sha256=") else { return false };
    let Ok(sig) = hex::decode(hex_sig) else { return false };
    let mut mac = Hmac::<sha2::Sha256>::new_from_slice(secret.as_bytes()).expect("any key length");
    mac.update(body);
    mac.verify_slice(&sig).is_ok() // constant time
}
}

Replays: remember the X-TeamCraft-Delivery ids you processed and skip repeats; the payload’s occurred_at lets you drop very old requests.

Retries and delivery order

A delivery that does not get a 2xx answer (error status, timeout, refused connection) is retried after about 1, 2, 4, 8, 16, 32 and 64 minutes – each delay with up to 25 % jitter – and marked failed after 8 attempts (roughly two hours). The webhook’s page lists the latest deliveries with status, attempts, HTTP status and the last error, shows each payload, and has Retry (a fresh set of attempts, tried at once) and Send test.

Deliveries are written in the same database transaction as the event itself – an action that fails or is rolled back sends nothing, and a committed one is never lost, even if the server restarts before sending. With several TeamCraft servers on one database each delivery is claimed by exactly one of them (FOR UPDATE SKIP LOCKED with a lease of two minutes; a sender that crashes mid-request is retried after the lease). Deliveries can arrive out of order and, after a crash, a lost response or a Retry while an attempt is still running, more than once – use occurred_at and the delivery id.

Switching a webhook off gives up its waiting deliveries; deleting it removes its history. Sent and failed deliveries are removed after TEAMCRAFT_WEBHOOK_RETENTION_DAYS (default 30).

Where webhooks may send to

Only http:// and https:// URLs are accepted, without a user name or password in the URL (the signature authenticates TeamCraft; a token of the receiver may go into the query string). To keep webhooks from being used to reach internal services (server-side request forgery), TeamCraft checks every address it connects to, at connection time and after DNS resolution:

• Default: public addresses only. Loopback (127.0.0.0/8, ::1), private (10/8, 172.16/12, 192.168/16, fc00::/7), shared (100.64/10), link-local (169.254/16 including cloud metadata endpoints, fe80::/10) and similar ranges are refused, also when they are written as IPv4-mapped, NAT64 or 6to4 IPv6 addresses.
• TEAMCRAFT_WEBHOOK_ALLOWED_HOSTS (recommended for on-premises installations): only the listed hosts can be targeted, and they may resolve to internal addresses – e.g. erp.corp.example,*.ci.corp.example.
• TEAMCRAFT_WEBHOOK_ALLOW_PRIVATE=true: every host may be internal. Use it only when nothing sensitive is reachable from the server.

The unspecified address, broadcast and multicast are always refused. Proxy variables (HTTPS_PROXY, …) are ignored for webhooks so the check applies to the real target. See Configuration.

How the secret is stored

The server needs the secret itself to sign, so – unlike passwords and API tokens, which are stored as hashes – it is kept in the webhooks.secret column of the database. It is never shown again in the web UI or returned by the API, and it is not written to logs or the audit trail. Anyone with read access to the database or to a backup can sign payloads, so protect both like the vault. Rotate the secret on the webhook’s page after a suspected leak; the new secret applies at once, also to deliveries that are still waiting.

Branding: your own logos

Administrators can replace the two TeamCraft logos under Admin → Branding (/admin/branding):

Without an upload the built-in TeamCraft logos stay. Use the built-in logo removes an upload again.

Rules for the files

• PNG, JPEG, WebP or SVG – the type is decided from the content, not from the file name.
• At most 512 KiB; bitmaps at most 4096 pixels per side. A PNG, JPEG or WebP file whose pixel size cannot be read is refused.
• SVG files must not contain scripts, event handlers, animations, foreignObject, entity declarations (<!ENTITY …>) or links to other files: href, xlink:href, src and CSS url(…) may point only into the file itself (#id) or carry an embedded data:image/…. Namespace declarations and metadata, as Inkscape writes them, are fine. Illustrator files saved with Preserve Illustrator Editing Capabilities carry entity declarations and are refused; use File → Export → Export As… → SVG instead, or save from Inkscape as Plain SVG. SVG logos are shown only as images and served with a sandboxing Content-Security-Policy.
• The web header shows one wide logo for all skins (light and dark). A logo with a transparent background and colours that read on both is best.

What else to know

• The logos are stored in the database, so a backup contains them and a restore brings them back.
• Every upload and reset is written to the audit log (branding.set, branding.reset).
• The web pages show a new logo at once. The desktop app loads the logos when it signs in or starts; sign out and in again to see a change.
• The image routes GET /branding/wide and GET /branding/square need no sign-in (the sign-in page shows the logo); they answer 404 while the built-in logo is in use. The REST API reports the state and the content types at GET /api/v1/branding; its image routes are cached private.

Header name and subtitle

Under Admin → Branding → Header name you can rename what the top left of the web header and the desktop title bar shows, today TeamCraft PLM:

• Display name – up to 40 characters, plain text on one line (no < or >). Leave it empty to use the default: TEAMCRAFT_INSTANCE_NAME, else TeamCraft.
• Subtitle – up to 20 characters, default PLM; empty shows none.

The name appears in the web header (when no wide logo is set; the logo wins), page titles, the sign-in page, notification e-mails and chat messages, and the desktop title bar. Changes are effective at once in the web UI and written to the audit log (branding.update); the desktop app reads them when it signs in. The REST API has GET /api/v1/branding (display_name, subtitle) and PUT /api/v1/branding/name (administrators).

Renaming the instance never renames the software. The footer, the desktop About dialog and Settings, the version, the licence and no-warranty notices, /api/v1/version, the CLI, the desktop user agent and the MCP serverInfo always say TeamCraft, so support and the MPL-2.0 notices stay clear about which software runs.

Upgrading and rolling back

TeamCraft upgrades itself: the server applies every missing database migration when it starts (teamcraft migrate does the same without starting the server; teamcraft serve --no-migrate skips it). There is no downgrade migration. The way back is a restore of a backup taken before the upgrade. Take that backup every time – while TeamCraft is 0.x any release may contain breaking changes (Contributing → Releases and versions).

Before the upgrade

1. Read the release notes of the GitHub Release you upgrade to, and the breaking changes below.

2. Check PostgreSQL. The server refuses to start on a PostgreSQL older than 16 (it names the version it found). Upgrade the database server first if needed (pg_upgrade, or dump and restore).

3. Stop the server so that the backup is one point in time.

4. Back up database and vault and keep the directory until the new version has proven itself:

   teamcraft backup /srv/backups/before-0.3.0     # db.dump + vault/objects + manifest.json
   

   The Docker installation backs up through the database container instead (Install with Docker → Backup and restore). Details, requirements (pg_dump in the server’s major version or newer) and what the backup verifies: Operations → Backups.

5. Optional: teamcraft vault check --verify-hashes – a backup stops at a corrupt or missing blob anyway, this finds it earlier.

Upgrade

On start the server

• waits for PostgreSQL, checks its version, then runs the migrations in order. Every migration runs in its own transaction: if one fails, it is rolled back completely, nothing of it stays (no half-added column, no half-converted rows), the server does not start, and the log names the migration. A database that is several versions behind applies all missing migrations one after the other, in one start; a migration that is missing below the newest applied one (as 0021 on a database that already has 0022) is applied too.
• does not touch rows of tables that are only extended: new columns get a default, new tables start empty.
• afterwards runs the background scans of the current version (for example reading the export names of STEP files, migration 0036). They fill in derived data and can be interrupted and repeated; the web interface is usable meanwhile.

If a migration fails, fix the cause named in the log (disk full, a missing permission, a database edited by hand) and start again – the migrations that succeeded are not repeated. If you cannot fix it, roll back.

Refusals that protect the data

• A changed migration is refused. The checksum of every applied migration is stored. If the text of an applied migration differs from the stored checksum, start-up stops with “was previously applied but has been modified”. Only five migrations that were edited before the first release (0002, 0003, 0005, 0011, 0012; comments and seed data only) are accepted with the new text. Never edit a migration of a database you keep.
• A half-applied migration is refused (success = false in _sqlx_migrations, which normal operation never leaves behind).
• An older server refuses a newer database. If the database has migrations the binary does not know, start-up stops with “migration N was previously applied but is missing in the resolved migrations”. Starting the old binary again after an upgrade therefore does not work: restore the backup first.

After the upgrade

• curl -s http://localhost:8080/healthz and /readyz answer ok (teamcraft healthcheck does the same for a container).
• Sign in, open an item with files and a BOM, open a change order.
• Optional: teamcraft vault check – every file the database refers to is in the vault.
• Read the log of the first minutes: the start-up scans (file formats, CAD file references) log how many files they handled, or a warning if they failed; they run in the background and do not stop the server.

Keep the backup for a while: the upgrade is only reversible by restore while the database has not been written to by users – everything entered after the upgrade is lost by a rollback (the vault keeps the new files, which is harmless: it is append-only and content-addressed).

Rolling back

A rollback is a restore of the backup into a fresh, empty database, followed by starting the old version:

# as the PostgreSQL superuser
createdb -O teamcraft teamcraft_old
# the server is stopped; point TEAMCRAFT_DATABASE_URL at teamcraft_old, then
teamcraft restore /srv/backups/before-0.3.0
# start the old binary or image

• The restored database has exactly the migrations of the backup. The old version starts on it. Starting the new version on it again applies the newer migrations again (tested: a backup taken before the newest migrations is restored and migrated without loss).
• teamcraft restore verifies the manifest, the checksum of db.dump and every vault object first; a damaged backup is refused before the database is touched, and pg_restore runs in one transaction, so a failing restore leaves the database unchanged.
• Restoring over the already upgraded database needs --force. It replaces the tables contained in the backup but not tables of the newer version. When such a table depends on a restored one (a foreign key), the restore fails as a whole and changes nothing; where it does not fail, the newer tables stay while the migration table says they were never created, and the next upgrade stops with “relation already exists”. Use a fresh database.
• Sessions and API tokens are part of the database: they are as old as the backup.
• Configuration and secrets are not part of the backup. Keep the configuration of the old version next to the backup.

Mattermost: switch from the webhook to a bot

Mattermost notifications are now direct messages of a bot account (TEAMCRAFT_MATTERMOST_URL and TEAMCRAFT_MATTERMOST_BOT_TOKEN, see Configuration). An installation with only TEAMCRAFT_MATTERMOST_WEBHOOK keeps working, but logs a deprecation warning at start-up and the account page says so; the webhook mode will be removed in a later version. To switch:

1. Create the bot account and its token in Mattermost.
2. Set TEAMCRAFT_MATTERMOST_URL and TEAMCRAFT_MATTERMOST_BOT_TOKEN (or …_FILE); remove TEAMCRAFT_MATTERMOST_WEBHOOK and TEAMCRAFT_MATTERMOST_DIRECT. The bot wins when both are set.
3. Restart and send a test notification from Account → Notifications.

Differences users notice: nothing is posted into the channel any more, the messages come from the TeamCraft bot, and notifications about restricted project groups carry their full text (unless the group switched notification content off). A wrong Mattermost username now shows as a failed delivery with a reason instead of a post that vanishes. No database change is needed. MATTERMOST_ERROR_WEBHOOK is not affected.

Breaking changes per version

What changed in each version is in CHANGELOG.md and the notes of its GitHub Release. What the database upgrade itself does, per released version (a migration is additive unless it says otherwise; the last row is main, not yet released):

An older published release first needs the steps of the releases between: a database of the first v0.1.0 tag (0001 – 0014, 0016 – 0020, 0022) gets 0021 and 0023 – 0031 first, then the rows above. Of these, the read-permission migrations 0024 – 0028 change behaviour for everybody: see Read permissions → Upgrading.

The proof behind these statements is in tests/migrations.rs (an empty database, every migration one at a time, a v0.1.0 database with data) and tests/upgrade_restore.rs (a seeded database one and several migrations behind head, a migration that fails and rolls back, an older server on a newer database, a backup from before the newest migrations restored and migrated, a damaged backup refused). When a release adds a migration that converts or removes data, its row in the table above says so before the release.

Operations

Backups

teamcraft backup <dir> writes one backup directory; <dir> must not exist or be empty:

The PostgreSQL client tools (pg_dump, pg_restore) must be installed on the machine that runs the command, in the server’s major version or newer (Debian/Ubuntu: postgresql-client-17; Windows: the bin folder of the PostgreSQL installation on PATH). The database password is handed to the child process in PGPASSWORD only. The database is dumped first and the vault afterwards; blobs are append-only, so every file that the dump references is included. Every blob is checked against its SHA-256 while it is copied, and every file content the database refers to must be in the vault: a corrupt or a missing blob stops the backup (run teamcraft vault check --verify-hashes to find it). Stop the server for a consistent point in time. A failed backup removes what it wrote – the directory, if it created it – and the manifest is written last, so an interrupted backup is never taken for a complete one.

Restore with the server stopped:

sudo -u teamcraft teamcraft restore <dir>            # database must be empty
sudo -u teamcraft teamcraft restore <dir> --force    # replace an existing database

The command first verifies the manifest, the SHA-256 of db.dump, the object count and the SHA-256 of every vault object, then runs pg_restore --clean --if-exists --no-owner --single-transaction against the configured database and copies the vault back without overwriting blobs that are already present. Start the server afterwards; it applies newer migrations.

• The target database must exist; TeamCraft does not create it (createdb -O teamcraft teamcraft as the PostgreSQL superuser).
• pg_restore runs in a single transaction: if it fails, the database is unchanged, and the vault too (it is copied only after the database).
• Large objects of the database travel with the dump. The previews/ cache is neither backed up nor touched by a restore; previews are made again.
• A backup of an older version restores into an empty database; the next start migrates it (tested with a v0.1.0 database).
• --force replaces the objects contained in the backup; other objects in the database stay, so a fresh, empty database is preferable. To roll back an upgrade, restore into a fresh database and start the old version; the next start of the new version migrates it again. Over the upgraded database, the restore fails when a table of the newer version depends on one it would replace; where it succeeds, tables the newer version added remain and the next upgrade may stop with “relation already exists”. See Upgrading.
• The database password comes from the configuration – TEAMCRAFT_DB_PASSWORD (or _FILE) or the password in TEAMCRAFT_DATABASE_URL, where special characters are percent-encoded (p%40ss for p@ss).
• Sessions and API tokens are part of the database: after a restore, everyone stays signed in and tokens keep working.
• Configuration and secrets (.env, the system teamcraft.env, TLS keys) are not part of the backup; back them up separately.

Encrypted backups

teamcraft backup <dir> --encrypt encrypts the dump and every vault object with a key derived from a passphrase (TEAMCRAFT_BACKUP_PASSPHRASE or _FILE, otherwise prompted for twice; at least 12 characters): Argon2id (64 MiB, 3 passes) for the key, XChaCha20-Poly1305 in 64 KiB authenticated chunks for the files. Object names and the manifest stay plain (the names are the SHA-256 of the plain content); the manifest records the salt, the cost and a key check. The plain dump exists only between pg_dump and its encryption, inside <dir>.

teamcraft restore <dir> notices an encrypted backup and asks for the passphrase (or takes it from the configuration). A wrong passphrase is reported before anything is changed; every file is authenticated and checked against its SHA-256 while it is decrypted, so a changed or truncated file stops the restore. The dump is decrypted to a temporary file in the vault’s tmp/ for pg_restore and removed afterwards. Without the passphrase the backup cannot be restored – store it apart from the backups.

The container image has no PostgreSQL client tools; the Docker installation backs up through the database container instead – see Install with Docker → Backup and restore.

Performance

• Pages run their database queries concurrently; the revision page needs one round trip per independent query group.
• 3D conversions run in separate processes (at most two at a time) with a time limit, so a pathological CAD file never blocks the server; results and failures are cached.
• Uploads are streamed to disk and hashed on the fly; text extraction for the search runs on a blocking thread.

Security

Strict Content-Security-Policy (script-src 'self', no inline scripts or styles), SameSite=Lax cookies plus an Origin check on every form, API tokens only as bearer tokens (never cookies), path-traversal-safe static files, content-addressed downloads with X-Content-Type-Options: nosniff.

Sizing

TeamCraft is measured against a large synthetic vault (see Scale check): about 100,000 items with 200,000 revisions, one million BOM lines in structures ten levels deep, 200,000 files, 20,000 changes and two million audit entries – about 1.6 GB in PostgreSQL. On a GitHub-hosted runner (4 CPUs, 16 GB RAM) nearly every page and API call of the check answers in less than 200 ms, most in a few dozen milliseconds. The slow ones do inherently large work: a search text that names a CAD program (“solidworks”) matches three quarters of the vault (about 1.6 s), and the impact analysis of a change with 1600 widely used parts walks tens of thousands of dependencies (about 220 ms).

• PostgreSQL 16 or newer. For a vault of that size, give PostgreSQL about a quarter of the RAM as shared_buffers (e.g. 1GB), set effective_cache_size to about half of the RAM and, on SSDs, random_page_cost = 1.1; the defaults (128 MB, random I/O priced for spinning disks) make the planner prefer full table scans.
• The pg_trgm extension (part of PostgreSQL, “trusted”, so the owner of the database may create it) backs the substring search over item numbers, names, attribute values and file names with trigram indexes. Migrations 0023 and 0031 create it when they can; otherwise the search still works but reads the tables – a few hundred milliseconds per search at 100,000 items. If the database role may not create extensions, an administrator can run CREATE EXTENSION pg_trgm; in the TeamCraft database and then the CREATE INDEX … gin_trgm_ops statements of migrations/0023_performance_indexes.sql and migrations/0031_attribute_search_index.sql.
• JIT is off and every statement gets a custom plan in TeamCraft’s sessions (jit=off and plan_cache_mode=force_custom_plan, sent as startup options of every connection; the server’s settings for other clients stay as they are): its queries are short, and on a large vault the JIT compilation took longer (100–400 ms) than the queries themselves; a generic plan of a prepared statement ignores how many ids an = ANY($1) list holds. Behind a connection pooler that drops the options startup parameter (e.g. PgBouncer with ignore_startup_parameters = options) the server’s own settings apply instead.
• Indexes of new migrations are built with plain CREATE INDEX at start-up: that blocks writes to the table for the time it takes (seconds at the size above, reads go on) and happens before the server accepts requests.
• Large results are bounded in the web UI: the BOM page and the BOM comparison list the first 2000 lines (the totals and the CSV/Excel downloads cover all of them), the “Where used” card 200 uses, the impact analysis of a change page the 500 nearest dependents. The where-used reports of the API and MCP stop at 2000 rows; the expanded BOM refuses structures beyond 100,000 lines or 5000 assemblies.

Scale check

tests/scale.rs is an ignored test – a tool for developers, not a feature. It creates (once) a database teamcraft_scale on the test server, fills it with the synthetic vault above using set-based SQL (tests/scale/seed.sql, a few minutes), and times the hot paths through the real router: item search, item and revision pages, the multi-level BOM of the largest assembly, where-used of a standard part used in every assembly, BOM comparison, dashboard and worklist of a busy user, vault explorer, notifications, a change with 2000 affected items and its release readiness, the MCP tools search_items, get_bom and where_used, and the REST lists with paging. Each step runs once to warm up and then five times (p50 and max); one more run per step collects the EXPLAIN (ANALYZE, BUFFERS) plan of every statement through auto_explain.

The GitHub Actions workflow Scale check (.github/workflows/scale.yml) runs it on PostgreSQL 18 – by hand (Actions → Scale check → Run workflow, or gh workflow run scale.yml --ref <branch>) and weekly, never on pull requests – and uploads the report as the artifact scale-report: report.md (the timing table: queries per request, slowest statement, sequential scans on big tables), plans.md (every plan) and results.json. How to run it locally is described in CONTRIBUTING.md.

Exporting and protecting the audit log

Administrators export the audit log with the filters of Admin → Audit log (Export CSV / Export JSON, or GET /api/v1/audit?entity_type=&username=&action=&format=json|csv). One export holds at most 100 000 entries, newest first (x-truncated: true when more matched – narrow the filter); entries about items an administrator’s need-to-know policy hides are left out or redacted, as on the page. Every export is itself recorded (audit.export).

TeamCraft only ever inserts into audit_log (the optional retention below deletes old entries and records that it did). To make sure nobody can rewrite it through the database either, run the server with a database role that may not change existing rows, and keep the table owner for migrations:

-- as the owner of the database, after the migrations ran
REVOKE UPDATE, DELETE, TRUNCATE ON audit_log FROM teamcraft_app;

With this grant TEAMCRAFT_AUDIT_RETENTION_DAYS must stay unset (the purge needs DELETE). Together with regular backups that keep older copies, this protects the record; a hash chain over the entries is not part of TeamCraft.

Data retention

The server’s hourly housekeeping also reminds the managers of due access reviews and tells the administrators once about each project group that has lost its last active manager (see users). It removes what is no longer needed. Nothing the database still refers to is ever removed. Removals of product data (old file versions) and of audit entries are recorded in the audit log; caches, expired sessions, staged uploads and unreferenced blobs (also vault gc --apply) are removed without an entry.

Keep only the latest version (large result files)

Every upload of a file name is a new version and the vault keeps all of them (default, retention = all). For files that change with every run and are large – simulation results, measurement series – that adds up. Whoever holds the check-out of a revision can switch a file to keep only the latest version (⋯ → Keep only the latest version on the revision page, or PATCH /api/v1/files/{id} with {"retention": "latest"}; back with Keep all versions / "all"; recorded as file.retention). Nothing is removed at that moment.

The housekeeping then removes a version once a newer version has replaced it for at least TEAMCRAFT_RETENTION_LATEST_GRACE_DAYS days, so a mistaken upload can still be rolled back within the grace period. It never removes

• the newest version of a file,
• anything of a revision that is not in work – revisions under review, released and obsolete revisions keep every version,
• files that keep all versions.

Each removal is one file.purge_versions audit entry per file (versions, hashes, bytes) in the transaction of the removal. The vault blobs that nothing refers to afterwards are removed from disk; content that another file still uses stays.

teamcraft vault purge-versions                 # dry run: list what would go
teamcraft vault purge-versions --apply         # remove it
teamcraft vault purge-versions --grace-days 1  # another grace period

The command uses TEAMCRAFT_RETENTION_LATEST_GRACE_DAYS (or 7 when that is 0) unless --grace-days is given, and works while the server runs.

Orphaned vault content

teamcraft vault gc lists the blobs in the vault that no file, version, attachment, staged import or upload session names and that were not written within the grace period (--grace-hours, default 24, at least 1); --apply removes them. Run it after deleting files, or after purge-versions left content behind that was younger than an hour. Back up before the first --apply.

Storage quotas

Optional limits keep one user – or all of them together – from filling the disk. Both count the sizes of the stored file versions (identical content stored twice counts twice; versions removed by the retention free their share). Without a quota (the default) nothing is limited.

teamcraft user quota --username max             # usage and quota of one account
teamcraft user quota --username max --mb 20480  # 20 GiB for max
teamcraft user quota --username max --mb none   # no limit
teamcraft vault quota                           # usage and quota of the vault
teamcraft vault quota --mb 2097152              # 2 TiB in total

An upload, check-in, import or new item that would go beyond a quota is refused with 413 and stores nothing; a chunked upload is refused when it starts, before any bytes are sent. Lowering a quota never removes anything – the user just cannot store more. Changes are recorded as user.quota and vault.quota in the audit log.

Metrics for Prometheus

Set TEAMCRAFT_METRICS_TOKEN (at least 16 characters, also as _FILE) and scrape GET /metrics with that value as bearer token. Without the variable the endpoint answers 404. Example scrape configuration:

scrape_configs:
  - job_name: teamcraft
    authorization: { credentials_file: /etc/prometheus/teamcraft-token }
    static_configs: [{ targets: ["plm.example.org"] }]

/metrics lies outside /api/v1 and accepts only the metrics token, no personal access token or session. Its answers carry Cache-Control: no-store. If a backlog cannot be counted (database unreachable), its gauge shows NaN and the server logs a warning.

Several replicas: scrape every instance. Request counters, latency, the database pool and the preview queue belong to the instance and can be summed with sum(). The outbox gauges (teamcraft_webhook_deliveries_pending, teamcraft_notification_*_pending) count rows in the shared database, so every instance reports the same number: aggregate them with max(), never sum().

Useful alerts: a rising teamcraft_webhook_deliveries_pending or teamcraft_notification_*_pending (a receiver or the mail server is down), teamcraft_db_pool_idle_connections at 0 for minutes, teamcraft_preview_conversions_waiting above 0 for many minutes (previews pile up behind slow conversions), and a share of 5xx above 1 % of the requests.

Support policy

This page says which versions of TeamCraft receive fixes, what a version number promises, and where to report a problem. It applies to the server, the web UI, the REST API, the MCP server, the command line and the desktop app.

Status. TeamCraft has no stable release yet. It is a work in progress and comes without warranty. Until the first stable release, the rules below for 0.x apply, and security fixes go into main only, as described in SECURITY.md.

Version numbers

TeamCraft uses Semantic Versioning: MAJOR.MINOR.PATCH.

• Before 1.0 (0.x), any release may contain breaking changes, including changes to the configuration, the REST API, the database schema and the command line. Each release note says what the upgrade needs.
• From 1.0 on:
  • a patch release (1.0.1) fixes bugs and security problems and does not change behaviour that users rely on;
  • a minor release (1.1.0) adds features and stays compatible: an upgrade within the major version does not need manual changes beyond the release notes;
  • a major release (2.0.0) may break compatibility. Its release notes list every breaking change and the steps for the upgrade.
• A pre-release (1.0.0-rc.1) is for testing. It gets no fixes beyond the next candidate or the final release.

Database migrations are part of the upgrade. A release never changes an existing migration; a new migration is added instead. Back up the database and the vault before any upgrade, as described in Operations.

Which versions receive fixes

From 1.0 on, when a new minor version is released, the previous minor version keeps receiving security fixes for six months after that release. After the six months, it is no longer supported. A patch release is made for the latest minor version only; a fix for an older minor is made only when it is a security fix.

Fixes are published as new releases, not as edits to old ones. The release notes and the security advisory name the versions that are affected.

Reporting a bug

• Bugs and feature requests that are not security problems: open an issue at github.com/rudalabs/TeamCraft/issues. Include the version (the image tag or the release, or the commit from git rev-parse --short HEAD), the platform, the steps to reproduce, what you expected and what happened. Remove passwords, tokens and other secrets from logs before posting them.
• Security problems: do not open a public issue. Report them privately as described in SECURITY.md through the GitHub security advisory form. The policy there sets out what is in scope and how a fix and its disclosure date are agreed.
• Questions about installation or operation: check this documentation first, the configuration reference and the operations guide. Then open an issue.

Before you report a bug, check the release notes of the version you run. The problem may be fixed in a newer release of your supported version.

What is not promised

• Response times. TeamCraft is maintained by volunteers.
• Support for a version that is no longer in the table above.
• Fixes for deployments that ignore the documentation, for example a server that is exposed without TLS.

Desktop app and server versions

The desktop app checks the server’s version on the sign-in screen and when its main window opens, and shows a warning once per server when the two do not fit:

Patch versions never matter. The message does not block the sign-in; it tells the user whether to upgrade the server or to install the matching app.

Supported file formats

TeamCraft accepts files of any type. The formats below are recognised: labelled with program and kind, searchable by program, delivered with their registered content type. 3D marks the formats the preview shows; refs the formats scanned for referenced files. The complete, current list is on every server at /formats and GET /api/v1/formats (source: src/cadformat.rs).

Mechanical CAD (native)

SketchUp models (.skp) of SketchUp 2021 and later are a ZIP archive behind a UTF-16 header; src/mesh/sketchup.rs reads its model.dat, a tree of tag–length–value records (vertices, edges, faces with their loops, component definitions, instances with a 13-value transform, layers), triangulates every face with an earcut port (src/mesh/earcut.rs, holes and loops touching themselves included), places nested components and groups (up to 32 levels, mirrored ones with reversed triangles) and converts inches to millimetres. Hidden faces and instances, hidden layers and image entities are left out. Files of SketchUp 3 to 2020 (one MFC object stream) are read by the Rust port of OpenSKP (MIT), vendored unchanged in vendor/openskp, and placed and triangulated the same way. The thumbnail is rendered from the 3D preview.

NX parts (NX 1980 and later) are read through their stream container (SPLMSSTR, src/nxpart.rs): the referenced component files come only from its reference streams (not from the save history), the preview image from /Root/images/preview, and the 3D preview of parts from /Root/FastLoad/JT: a JT 9 file whose finest level of detail (topologically compressed tri-strip sets, src/mesh/jt.rs) is refined along its stored surface normals up to 3 × 3 (src/mesh/pn.rs, at most about 500 000 triangles) and shown in millimetres. Assemblies carry no such stream: their 3D preview is put together from the previews of their part files (src/nxasm.rs reads the components and placements from /Root/FastLoad/Structure, src/services/assemblies.rs places the parts). Components are found by file name, like file references – in the assembly’s revision first, otherwise in the latest revision of another item – and sub-assemblies are followed up to 8 levels deep; components that are not in TeamCraft are left out, and so are components on a layer the assembly’s layer settings hide (read from /Root/UG_PART/UG_PART), as in NX. Drawings have no 3D preview.

Stand-alone .jt files (Teamcenter visualisation, exports of NX, CATIA, Creo):

• JT 10 (src/mesh/jt10.rs) carries parts and assembly in one file. The scene graph (an LZMA-compressed segment) gives every shape occurrence with its transform, the units of the model and the nodes NX marks hidden (section and trace-line geometry). Each shape’s finest level of detail is decoded with the JT 9 topology coder plus the newer integer codecs, its hash checked, refined along the stored normals within the same budget as NX parts and placed per instance.
• JT 9 with topologically compressed triangle LODs, as NX writes them: an assembly (several shapes, or a placed one) is put together through its scene graph like JT 10 – the JT 9.5 field widths (I16 versions, F32 transforms), zlib instead of LZMA, metres unless the file names its units; a single part goes through the reader of NX parts as before.
• Other versions report their version. Not read: files that keep their parts in other .jt files (“shattered”), colours, PMI and the B-rep segments.

SOLIDWORKS files from 2015 on are read through their section container (src/swpart.rs). The 3D preview of a part is the display tessellation SOLIDWORKS stores in Contents/DisplayLists (src/mesh/sw.rs):

• each face is stored as triangle strips with a unit surface normal per vertex;
• the per-face vertices are welded on a 1 µm grid;
• the result is refined along the normals like NX parts and shown in millimetres.

An assembly is put together from the previews of its part files. The placements come from the component tree swXmlContents/COMPINSTANCETREE (swpart::placements), using the configuration that was active when the file was saved, with sub-assemblies resolved. Suppressed, hidden and virtual components are left out, and components are found by the file name of their stored path. Files saved before 2015 (OLE compound files) and drawings have no 3D preview.

CATIA V5 parts (.CATPart, container V5_CFV2) are previewed from the visualisation data CATIA saves with them (src/mesh/catia.rs). That data is the container CATCGRCont, a V5_CFV2 document nested in the file; its scene graph holds one uncompressed mesh per body. The reader takes:

• the vertices in millimetres, stored with prefix sharing;
• the exact surface normals of the curved faces;
• the triangle lists, strips and fans of each B-rep face.

The mesh is refined along the stored normals like an NX part. A part saved without visualisation data has no 3D preview, nor do drawings. Details are in Research: 3D preview of CATIA V5 parts.

CATIA V5 products (.CATProduct) are put together from their parts (src/catprod.rs, services/assemblies.rs). A product names no files. The object stream of its container CATProdCont holds per instance:

• the part number and the instance name (_InstanceName);
• a link to the UUID of the referenced document’s CATProdCont, which every CATIA file lists in the container table at its start;
• the placement (_Position): X, Y and Z axis and origin in millimetres.

A component is the CATIA file of the product’s revision (or a file found by name) with that UUID, otherwise <part number>.CATPart or .CATProduct. Sub-products are entered, hidden components are not recognised yet. Details are in Research: 3D preview of CATIA V5 products.

Rhino models (.3dm, versions 1 to 8) are read as openNURBS archives (src/mesh/rhino.rs): nested chunks, the object, layer, block-definition and settings tables. The 3D preview shows what Rhino stored for display – mesh objects, the render meshes of polysurfaces (one per face, welded at 1 µm), the mesh cache of extrusions (Rhino 6 and later) and the quantised meshes of Rhino 1 files – and refines SubD objects, which store only their control net, by Catmull-Clark subdivision (crease edges and corners kept, up to about 200 000 quads per SubD) onto the limit surface. Block instances place the objects of their definition with the stored 4 × 4 transform (nested up to 8 levels). Hidden objects, objects on hidden layers and block-definition objects themselves are left out; coordinates are converted from the model unit to millimetres. Polysurfaces, extrusions and NURBS surfaces saved without render meshes, curves, points, annotations, linked blocks and colours are not shown; such a model keeps the preview bitmap Rhino stored as its thumbnail. Fusion designs (.f3d) are ZIP archives whose entries are mostly compressed with Zstandard (read by src/fusion.rs with the pure-Rust ruzstd, sizes capped and checked against the stored CRC-32). Their 3D preview is the display scene Fusion stores for fast opening (OGS.BlobFolder/OGS/DefaultScene/world and stream_mesh_NNN, src/mesh/f3d.rs): the triangles of every body face, welded per body, refined along their stored normals like NX parts and converted from centimetres to millimetres. Sketches, edges, dimensions and work geometry are left out. The thumbnail is rendered from the 3D preview; a file without a display scene shows Previews/big.png, the image Fusion stored. The exact B-rep (ShapeManager .smb) is not read. See Research: 3D preview of Fusion designs.

Inventor parts and assemblies are OLE compound files whose data lives in zlib- or Zstandard-compressed segments below RSeStorage (src/invpart.rs; Zstandard in newer files, told apart by the magic bytes). The 3D preview of a part is the display tessellation in PmGraphicsSegment (src/mesh/inventor.rs):

• each B-rep face is an indexed triangle list (centimetres) with a unit surface normal per vertex;
• the faces of solid bodies are taken (all faces of a part without a solid), welded on their exact coordinates and refined along the normals like NX parts, and shown in millimetres.

An assembly is put together from the previews of its part and sub-assembly files (src/invplace.rs): the referenced files and the visibility of each occurrence come from the stream UFRxDoc, the placements from AmRxSegment, including the poses a parent gives the children of flexible sub-assemblies. Hidden and suppressed components are left out, and components are found by the file name of their stored path. Not covered: design views other than the saved one, weld beads, drawings and presentations.

Creo parts (.prt.N, src/mesh/creo/) store no display tessellation. The 3D preview is tessellated from the B-rep in the VisibGeom section: the table of contents and the LZW-compressed sections (container.rs), the self-describing tagged format with its compressed numbers (tagged.rs), planes, cylinders, cones and tori with their contours and the edges sampled in both faces’ parameter spaces (brep.rs), interpolating bicubic splines, rolling-ball fillets and ruled surfaces (freeform.rs), ear clipping of every face region in the parameter plane with every edge evaluated once on its most exact face, welding and PN refinement along the analytic normals (tess.rs). Lengths are converted to millimetres with the unit of the UnitSystemDef section (mm, in, …). Turned parts without a plane in the identity frame get their face parametrisations from a seeded face (see Research: 3D preview of Creo parts).

Creo assemblies (.asm.N, src/mesh/creo/asm.rs) are put together from their parts like NX, SOLIDWORKS, Inventor and CATIA assemblies: the section NeuAsmSld lists the direct components – model name, part or sub-assembly, the images of the component’s axes and its origin in the assembly’s unit – and each is found as <name>.prt / <name>.asm (the iteration suffix is not part of the stored name). Family-table instances show their generic; drawings keep their stored JPEG (see Research: 3D preview of Creo assemblies).

SOLIDWORKS files from 2015 on are no OLE files any more but a sequence of Deflate-compressed sections (src/swpart.rs; verified with SOLIDWORKS 2018 files). TeamCraft inflates only the sections it needs, with a hard size limit and a CRC check: the preview image from PreviewPNG, the component files of an assembly from its component tree (swXmlContents/COMPINSTANCETREE: direct components, without virtual components and without the old names of renamed parts that the rest of the file still contains). Files without a component tree (drawings) use the names in the document manager’s section (SwDocContentMgr/SwDocContentMgrInfo); this was not verified with a real drawing. SOLIDWORKS 2014 and older files are OLE files and are read as before. Assemblies stored with an older TeamCraft keep the references found then until the next check-in – or run teamcraft rescan-references once (see Operations).

Instance counts. For SOLIDWORKS 2015+ assemblies (component tree, instances with exclude from BOM not counted), NX assemblies (placed components, hidden layers left out) and STEP assemblies with external part files (NEXT_ASSEMBLY_USAGE_OCCURRENCE per child whose definition is linked to a DOCUMENT_FILE – through APPLIED_DOCUMENT_REFERENCE, PRODUCT_DEFINITION_WITH_ASSOCIATED_DOCUMENTS or DOCUMENT_PRODUCT_EQUIVALENCE; sub-assemblies inside the file count with their own occurrences) and Inventor assemblies (the occurrences of each referenced file from the file descriptor table in UFRxDoc, suppressed occurrences left out – a file with only suppressed ones counts 0, see the research note) the scan also stores how often each referenced file is placed (file_references.instances, instances in GET …/references); the desktop folder import uses it as the BOM quantity, Quantities from CAD… corrects existing lines with it. Other formats – Solid Edge, Creo, CATIA, … – store no count (null): their references are found by name only. The current versions of SOLIDWORKS, NX and referencing STEP files stored before this are read again once at the next start; for Inventor assemblies stored before run teamcraft rescan-references --format inventor-assembly once (Quantities from CAD… reads the counts from the file and works without it).

.prt and .asm are told apart by content (Creo’s #UGC: header, Solid Edge’s OLE container); .sc must be a SolidCraft ZIP or JSON design.

BIM / architecture

3D / DCC / animation

Neutral exchange

Meshes, visualisation, 3D printing

Point clouds and scans

Electronics, simulation, manufacturing, documents

KiCad (.kicad_pcb .kicad_sch .kicad_pro .kicad_sym .kicad_mod, refs), Altium, Eagle, Gerber and Excellon; OpenRocket, RockSim, RASAero, motor curves (.eng .rse); ANSYS Workbench, Abaqus, COMSOL; G-code; PDF, office documents, CSV, images and archives.

Simulation models and results (FEA, CFD)

Recognised and versioned (see Simulations). Model = setup or solver deck, result = solver output (kind Simulation result). Legacy VTK (.vtk, unstructured grid and polydata), VTK XML unstructured grids and polydata (.vtu, .vtp) and CalculiX .frd (ASCII) are shown in the 3D viewer, coloured by their result fields; the other result formats are stored, not parsed.

Extensions that other programs use too are decided by the file content:

• .sim, .fem and .afm starting with NX’s SPLMSSTR container are NX simulation files. Any other .sim is a STAR-CCM+ simulation when the beginning of the file names STAR-CCM+, otherwise an NX simulation file (older NX releases have no container signature). A text .fem is an OptiStruct/HyperMesh deck, another binary .fem and a non-NX .afm (Adobe font metrics) stay unclassified. The STAR-CCM+ marker is a heuristic; it was not verified with files of every STAR-CCM+ version.
• .dat counts with Fluent’s section syntax ((0 "…"), (1 "…")) as Fluent data, and as a Nastran deck when it is text with a line starting with SOL , CEND, BEGIN BULK or INIT MASTER, or a $ comment naming Nastran or Simcenter (Simcenter 3D writes its decks as .dat); all other .dat files stay unclassified.
• .msh is a Fluent mesh with Fluent’s sections ((0 , (1 , (2 , (10 ) and a Gmsh mesh with $MeshFormat; otherwise, and by name alone, it stays unclassified.
• .cas.h5, .dat.h5 and .msh.h5 need the HDF5 signature (at offset 0 or 512), .cas.gz, .dat.gz and .msh.gz the gzip magic. The HDF5 files are never opened as HDF5.
• .out is a Fluent report file when its first line is a quoted title and the second a header of quoted column names (by name alone: report-file-*.out); .java is a STAR-CCM+ macro only when its beginning names STAR-CCM+ or imports star.common; .op2 must be binary, .f04, .pch, .jou and .trn must be text.
• .e is Exodus II only as netCDF or HDF5 file; .db is not ANSYS when it is an SQLite database, an OLE file (Thumbs.db) or text; .rst text files are reStructuredText; .msg and .sta must be text (Outlook mails are OLE files); .odb ZIP files are OpenDocument databases; .bdf files starting with STARTFONT are bitmap fonts; .k must be text.

Result files are never treated as CAD files referenced by assemblies.

STEP in the 3D preview

STEP files (AP203, AP214, AP242; .step, .stp, .p21) are previewed from one of two sources:

• B-rep – CLOSED_SHELL / OPEN_SHELL of ADVANCED_FACEs with planes, cylinders, cones, spheres, tori, B-spline and Bézier surfaces (also rational), extrusions and revolutions, tessellated with the truck kernel. TeamCraft’s own Part 21 reader hands the kernel only the geometry and topology it understands, in a normalised form: PMI, presentation, product and unit data – where AP242 exporters write empty lists, escaped quotes or binary values that the kernel’s parser rejects – never reach it.
• Tessellated geometry of AP242 (TRIANGULATED_FACE, COMPLEX_TRIANGULATED_FACE, TRIANGULATED_SURFACE_SET, COMPLEX_TRIANGULATED_SURFACE_SET with their COORDINATES_LIST) when there is no B-rep or it is incomplete – no kernel needed. Tessellated PMI (dimensions and notes drawn as triangles, used by an …ANNOTATION…OCCURRENCE) is not shown.

Each shell is tessellated on its own; when the kernel fails on a face – an unsupported surface type, broken trimming, or a panic inside the kernel – the faces are tessellated one by one and only the bad ones are missing. The viewer then says partial preview: N of M faces.

Not applied: length units (the viewer shows model units as in the file) and assembly placements (MAPPED_ITEM, CONTEXT_DEPENDENT_SHAPE_REPRESENTATION – every shell appears in its own coordinates). STEP files above 256 MB are not previewed; the conversion has a time limit of 180 s and the usual triangle limit.

Why not every format is previewed

Most native formats are proprietary and undocumented; reading their geometry would need the vendors’ kernels. TeamCraft stays pure Rust and previews the open formats. For native CAD files keep a STEP export next to them – it is previewed, searchable and scanned for references.

REST API

The JSON API lives under /api/v1 and authenticates with personal access tokens (Authorization: Bearer tc_pat_…), created on the account page with an optional expiry. Cookies are never accepted by the API. GET /api/v1 on a running server lists every endpoint.

TOKEN=…   # from Account → API tokens
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/me
curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:8080/api/v1/items?q=bracket&system=solidworks"

Token scopes

A token has a scope that narrows what its user may do with it; it never widens the user’s rights. Choose it on the account page, with POST /api/v1/tokens ({name, expires_in_days?, scope?}) or teamcraft user create-token --scope.

A refused request answers 403 and changes nothing. A write token cannot create a full token. GET /api/v1/me shows the token_scope. A token with an idle lifetime (the desktop app’s) expires after that many days without use. With TEAMCRAFT_OIDC_TOKEN_IDLE_DAYS, POST /api/v1/tokens gives a single sign-on user a token with that idle lifetime when expires_in_days is missing or longer (the answer’s expires_at and idle_days show it).

Read permissions

Every answer contains only what the token’s user may read (see Read permissions and restricted groups):

• An item, revision, file, file version, change order, change request, attachment or project group the user may not read answers 404 with the same message as an unknown one ({"error": {"code": "not_found", …}}), never 403. Lists and their total leave such objects out.
• Rows that link a visible object to a hidden item are placeholders: "restricted": true, the identity fields (number, name, type, revision, state) empty and the ids the nil UUID; structural fields (find number, quantity, kind of a reference, role of a simulation basis) stay. Notes are emptied (they describe the hidden item), a hidden simulation basis has out_of_date: null, and placeholders come after the visible rows of their kind. This applies to BOM lines and trees, item references, simulation bases, change order and change request items and readiness blockers and warnings; impacts get "source_restricted": true with the source removed. The releasing change order of an impact (change_id, change_number) is left out, and another open change in readiness (other_change) reads “another open change order”, when the user may not see that change.
• Creating an item whose generated number is already held by an item the user cannot see answers 409 (“already in use; change the scheme or enter a number”) instead of skipping to the next number.
• Expanded BOMs (?expand=true) carry restricted_lines and rollup_incomplete; a working set carries restricted_lines; the Pack and Go manifest.json carries restricted_lines.
• Lists that leave entries out say how many: where-used, /items/{number}/simulations and /changes/{number}/impact return the usual array plus the header x-hidden-count; the revision answer has hidden_changes, references have hidden_incoming, a change request has hidden_changes. CAD file-name matches (file_referrers) in groups the user cannot see are left out without a count.
• GET /api/v1/me lists the user’s own memberships in projects and, in restricted_projects, those of them that are restricted. It never names groups the user is not a member of. auth_source is local or oidc; only local accounts have a password to change. preferred_cad is the user’s preferred CAD program (a format family such as nx or solidworks, "" = all alike; set on the account page). File lists are never filtered by it – each file’s format_info.family names its family (null for neutral formats), and clients group by it. capabilities says what the server offers: assistant (Ask TeamCraft is configured), mcp and local_agents (both false when the administrator set TEAMCRAFT_LOCAL_AGENTS=off: POST /api/v1/mcp then refuses every token and clients offer no local agent).
• GET /api/v1/projects lists only the groups the user may see; projects carry visibility (internal or restricted). POST /api/v1/projects takes an optional visibility; PUT /api/v1/projects/{code}/visibility {"visibility": "restricted"} restricts a group (managers of the group and admins). GET/PUT /api/v1/projects/{code}/policy ({"admin_read": "implicit"|"with_reason"|"none"}, managers and admins) read and set how administrators read a restricted group; POST /api/v1/projects/{code}/elevations {"reason"} (admins, policy with_reason) opens 60 minutes of access, DELETE on it ends it.; GET /api/v1/projects/{code}/access-review (?format=csv) is the access report of a restricted group, POST confirms the review {"note"}, GET …/access-review/{id} is the member list at that review (managers and admins). See Read permissions.

Creating items, safely repeated

For a simulation, POST /items also takes basis: {item, revision?, role?} (role geometry by default, mesh, material, load_case, other): the item is created with the basis link in one transaction, name and description default from the basis and the current version of its STEP (else first CAD) file is pinned. A hidden or unknown basis is 404, an invalid role 400, basis on another item type or together with idempotency_key 400.

POST /items takes {item_type, name, project, number?, unit?, description?, material?, mass_kg?, unit_cost?, classification?, attributes?} and answers 201 with the new revision A. A client that lost the answer (timeout, crash) cannot tell whether the item exists. With the optional idempotency_key (1 to 255 printable ASCII characters without spaces, chosen by the client) the request can be repeated safely:

The key is stored in the transaction that creates the item, so a refused request (403, 409, 400 …) leaves no key behind and may be repeated with the same key once it is valid. Without a key every request creates an item. The desktop’s Import CAD Folder… sends a stable key per source item (group, folder and item), so a run after a lost answer finds the items it created.

The check-out / check-in cycle

API=http://localhost:8080/api/v1; H="Authorization: Bearer $TOKEN"
curl -s -X POST -H "$H" $API/items/PRT-000001/revisions/A/checkout
curl -s -H "$H" -o hub.step $API/files/<file id>/content
# … edit …
curl -s -X POST -H "$H" -F file=@hub.step -F comment="wall 2 → 2.5 mm" \
     $API/items/PRT-000001/revisions/A/checkin          # stores and releases in one step
curl -s -X POST -H "$H" $API/items/PRT-000001/revisions/A/cancel-checkout
# a group manager releasing an active member's lock names a reason (10–500 characters)
curl -s -X POST -H "$H" -H "Content-Type: application/json" \
     -d '{"reason": "Lena is away until March; Tom finishes the bracket."}' \
     $API/items/PRT-000001/revisions/A/cancel-checkout

Concurrency: base versions and file status

A check-in or upload can name the version each file is based on in the multipart field bases, a JSON object from file name to the version number (0 = a new file that must not exist yet) or the SHA-256 of the content the client checked out. If a file moved on since (e.g. after an administrator broke the lock and someone else checked in), the request is refused with 409 Conflict and nothing is stored; identical content is never a conflict, and files without a base are stored as before. Several uploads of one name in a request (Creo iterations housing.prt.6, housing.prt.7) share the base: the first is checked against it, the others build on it.

curl -s -X POST -H "$H" -F file=@hub.step -F 'bases={"hub.step": 3}' \
     $API/items/PRT-000001/revisions/A/checkin
# 409 {"error": {"code": "conflict", "message": "hub.step changed on the server since you got it: …"}}

GET …/revisions/{code}/file-status returns every file with its current version, sha256, uploader and the lock (locked_by, locked_by_name, locked_at, locked_by_me, locked_by_other). When somebody else released your check-out of the revision and nobody has checked it out since, released says so (by_name, at, reason and the message Released by X; your local changes are kept and need a new check-out.); otherwise it is null. POST the same path with the client’s files to get the sync state of each local copy:

curl -s -X POST -H "$H" -H 'Content-Type: application/json' \
     -d '{"files": [{"filename": "hub.step", "sha256": "9f86d0…", "base_version": 3}]}' \
     $API/items/PRT-000001/revisions/A/file-status

state is up_to_date, modified (the server still has the base), outdated (the local content is an older version – local_version says which), conflict (changed locally and on the server since the base), new (only local) or missing (only on the server). Without a base, unknown local content counts as modified.

Large files: chunked, resumable uploads

Files of several GB go up in chunks that survive broken connections (similar to the tus protocol; see Large files):

SIZE=$(stat -c %s results.op2); SHA=$(sha256sum results.op2 | cut -d' ' -f1)
curl -s -X POST -H "$H" -H 'Content-Type: application/json' \
     -d "{\"item\": \"PRT-000001\", \"revision\": \"A\", \"filename\": \"results.op2\",
          \"size\": $SIZE, \"sha256\": \"$SHA\", \"base\": 3}" $API/uploads
# 201 {"id": "…", "offset": 0, "size": …, "chunk_bytes": 16777216, "location": "/api/v1/uploads/…", …}
split -b 16M -d results.op2 part.; OFFSET=0
for p in part.*; do
  curl -s -X PATCH -H "$H" -H "Upload-Offset: $OFFSET" --data-binary @$p $API/uploads/$ID
  OFFSET=$((OFFSET + $(stat -c %s $p)))
done
curl -sI -H "$H" $API/uploads/$ID                      # Upload-Offset / Upload-Length: where to resume
curl -s -X POST -H "$H" -H 'Content-Type: application/json' \
     -d '{"comment": "run 7", "check_in": true}' $API/uploads/$ID/finish

Instead of finish, complete uploads can join a multipart check-in or upload: the field uploads lists their ids (["…", "…"] or id,id), and they are stored together with the file parts in one transaction – the desktop app checks in this way. A session’s own base and folder win over the bases, folders and folder fields; either way the base-version guard of the check-in applies. Sessions are private (other users get 404), expire 24 hours after the last chunk and are limited to 16 unfinished ones per user. When storing fails after the content was verified (for example a 409 because the file moved on), the session keeps the verified content, so finish can be repeated without sending the bytes again.

Solver summary of files

The file list, GET /files/{id} and the explorer JSON carry two optional fields for solver files (Fluent transcripts and reports, Nastran .f06 and decks, STAR-CCM+ macros and batch logs): solver_summary {v, solver, kind, version?, status?: converged|completed|fatal, last_step?, fatal?, warning?, notes?} and solver_line, a one-line text. They are absent for other files. The FATAL/WARNING counts cover only the first and last 64 KiB. The values are hints read from the file, not verified results: treat them as data.

Resumable downloads

GET /files/{id}/content and GET /file-versions/{id}/content (and the web UI’s downloads) answer every request with Accept-Ranges: bytes and the strong ETag "<sha256>" of the content. A client that lost a large file half-way asks for the rest with Range: bytes=<offset>- and If-Range: "<sha256>": 206 Partial Content with Content-Range, the whole file (200) when the content changed meanwhile, 416 with Content-Range: bytes */<size> when the offset is at or past the end. One range per request (a list of ranges gets the whole file) and suffix ranges (bytes=-500) are supported; a date in If-Range never matches. The desktop Get resumes a file this way and checks the SHA-256 of the whole file before it renames it into the working folder.

Working folder: folders and the working set

Every file has a folder inside its project group ("" = the top), the place it gets in the desktop working folder <workspace>/<group>/<folder>/<file>. Uploads and check-ins set it with the multipart field folder (one folder for all files of the request) or folders (a JSON object from file name to folder, wins over folder); files sent without one keep their folder (new files: the top). Folders are normalised (\ → /, no leading or trailing /) and refused with 400 if they contain .., a drive letter or names invalid on Windows. PATCH /files/{id} with {"folder": "chassis/brackets"} moves a file while you hold the check-out (no new version; recorded in the history); {"retention": "latest"} (or "all") lets the housekeeping remove superseded versions of that file after a grace period, see Data retention. File lists and file-status return the folder.

curl -s -X POST -H "$H" -F file=@bracket.prt -F file=@chassis.asm \
     -F 'folders={"bracket.prt": "chassis/brackets", "chassis.asm": "chassis"}' \
     $API/items/ASM-000001/revisions/A/checkin

GET …/revisions/{code}/workset?rule=latest|released|as_released is what the desktop Get downloads: the revision, its multi-level BOM under the rule and the items holding the CAD files those files reference (references=false leaves them out), each revision with via (root/bom/reference), project_code, lock (locked_by_name, locked_by_me) and its files (file_id, filename, folder, version, sha256, size_bytes); plus unresolved (items without a revision for the rule), missing_references (names not in the vault), file_count and total_bytes.

The desktop Structure view of the navigator reads one level at a time: GET /projects/{code}/structure?limit=&offset= lists the top-level items of a group (no BOM line of the group uses them) and GET …/revisions/{code}/structure?rule=latest|released&limit= the BOM lines of one revision. Both answer {nodes, total}; a node has item_number, item_type, name, the revision the rule resolves to (code, state, both null when there is none, e.g. not released yet), checked_out_by_name, used_in (assemblies that use it), bom_lines (more than 0 = expandable) and, for BOM lines, find_number and quantity. A child in a restricted group the caller cannot read is a placeholder (restricted: true, no identity); hidden assemblies are not counted in used_in.

The desktop file browser (Home, Files) reads one folder of a group at a time: GET /projects/{code}/files?folder=&limit=&offset= answers {folder, folders, entries, total} for the folder (chassis/brackets; empty = the top of the group; normalised like the folder of an upload). folders are the folders directly below it (name, path to ask for, files = files in it at any depth). entries are its files by name, each with the item it belongs to: file_id, filename, size_bytes, format, format_label, format_kind (part, assembly, drawing, …; null if unknown), item_number, item_type, and name, code, state and checked_out_by_name of the item’s latest revision – the browser shows the files of the latest revision of every item. At the top of the group the items without files follow the files (file_id and filename are null), so every item of the group is in the browser. total counts the entries of the folder; limit is at most 500.

POST /worklist/checkin-all (body optional: {"revisions": [id, …]}) checks in all of my check-outs – or the listed ones – without new files, one transaction and one audit record per revision. The answer lists every revision with ok and error, plus checked_in, failed and a summary.

Dependents to check (impacts)

GET /worklist lists the open impacts flat (impacts) and grouped by the dependent revision (impact_groups): each group has the dependent (item_number, item_name, revision_id, revision_code, revision_state, project_id, project_code), latest_at and its impacts, ordered by source item number. Groups are ordered by their newest impact.

POST /impacts/{id}/acknowledge ({"note": "…"}) resolves one impact; POST /items/{number}/revisions/{code}/impacts/acknowledge ({"note": "…", "impacts": [id, …]}) resolves all open impacts on that dependent revision – or only the listed ones, the ones the user saw – with one note, in one transaction, with an audit record per impact. Both need a CAD editor of the dependent’s project group (or an admin) and a note. The list must not be empty and may only name impacts on that revision (400 otherwise). Listed impacts that were resolved in the meantime are skipped; the answer has acknowledged (the resolved impacts) and skipped. If nothing is left to acknowledge the answer is 409 Conflict. Acknowledging stays a human decision: the MCP server only reads impacts.

Where-used over several levels

GET /items/{number}/where-used lists the parent revisions whose BOM uses the item. With ?levels=N (1–25) it walks up further – parents of the parents – and every row also carries level (1 = direct parent) and child_number (the item used on that line). Each item is reported on the lowest level it is reached on. Both reports stop at 2000 rows.

Custom attributes and classification

Administrators define attributes once; values are set per revision by key, as text, number, true/false or one of the choices (null or "" removes a value, keys not sent keep theirs):

curl -s -X POST -H "$H" -H 'Content-Type: application/json' \
     -d '{"key": "length_mm", "data_type": "number", "label": "Length", "unit": "mm"}' $API/attributes
curl -s -X PATCH -H "$H" -H 'Content-Type: application/json' \
     -d '{"attributes": {"length_mm": 120.5, "vendor": null}}' $API/items/PRT-000001/revisions/A
curl -s -X PATCH -H "$H" -H 'Content-Type: application/json' \
     -d '{"classification": "purchased"}' $API/items/PRT-000001
curl -s -H "$H" "$API/items?class=purchased&attr=length_mm&value=100..200"
# simulations with a failed value whose name contains "stress"
curl -s -H "$H" "$API/items?type=simulation&result=failed&result_name=stress"

value matches text and choices as a part (case-insensitive), yes/no attributes with yes/no, numbers with 12, >=10, <=20 or 10..20; an empty value finds every item that has the attribute. Revisions and the item search return attributes (object by key) and classification.

Alternates, supersession and replace in assemblies

action is replace, checked_out (by somebody else), no_permission, in_review, needs_revision (released) or cycle. Linked items in groups the caller cannot read are left out; a successor there is a placeholder with restricted: true. The preview and the replacement carry X-Hidden-Count.

Main resources

The BOM comparison is also available as an Excel workbook of the same lines (same with query): GET …/revisions/{code}/bom/compare.xlsx?with={code}. Both compare the direct lines; depth=all compares every level, with the children resolved by rule=latest|released|as_released (default as_released when one of the revisions is released, else latest; each line then has its level and the resolved revision on both sides). The expanded BOM itself downloads as Excel workbook: GET …/revisions/{code}/bom.xlsx?rule=.

Similar parts

GET /items/{number}/revisions/{code|latest}/similar compares the shape of the revision’s 3D model (its STEP file, else its first mesh, or file=name) with the latest revisions of all other items – see Finding similar parts for the method.

{
  "item": "PRT-000012", "revision": "A",
  "status": "ready",
  "source": { "file_id": "…", "filename": "bracket.step", "sha256": "…", "format": "step" },
  "signature": { "extents": [120.0, 40.0, 8.0], "area": 12160.0, "volume": 38400.0, "closed": true, "triangles": 1234 },
  "ignore_scale": false,
  "candidates": [{
    "item_number": "PRT-000007", "revision_code": "B", "name": "Bracket", "state": "released",
    "revision_id": "…", "file_id": "…", "filename": "bracket-old.stl", "identical": false,
    "score": 91, "shape": 94, "size": 97, "extents": [118.0, 40.0, 8.0],
    "explanation": "extents 118 × 40 × 8 vs 120 × 40 × 8, shape distribution 94 % similar, volume 37760 vs 38400",
    "thumbnail_file_id": null
  }]
}

status is ready, pending (call again shortly), no_shape_file (no STEP or mesh file) or failed (message says why, e.g. the model could not be read). volume is null when the mesh is not watertight.

Suggested reviewers

GET /changes/{number}/suggested-reviewers?limit=5 (1–20) answers who should review this? from the history of the affected items: {"change": "ECO-000004", "suggestions": [{"user_id", "username", "display_name", "role", "score", "reasons": ["edited PRT-000005 3 times in the last 90 days", "manager of ROVER"]}]}, highest score first, ties by name. Only active CAD editors and admins are suggested; the author and the assigned reviewers never are. Users who changed the affected revisions come last with "cannot_review": true (four-eyes): show them, do not add them. It only reads – add a suggestion with POST /changes/{number}/reviewers. See Suggested reviewers for the sources and points.

Review decisions and their sign-off

POST /changes/{number}/review with {"decision": "approve"|"reject", "comment": "…", "meaning": "…"} needs a token with the approve scope. Each entry of reviews and earlier_rounds carries sign_off_method (session, password, sso, token; null while pending) and sign_off_meaning. In the browser, TEAMCRAFT_APPROVAL_REAUTH asks for the password or a fresh single sign-on (see Configuration).

Review rounds and absent reviewers

GET /changes/{number} returns review_round, earlier_rounds (reviews of the rounds before) and, per entry of reviews, absent (deactivated, not_editor, cannot_see_items or null; set only for a pending reviewer who cannot decide). POST /changes/{number}/reviewers/{old_username}/replace with {"username": "<substitute>"} replaces a pending reviewer while the change is in review (author or admin; 409 when it is not in review or the reviewer has decided).

Change requests (ECR)

Every signed-in user – viewers included – raises change requests and comments on them; CAD editors of the project groups of the affected items (and admins) triage and decide. GET /change-requests/{number} returns the request with its items, comments, attachments, linked changes, history and can (the actions the caller may take). A request names at most 100 affected items (an item named twice is listed once; more distinct items are refused with 400 before any item is looked up). See Change requests for the flow.

curl -s -X POST -H "$H" -H "Content-Type: application/json" $API/change-requests -d '{
  "title": "Weld seam cracks", "reason": "manufacturing", "priority": "high",
  "description": "Seen on 3 of 10 parts. Proposal: 4 mm fillet.", "due_date": "2026-12-01",
  "items": [{"item": "PRT-000001", "revision": "A", "note": "File: bracket.step"}]}'
curl -s -X POST -H "$H" -F file=@crack.png $API/change-requests/ECR-000001/attachments
curl -s -X POST -H "$H" $API/change-requests/ECR-000001/triage                     # new → in triage
curl -s -X POST -H "$H" -H "Content-Type: application/json" \
     $API/change-requests/ECR-000001/decide -d '{"decision": "accept"}'           # or reject / defer + comment
curl -s -X POST -H "$H" $API/change-requests/ECR-000001/create-change              # draft CHG with the in-work revisions

create-change answers with the new change, the revisions it added and the affected items it skipped (no revision in work, already in another open change, no access). link-change ({"change": "CHG-000004"}) links an existing open change order instead. When a linked change order is released, the request becomes implemented. Lists filter with ?status=open|all|new|in_triage|accepted|rejected|deferred|implemented|withdrawn, scope=mine|assigned and item={number}; GET /worklist contains requests_assigned and my_requests, GET …/revisions/{code} the open_requests of the item.

Simulations

A simulation revision (item type simulation) links the revisions it was computed with and stores its key result values (see Simulations). Writes need the simulation revision checked out by the caller.

A solver script after a run:

curl -s -X POST -H "$H" $API/items/SIM-000003/revisions/B/checkout
curl -s -X PUT -H "$H" -H 'Content-Type: application/json' \
     -d '{"results": [{"name": "Max. von Mises stress", "value": 182.5, "unit": "MPa",
                       "upper_limit": 250, "load_case": "LC1", "solver": "CalculiX", "solver_version": "2.21"}]}' \
     $API/items/SIM-000003/revisions/B/simulation/results
curl -s -X POST -H "$H" -F file=@job.frd $API/items/SIM-000003/revisions/B/checkin

As-built records

An as-built revision (item type as_built, numbers AB-…) records one physical unit: the design revision it was built to, serial number, build date, deviations and – as its regular BOM – what was really installed (see As-built records). Writes need the as-built revision checked out by the caller; a revision checked out by somebody else answers 409, a viewer or a non-member of the group 403, and a revision or deviation the caller may not read 404.

A change order with an as-built revision cannot be submitted (409) while that revision has no build record or an open deviation.

Webhooks (administrators)

Outgoing event webhooks – payloads, signature and retries are described in Event webhooks. Every endpoint needs an administrator’s token; secrets are returned only by POST /webhooks and rotate-secret.

curl -s -X POST -H "$H" -H "Content-Type: application/json" $API/webhooks -d '{
  "name": "ERP BOM export", "url": "https://erp.example.org/teamcraft/events",
  "events": ["revision.released", "change.released"], "project": "ROVER"}'

Errors are JSON: {"error": {"code": "conflict", "message": "…"}} with the matching HTTP status (400, 401, 403, 404, 409, 413, 500).

MCP server (AI assistants)

TeamCraft has a built-in Model Context Protocol server, so an AI assistant such as Claude Code, Claude Desktop or any other MCP client can work with your PDM data: find items, explain structures and where-used, summarise what changed between revisions, check a BOM before a release, prepare change orders, summarise and raise change requests, and check simulations and their results.

The assistant works with your rights: it signs in with one of your personal access tokens and every tool calls the same business logic as the REST API and the web interface. It can read what you can read, it can draft change orders if you are a CAD editor, and – like everyone signed in – raise change requests and comment on them. It cannot submit, approve, release or make anything obsolete, and it cannot triage, accept, defer or reject change requests. Those decisions stay with people.

The same tools also power the optional server-side assistant, Ask TeamCraft. It needs no client, only an AI provider (Anthropic, OpenAI-compatible or a local model) configured on the server.

Endpoint

The HTTP endpoint is stateless. Each POST carries one JSON-RPC 2.0 message (or a batch), and the answer is application/json. Notifications get 202 Accepted. There is no event stream (GET returns 405) and no session id. Protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05 are accepted. Without a valid token the endpoint answers like the rest of the API, with 401 and a JSON error.

With TEAMCRAFT_LOCAL_AGENTS=off the endpoint refuses every call with 403 and a JSON-RPC error naming the setting, for every token: the desktop app’s agent, the teamcraft mcp bridge and any other client (GET /api/v1/me then reports capabilities.mcp: false). The built-in assistant is not affected. See Local agents for what this setting can and cannot enforce.

Setup

Create a personal access token under Account → API tokens. Give it an expiry, and give each assistant or machine its own token so you can revoke it on its own. Prefer a scoped token: read_only (only the read-only tools), write (all tools, but no approving on the REST API) or mcp_only (see Token scopes).

Claude Code

claude mcp add --transport http teamcraft http://localhost:8080/api/v1/mcp \
  --header "Authorization: Bearer <token>"

Use the server’s public https:// URL for a shared installation. Then ask, for example: “What changed in ASM-000003 between B and C?”, “Is ASM-000003 ready to be released?”, “What problems were reported on PRT-000012?”, “Which simulations are out of date after yesterday’s release?”, “Summarise the results of SIM-000003 rev B vs A”, or use one of the prompts below (/mcp__teamcraft__release_check).

Clients that only speak stdio

Some clients, such as Claude Desktop, start MCP servers as local processes. The teamcraft binary bridges them to the HTTP endpoint:

{
  "mcpServers": {
    "teamcraft": {
      "command": "teamcraft",
      "args": ["mcp", "--server", "https://pdm.example.org"],
      "env": { "TEAMCRAFT_TOKEN": "<token>" }
    }
  }
}

The bridge reads newline-delimited JSON-RPC from stdin, forwards each message to POST /api/v1/mcp and writes the answers to stdout. It writes nothing for notifications, and diagnostics go to stderr. The token comes from TEAMCRAFT_TOKEN or --token-file <path> and is never printed. --server defaults to TEAMCRAFT_SERVER, or else http://localhost:8080. Messages longer than 4 MiB are rejected.

Tools

All tools return compact JSON that uses item numbers and revision codes instead of internal ids. It is sent both as text and as structuredContent. Long lists are capped and marked with truncated: true: expanded BOMs stop at 2000 rows, other lists at 500 entries, and the whole result at 1 MiB.

Revisions are given as item plus revision (latest by default). In the change order tools, items are given as PRT-000012 (meaning its in-work revision) or PRT-000012/B. If create_change_draft cannot add one of the revisions, it cancels the new draft again, so nothing half-finished is left behind. In create_change_request, PRT-000012 names the item and PRT-000012/B the revision the problem was found in (at most 100 items); every item is resolved before the request is created, so a typo creates nothing. compare_simulation_results defaults like compare_revisions: to = latest, from = the revision before it.

Each tool declares MCP annotations. The read tools are readOnlyHint, and no tool is destructiveHint. Clients that ask before running write tools will ask before create_change_draft, add_to_change, create_change_request, propose_result_values and comment_change_request.

Prompts