Working Offline

The Clean Estimate Pro mobile app is designed to work in areas with limited or no internet connectivity. You can view client data, create estimates, and capture job details while offline. The app stores changes locally and syncs them to the server when your connection is restored.

Cold Start Without Connectivity

If the installed app still has a saved session, it can reopen offline with the last workspace that the server previously verified for that user. The secure, user-scoped snapshot contains the selected organization, membership and role, available memberships, and basic profile context. This lets the correct role shell and already-cached field data load instead of sending the user back to the sign-in screen solely because the startup request cannot reach the server.

The app accepts the snapshot only when its user, membership, and organization identifiers agree. A malformed or cross-user snapshot is ignored, and the offline workspace authorization expires 24 hours after its last successful server verification. A deliberate sign-out clears the saved workspace; changing accounts also clears the previous user's workspace plus its scoped canvassing and proposal cache before the next account is applied.

The snapshot is not a second login credential. While the phone is offline, it cannot learn that a server administrator revoked a session or membership. Network-backed reads and writes still require a valid server session, and the app refreshes the live membership and organization after connectivity returns. An explicit authorization rejection clears the snapshot instead of falling back to offline access.

Canvassing Offline

Canvassing has its own organization- and user-scoped local cache and durable queue. Open each assigned territory while connected before entering a low-service area.

During an already-started shift, you can:

• Search and page through downloaded targets in map or list view.
• Record append-only door outcomes and see the marker change immediately.
• Long-press a missing property inside the assignment and keep its marker pending while the address waits to resolve.
• Preserve the original visit time and available device location.
• Continue active-shift background GPS collection.
• Create and autosave a residential estimate draft with a still-valid,

verified pricing bundle that this account downloaded while connected.

• Queue initial proposal delivery or an intentional resend.

The queue replays dependencies in order: a missing property must resolve before it can receive an outcome, the door visit must sync before its attributed proposal, and the proposal must exist before its delivery. A blocked or failed prerequisite prevents the proposal from being presented as sent.

Client-generated identifiers prevent duplicate visits and GPS points. Proposal delivery uses a stable key for retries, while each intentional resend receives a new key. A permanently rejected item moves to Needs review so later valid work can continue.

Starting a new shift, AI assistance, customer acceptance and signatures, payment links, and schedule updates require connectivity. A local residential draft must sync and then be reopened as the canonical server estimate before the customer can review terms or sign. Ending a shift while offline still stops the native tracking task immediately; only the server-side finalization remains queued.

Pending data stays pinned to the organization and user that created it and resumes only under that saved user session. Explicit sign-out clears the saved workspace, while reconnecting lets the server confirm whether the session and membership are still valid.

See Door-to-Door Canvassing for the complete field workflow.

How Offline Sync Works

The app uses a local database on your device to cache data and queue changes. The sync process follows three stages:

1. Pre-cache -- When you are online, the app downloads and stores a local

copy of your most-used data. Residential estimating uses one verified bundle containing the active price book, supported services, add-ons and size options, approved custom-item templates, published Suds Club setup, and your effective pricing permissions.

1. Offline queue -- When you make changes without connectivity, the app saves each action (new estimate, client edit, note, photo) to a local queue with a timestamp.
2. Sync on reconnect -- When your device regains an internet connection, the app automatically processes the queue and pushes all pending changes to the server. Incoming changes from other team members are pulled down at the same time.

Sync Status Notices

Routine background syncing stays out of the way. The app does not show a global banner while saved proposals and other normal changes upload.

When the device is offline, a notice confirms that work is being saved locally. You can continue working, and queued changes upload automatically after the connection returns.

If a saved change needs attention, open More > Offline & Storage. Retry sync puts failed work back in the queue and tries again. Acknowledge items hides the prompt for the current app session without deleting the saved change; failed work remains counted and available for another retry. Once no queued or failed work remains, the error state clears automatically. The queue summary includes proposal updates, deliveries, photos, pipeline updates, and other saved work so its visible buckets reconcile with the total.

