How to back up, export and restore your data

MechanicDesk can move structured workspace records between devices with JSON export/share/import. The hosted /app workspace can also save authenticated user snapshots, save/load shared organisation snapshots and export a server-owned shared organisation snapshot for team-ready recovery.

What it does

• Exports or shares customers, jobs, forms, invoices, templates, settings and account/team scaffold records as JSON.
• Imports a MechanicDesk JSON export after showing record counts, new records and matching existing IDs.
• Backs up structured records from /app to the hosted API when signed in.
• Saves, loads and exports shared organisation snapshots by the current organisation slug.
• Can check current organisation access before shared snapshot save/load/export.
• Can preview and merge a selected JSON import into the shared organisation snapshot through the hosted API when signed in.
• Merges or replaces hosted structured snapshots back into the current browser workspace.
• Keeps photo bytes local; exported and hosted snapshots include photo metadata only.

Where to find it

• Hosted workspace: /app -> Data import and export
• Mobile shell: / -> More -> Settings -> Cloud backup

Step by step

Export a local JSON backup

1. Open /app.
2. In Data import and export, select Export data.
3. Keep the downloaded JSON file for desktop transfer or manual recovery.

Share a local JSON backup

1. Open /app.
2. In Data import and export, select Share export.
3. In a native iOS or Android build, use the platform share sheet to send or save the JSON export.
4. In a browser or PWA, use the browser share sheet when available; otherwise keep the downloaded fallback file.

Import a local JSON backup

1. Open /app.
2. In Data import and export, select Choose import.
3. Choose a MechanicDesk JSON export.
4. Review the customer, job, form, invoice, template and reminder counts.
5. Review how many records will be added and how many matching existing IDs were found.
6. Select Merge new records to add only records that do not already exist in this browser workspace.
7. Select Replace workspace only when you want the file to replace the current browser records.

Merge new records keeps the current browser records when a record ID already exists. Replace workspace replaces the current browser records.

Back up through the hosted API

1. Sign in to hosted Supabase access in /app.
2. In Data import and export, find Hosted API backup.
3. Select Back up.

The hosted API stores a structured snapshot for the signed-in user.

Restore from the hosted API

1. Sign in to hosted Supabase access in /app.
2. In Data import and export, find Hosted API backup.
3. Select Merge backup to add only records from the hosted snapshot that do not already exist in this browser workspace.
4. Select Replace from backup only when you want the hosted snapshot to replace the current browser records.

Merge backup keeps the current browser records when a record ID already exists. Replace from backup replaces the current browser records.

Save a shared organisation snapshot

1. Sign in to hosted Supabase access in /app.
2. Check the organisation Workspace slug in Account.
3. In Account, use Organisation access -> Check access if you want to confirm the signed-in role before saving.
4. In Data import and export, find Shared organisation snapshot.
5. Select Save shared.

For a new organisation, the hosted API creates the organisation, writes member rows from the Account screen, and stores the structured snapshot. For an existing organisation, owners/admins can update organisation/member metadata and the snapshot; active technicians can save the shared snapshot without changing persisted organisation/member rows.

Load a shared organisation snapshot

1. Sign in to hosted Supabase access in /app.
2. Check that the current organisation Workspace slug matches the workspace you want to load.
3. In Account, use Organisation access -> Check access if you want to confirm the signed-in role before loading.
4. In Data import and export, find Shared organisation snapshot.
5. Select Merge shared to add only records from the shared snapshot that do not already exist in this browser workspace.
6. Select Replace from shared only when you want the shared snapshot to replace the current browser records.

Merge shared keeps current browser records when a record ID already exists and updates the local account/team scaffold from the shared snapshot. Replace from shared replaces the current browser records.

Export a shared organisation snapshot

1. Sign in to hosted Supabase access in /app.
2. Check that the current organisation Workspace slug matches the shared workspace you want to export.
3. In Account, use Organisation access -> Check access if you want to confirm the signed-in role before exporting.
4. In Data import and export, find Shared organisation snapshot.
5. Select Export shared.

Export shared downloads the current shared organisation snapshot as a metadata-only JSON file after the hosted API confirms that the signed-in role can view the shared snapshot. It does not include local photo bytes.

Preview an import against the shared organisation snapshot

1. Sign in to hosted Supabase access in /app.
2. Check that the current organisation Workspace slug matches the shared workspace you want to update.
3. In Data import and export, select Choose import.
4. Choose a MechanicDesk JSON export and review the local import preview.
5. Select Check shared merge.

The hosted API checks the current shared organisation snapshot and reports how many records would be added and how many existing shared records would be skipped. The check requires a signed-in organisation role that can view shared snapshots.