After the canonical Commercial, Fleet, and Holiday Lights sync rollout, an online authenticated app start performs one narrow recovery pass for matching older failed proposals whose errors specifically say the former proposal-table contract contained an unsupported sync column. Those identified legacy items return to the queue and use the new server-validated estimate sync. The pass runs only once for each organization and user during that signed-in app session. Validation failures, delivery failures, malformed records, other estimate types, and another workspace's items remain untouched and still require normal review.

The sync engine waits for the device's first network result and requires an internet-reachable connection before uploading. A Wi-Fi or cellular link that cannot reach the internet does not consume retries or turn saved work into a failed item.

Signing out, changing workspaces, or otherwise closing the active mobile session also shuts down that session's network and app-state sync listeners. Only the current session can resume its scoped queue when the app returns to the foreground.

Automatic vs. Manual Sync

The app attempts to sync automatically whenever it detects a network connection. You can also trigger a manual sync at any time:

1. Go to Settings > Offline.
2. Tap Sync Now.

This is useful when you want to confirm all changes are uploaded before switching devices, ending your work session, or heading into an area without connectivity.

What Data Is Available Offline

Not all data is cached locally. The app prioritizes the information you are most likely to need in the field.

Always Available Offline

The following data is cached automatically and accessible without connectivity:

Not Available Offline

The following features require an active internet connection:

• Provider delivery -- email and SMS cannot reach the provider without

connectivity. You can save a draft or queue an eligible proposal delivery offline; Queued means waiting on this device, not delivered.

• Customer acceptance and signatures -- a locally saved proposal cannot

collect or queue a signature. Sync it, reopen the canonical server estimate while connected, and let the customer review the exact scope, total, pricing version, and current organization terms before signing.

• Google Places autocomplete -- address search and the Auto-fill Property feature require an API call. Enter addresses and property details manually when offline.
• Photo uploads -- supported Residential, Commercial site-condition,

Holiday Lights property, and job photos taken offline are stored in the signed-in user's workspace and queued locally. They upload only after connectivity returns. A queued proposal delivery waits until its photos have durable HTTPS references in the canonical estimate. The private storage row and stable photo ID remain the source of truth. Upload responses use a short-lived authorized URL, and estimate and customer photo views generate a new authorized URL whenever an older signed URL expires.

• Real-time notifications -- push notifications require a connection to the notification server.
• PDF preview and generation -- PDF rendering happens server-side and requires an internet connection.
• AI features -- lead scoring, pricing analysis, photo estimation, and AI-generated proposal text all require server connectivity.
• Payment processing -- Stripe payment links, invoice creation, and payment status checks require an active connection.
• Integration syncs -- calendar, QuickBooks, and Workiz data syncs require connectivity.

If you attempt to use one of these features while offline, the app displays a message indicating that the action requires an internet connection.

Creating Estimates Offline

You can build a residential estimate without an internet connection when this account has a still-valid verified bundle. A selected Suds Club plan requires an online refresh before delivery can be queued. The process is otherwise similar to the online workflow with a few differences.

Step-by-Step

1. Tap the + button on the Proposals tab to start a new estimate.
2. Select the estimate type (Residential, Commercial, Fleet, Holiday Lights,

or Generic Quote).

1. Client and Property -- type the client name and details manually. If the client exists in your cached data, the app suggests matches from the local database. Google Places autocomplete is not available offline, so enter the full address, city, state, and ZIP by hand.
2. Services and Pricing -- select services and enter their required

measurements. For a Generic Quote, use verified cached price-book services or add a custom service, product, or equipment item. Pricing uses the verified bundle cached for the signed-in organization and user. If that bundle is missing, invalid, or expired, the builder asks you to reconnect instead of guessing rates or using another workspace's data. Property details remain editable and auto-saved. The pricing notice provides Try pricing again and Keep draft & exit, so the rep can leave safely without losing the property work or creating an unverified total.

1. Review -- review the estimate summary. Tap Save as Draft, or use

Queue Delivery when the proposal is complete and its verified pricing bundle is still valid. A queued delivery waits for successful proposal sync and provider connectivity. This also applies to the first send from every native estimate type: the app binds the queued delivery to the server-issued revision after the canonical estimate write completes.

What Happens to Offline Drafts

Offline drafts are stored in the local database and marked with a pending sync badge in your Proposals list. When you regain connectivity:

1. The app detects the connection and begins the sync cycle.
2. Draft estimates upload to the server, where active catalog rows,

measurements, permissions, Suds Club availability, and totals are validated again.

1. The drafts appear in your estimates list on all devices -- mobile and web.
2. You can then open any draft, review any changed pricing or catalog choice,

and tap Send Estimate to deliver it to the customer.

A proposal queued as Sent must carry the exact revision of the residential bundle that was reviewed. If pricing, a service, an add-on option, an approved template, Suds Club setup, or an effective permission changed while the device was offline, sync stops that proposal for review. It does not retry the same stale payload or let a queued delivery overtake the rejected proposal write.

The pending sync badge disappears once the upload completes successfully.

Editing Existing Data Offline

You can edit client details and estimate drafts while offline. Edits are saved locally and synced when you reconnect.

Client Edits

Open a client profile and update their contact information, address, or notes. Changes save to the local database immediately. A pending sync badge appears on the client record until the edit uploads to the server.

Estimate Edits

Open any draft estimate and modify services, pricing, client details, or add-ons. The app recalculates totals using your cached pricing data. Save the changes and they queue for sync.

When a saved mobile draft cannot be reopened, the app distinguishes a missing draft from a temporary local-storage failure. It does not keep the estimate builder on an indefinite loading screen; use the displayed recovery action to return to Estimates or try the draft again.

Adding Notes and Photos

You can add notes to client records and job entries while offline. Photos taken with your device camera attach to the relevant record locally. Both notes and photos upload during the next sync cycle.

Conflict Resolution

If two team members edit the same record while one or both are offline, a conflict may occur during sync. The app handles conflicts using the following rules:

Simple Fields

For straightforward fields like client phone number, email, or address, the most recent change wins based on timestamp. If you updated a phone number at 2:00 PM and a colleague updated the same phone number at 2:15 PM, your colleague's change takes precedence.

Notes

Notes from both edits are preserved and merged chronologically. Neither person's notes are lost.

Estimates

If two team members edit the same estimate while one or both are offline, the app flags the conflict during sync. A conflict resolution dialog appears prompting you to review both versions side by side and choose which to keep.

Conflict Frequency

In practice, conflicts are uncommon. Most offline usage involves working on different client records or creating new estimates rather than editing the same data simultaneously.

Configuring Offline Settings

Go to Settings > Offline to manage how the app handles local data.

Offline Mode Toggle

Offline mode is enabled by default. The toggle controls whether the app maintains a local data cache. Leave this on unless you have a specific reason to disable it.

Data Cache Size

The settings screen shows how much device storage the app is using for cached data. Typical usage ranges from 50 MB to 200 MB depending on the size of your client list and the number of recent estimates.

Sync Now

Tap this button to manually trigger a full sync cycle. The app uploads any pending local changes and downloads the latest data from the server.

Clear Cache

Tap this to remove all locally cached data and force a full re-download on the next sync. Use this only if you suspect corrupted local data or need to reclaim device storage.

Warning: Do not clear the cache while you have unsynced changes. Verify that the sync status indicator shows a green checkmark before clearing. If you clear the cache with pending changes, those changes are lost permanently.

Preparing for Offline Work

Before heading into an area with limited connectivity, take these steps to ensure you have the data you need:

1. Open the app while online. This triggers a background sync that downloads the latest client and pricing data.
2. Tap Sync Now in Settings > Offline to force a complete sync cycle.
3. Verify the sync indicator in the app header shows a green checkmark, confirming all data is up to date.
4. Browse the clients and estimates you plan to work with during your offline period. Accessing a record ensures it is fully cached in the local database.
5. Check your pricing configuration by viewing the Pricing section in

Settings. Open the Residential builder while connected so the current verified bundle is available before creating estimates offline.

Syncing When Back Online