Merge an import into the shared organisation snapshot

1. Sign in to hosted Supabase access in /app.
2. In Data import and export, select Choose import.
3. Choose the MechanicDesk JSON export you want to merge.
4. Select Check shared merge if you want to review the shared conflict count first.
5. Select Merge to shared.

Merge to shared adds only records whose IDs do not already exist in the shared organisation snapshot. It requires a signed-in role that can write shared snapshots, and it then loads the merged shared snapshot into the current browser workspace.

What each screen shows

Area	What it shows
Data import and export	Manual JSON export, share, merge/replace import controls and photo-store status.
Hosted API backup	The current hosted backup status plus Back up, Merge backup and Replace from backup actions.
Organisation access	Account panel check showing whether the signed-in role can manage, write shared snapshots or view the organisation.
Shared organisation snapshot	Organisation-scoped save/load/export status plus Save shared, Export shared, Merge shared and Replace from shared actions.
Import preview	Record counts, records that will be added, matching existing IDs, local Merge new records, Replace workspace, Cancel, signed-in Check shared merge and Merge to shared actions.

Tips and good to know

• Use JSON export or Share export before testing restore workflows on important records.
• Use Merge new records, Merge backup or Merge shared when combining browser/device or hosted snapshots. Use replace actions only after exporting the current workspace or when you deliberately want a clean restore from the selected source.
• Native shells use the platform share sheet for Share export; ordinary browsers use Web Share when available and otherwise download the JSON file.
• Hosted snapshots are per signed-in Supabase user at this stage.
• Hosted snapshot reads and writes use the signed-in user's bearer token against Supabase RLS; they do not require a service-role key.
• Shared organisation snapshots use the current organisation slug, Supabase RLS membership checks and API capability checks. Owners/admins can manage organisation/member rows and snapshots; active technicians can write snapshots only; active viewers are read-only.
• Export shared uses GET /api/organisations/export with the signed-in user's bearer token, strips embedded photo data, downloads a JSON file and records an organisation activity event when the setup SQL is current.
• Shared import preview/merge uses POST /api/organisations/import with the signed-in user's bearer token. View access can preview; shared-snapshot write access is required to merge.
• If Organisation access has been checked and shows a denied capability, the hosted /app blocks the related shared snapshot action before calling the API.
• Local photo files are not uploaded by the hosted snapshot API. Use the mobile shell's photo backup flow when Supabase storage is configured.
• Shared snapshot saves, exports and shared import preview/merge actions are recorded in organisation activity when the latest Supabase setup SQL has been applied. Local Merge new records remains a browser-only merge into the current device workspace.

Troubleshooting

Problem	What to try
Back up, Merge backup or Replace from backup is disabled	Sign in to hosted Supabase access first.
Save shared, Export shared, Merge shared or Replace from shared is disabled	Sign in to hosted Supabase access first.
Check shared merge or Merge to shared is disabled	Sign in to hosted Supabase access first, then choose a JSON export so the import preview is visible.
Restore says no snapshot was found	Back up once from the signed-in account, then try restore again.
Shared load says no organisation snapshot was found	Check the organisation slug, then save a shared snapshot from an owner/admin account.
Shared export says no organisation snapshot was found	Check the organisation slug, then save a shared snapshot before exporting.
Shared save says the role cannot write snapshots or cannot save shared snapshots	Ask an owner/admin to activate the member row and set the role to owner, admin or technician, then check access again.
Shared load says the role cannot load snapshots	Ask an owner/admin to activate the member row, then check access again.
Shared export says the role cannot export shared snapshots	Ask an owner/admin to activate the member row, then check access again.
Shared import preview says the role cannot view shared snapshots	Ask an owner/admin to activate the member row, then check access again.
Shared import merge says the role cannot merge shared snapshots	Ask an owner/admin to activate the member row and set the role to owner, admin or technician, then check access again.
Photos are missing after restore	Use the same browser/device where the local photo files exist, or run the separate photo backup flow when available.
Import is rejected	Choose a MechanicDesk JSON export rather than a PDF, image or spreadsheet.
Merge new records adds fewer records than expected	The preview skips records whose IDs already exist in the current browser workspace. Use Replace workspace only if you want the file to become the whole workspace.
Merge backup or Merge shared adds fewer records than expected	The merge skips records whose IDs already exist in the current browser workspace. Use the matching replace action only if the hosted snapshot should become the whole workspace.
Share export downloads instead of opening a share sheet	The current browser does not support file sharing, or the hosted app is not running inside a Capacitor iOS/Android shell. Use the downloaded JSON file or test through a native build.

Related guides

• Account and Team Workspace
• Mobile Mechanic Workflows
• Platform Architecture