When your device reconnects to the internet, the sync process starts automatically within a few seconds. Here is what to expect.

Sync Order

The app processes queued changes in a specific order to maintain data integrity:

1. New client records upload first so that estimates can reference them.
2. Client edits sync next.
3. New estimate drafts upload.
4. Estimate edits sync.
5. Notes and other metadata sync.
6. Estimate photo uploads run after the first canonical estimate write. The app

then saves the returned HTTPS references into a canonical estimate revision before customer delivery can continue. Large files may take longer depending on connection speed.

Sync Progress

A progress indicator appears showing the number of pending items and the current upload status. For example: "Syncing 3 of 7 items."

Completion

When sync finishes, the indicator returns to the green checkmark state. All your offline work is now visible on the web dashboard and accessible to other team members.

Queued proposal deliveries also finish at this point. If a proposal was created directly on mobile and does not yet have a linked estimate record, Clean Estimate Pro now sends a signed proposal-view link with a token query parameter instead of dropping the SMS send or requiring an older unauthenticated fallback URL.

That signed-link flow depends on the server-side CUSTOMER_TOKEN_SECRET environment variable. Keep that secret configured and stable across deploys, and expect customer delivery links to expire after their configured lifetime rather than staying valid forever.

Troubleshooting Sync Issues

Changes are not syncing

1. Verify your internet connection by opening a browser and loading a web page.
2. Go to Settings > Offline and tap Sync Now to trigger a manual sync.
3. If the sync fails, read the error message displayed below the Sync Now button. Common causes include expired authentication tokens and temporary server issues.
4. If the error mentions authentication, log out and log back in to refresh your session. Pending offline changes are preserved through the logout and login cycle.
5. If the header warning remains after the queue reaches zero, tap Retry.

The warning should clear after the app confirms that no failed work remains. You can also close the warning without deleting saved work.

Duplicate records after sync

This can happen if you create a new client offline that another team member also created while you were disconnected. The app detects potential duplicates based on matching email address or phone number. When detected, a merge prompt appears asking you to combine the records or keep them separate.

Sync takes too long

Large photo uploads are the most common cause of slow syncs. If you have many queued photos:

1. Connect to a Wi-Fi network for faster upload speeds.
2. Keep the app open and in the foreground during the sync. Mobile operating systems may throttle background data transfers.
3. Wait for the sync to complete before closing the app. Interrupting a sync mid-transfer can cause it to restart from the beginning on the next attempt.

Cached data seems outdated

Pull to refresh on any list screen first. If data still appears stale:

1. Go to Settings > Offline.
2. Tap Sync Now and wait for it to complete.
3. If data remains outdated, tap Clear Cache (after confirming you have no pending changes) to force a full re-download of all data.

Estimate pricing differs from web

This usually means the verified residential bundle is missing, expired, or no longer matches the active price book. A manager may have changed pricing, catalog options, templates, Suds Club, or your pricing permissions since the estimate was reviewed. Reconnect, tap Sync Now, reopen the estimate, and review the refreshed measurements, choices, and total before sending.

Error: "Session expired"

Your authentication token has expired after an extended offline period. Log out via Settings > Profile > Log Out, then log back in with your credentials. The app preserves all pending offline changes and uploads them after you re-authenticate.

Tips

• Sync before you leave the office. A quick tap on Sync Now ensures your local data is current before heading into the field.
• Save estimates as drafts when offline. Finalize and send them as soon as you reconnect -- it takes only a few seconds.
• Monitor the sync indicator. The icon in the header tells you at a glance whether your data is current or has pending uploads.
• Use Wi-Fi for the initial sync. The first sync after installing the app downloads your full client list and pricing data. A Wi-Fi connection avoids consuming mobile data.
• Do not clear the cache unnecessarily. Clearing forces a full re-download of all data. Only use it when troubleshooting persistent issues.
• Take photos on-site even without signal. They attach to the relevant record locally and upload automatically during the next sync.
• Check the sync status before switching devices. If you create estimates on mobile and want to continue on the web, make sure the green checkmark is showing first.