Data Synchronization Architecture

Understanding the synchronization architecture helps administrators troubleshoot issues and optimize ZenTime deployment.

Synchronization Phases Overview

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐

│ WebClock │───▶│ ZenTime App │───▶│ Central Server │

│ (CMS Setup) │ │ (Tablet Device) │ │ (Real-time) │

└─────────────────┘ └──────────────────┘ └─────────────────┘

Phase 1: Initial Setup (Online Required)

The initial setup phase establishes the device's connection to the organizational ecosystem and downloads all necessary configuration and employee data.

Step 1: Tenant Information Fetch

• Administrator enters Company Name and Alias on setup screen
• Device contacts Zenople server at configured API endpoint
• Server validates Company Name and Alias exist in tenant database
• Server returns tenant configuration: 
  • Tenant ID (internal identifier)
  • Organization settings
  • Available timeclocks for this tenant
  • Server endpoint URLs

Step 2: Timeclock Properties Fetch

• Admin/Supervisor enters Timeclock ID
• Device requests specific timeclock configuration from server
• Server Response Includes: 
  • Punch sequence rules (valid transitions between punch types)
  • PIN type configuration (4-digit, 6-digit, SSN-based, Name+SSN)
  • Reset timer duration (inactivity timeout)
  • Geo-fencing settings: 
    • GPS coordinates (latitude, longitude)
    • Radius (distance threshold)
    • Enforcement mode (strict, warning, disabled)
  • IP validation rules: 
    • Allowed IP address validation
    • IP restriction enforcement
  • Break compliance configuration: 
    • Required breaks per shift
    • Break duration min/max
    • Break timing windows
    • Compliance survey questions
  • Post clock-out questions: 
    • Question text
    • Question types
    • Required vs. optional
    • Conditional logic
  • Rounding rules: 
    • Clock in rounding (nearest 5, 10, 15 minutes)
    • Clock out rounding
    • Break rounding
  • Display customization: 
    • Company logo
    • Color scheme
    • Language options

Step 3: Credential Validation

• Administrator enters Username and Password
• Device submits credentials to server with tenant and timeclock context
• Server Validation Process: 
  • Username exists in user database?
  • Password matches encrypted stored value?
  • User belongs to specified tenant?
  • User has Admin or Supervisor role?
  • User has permission to access specified Timeclock ID?
• Validation Success: 
  • Server returns authentication token
  • Device stores token for future API requests
  • Setup process continues
• Validation Failure: 
  • Error message displayed indicating specific issue
  • Setup cannot proceed
  • Administrator must correct credentials or request proper access

Step 4: Employee and Assignment Data Download

• With valid authentication, device requests employee data
• Server Response Includes: 
  • All employees with assignments to this timeclock
  • Employee profiles: 
    • Employee ID
    • Full name
    • PIN (encrypted)
    • Last 4 SSN (for identification form matching)
    • Photo (if configured)
  • Active assignments: 
    • Assignment ID
    • Job/Department name
    • Start and end dates
    • Scheduled shift information
    • Multiple assignment flag
• Device stores all data in local device database

Step 5: Language and Localization Download

• Device requests language translations
• Server sends text strings for all configured languages
• Enables multi-language interface support
• Stored locally for offline operation

Step 6: Transition to Operational Mode

• All configuration and data successfully downloaded
• Device saves setup completion flag
• PIN Entry Screen Displayed
• Device now ready for employee use
• Background sync cycle initialized (first sync in 10 minutes)

Setup Failure Scenarios:

• Invalid Company/Alias: Setup cannot proceed, administrator must verify spelling
• Invalid Timeclock ID: Setup cannot proceed, administrator must verify ID from WebClock Setup
• Invalid Credentials: Setup cannot proceed, administrator must use valid Admin/Supervisor account
• Network Timeout: Setup paused, device retries automatically or administrator can retry manually
• Server Unavailable: Setup cannot complete in offline mode, requires server connection

Phase 2: Normal Sync (Every 10 Minutes, Online)

Once device is operational, regular synchronization maintains data currency and uploads new punches.

Sync Trigger: Automatic every 10 minutes (configurable interval, default 10 minutes)

Bi-Directional Synchronization Process:

Direction 1: Device → Server (Upload)

Step 1: Identify Unsynchronized Punches

• Device queries local database for punches with "pending sync" status
• Collects all punch records since last successful sync
• Includes: timestamps, employee IDs, punch types, assignments, work dates, device metadata

Step 2: Transmit Punch Batch

• Device sends encrypted punch batch to server API
• Batch includes authentication token for security
• Server receives and validates batch

Step 3: Server Processing

• For each punch in batch: 
  • Validate employee credential exists.
  • Validate assignment is active for work date
  • Validate punch sequence logic (e.g., Clock In before Clock Out)
  • Validate timestamp is reasonable (not future date, not decades in past)
  • Apply rounding rules if configured
  • Check for duplicates (same employee, same punch type, within X minutes)

Step 4: Server Response

• Server returns status for each punch: 
  • Success: Punch accepted and stored in Zenople database
  • Failure: Punch rejected with specific error reason
• Device processes response: 
  • Successful punches: Mark as "synced" in local database
  • Failed punches: Keep as "pending sync", log error for administrator review

Direction 2: Server → Device (Download)

Triggered Only If Upload Successful

Step 5: Request Latest Updates

• Device requests data updates from server
• Sends timestamp of last successful sync for delta updates

Step 6: Server Sends Updates

• Updated Timeclock Properties: 
  • If admin changed timeclock configuration in WebClock Setup
  • New settings downloaded and applied immediately
  • Example: PIN type changed from 4-digit to 6-digit
• Updated Language Translations: 
  • If new languages added or text strings modified
  • Ensures consistent messaging across all devices
• Updated Active Assignments: 
  • New employees added since last sync
  • Assignment changes (employee moved to different department/shift)
  • Assignment end dates (employee terminated or transferred)
  • Removes inactive assignments from local cache
• Updated Employee Profiles: 
  • PIN changes (employee changed PIN in web interface)
  • Name corrections
  • Profile additions/deletions
• Punch Corrections: 
  • If supervisor edited punch times in Zenople Web App
  • Correction downloaded to device
  • Will display as "Updated Time" when employee next logs in

Step 7: Local Database Update

• Device applies all updates to local database
• Replaces outdated cached data with fresh server data
• Critical for Accuracy: Ensures device always operates with most current information when online

Step 8: Sync Completion

• Device logs successful sync with timestamp
• Next Sync Scheduled: 10 minutes from completion of current sync

Successful Sync Result:

• All pending punches uploaded and confirmed
• Local cache refreshed with latest server data
• Device and server databases in alignment
• Employees see the most current assignment information

Failed Sync Result:

• Upload Failure: 
  • Punches remain in "pending sync" status
  • Will retry on next sync cycle (10 minutes)
  • Error logged for administrator review
  • Common causes: network timeout, server unavailable, authentication expired
• Download Failure: 
  • Punches may have uploaded successfully
  • Device cache not refreshed with latest server data
  • Device continues operating with slightly stale data
  • Will retry full bi-directional sync on next cycle

Phase 3: Offline Operation

When network connectivity is lost, ZenTime seamlessly transitions to offline mode while maintaining full time-tracking functionality.

Offline Detection:

• Device monitors network connectivity continuously
• When connection lost, sets offline flag immediately
• Visual Indicator: Red line appears at bottom of PIN Entry Screen

Offline Capabilities - Full Functionality Maintained:

• Employees can punch in/out normally
• Break tracking continues
• Assignment selection works (from cached assignments)
• Timesheet view displays (from local punches)
• Multiple assignment handling
• Work date selection
• Identification form entry

Local Storage for All Punches:

• All punches saved to local database
• Punch records marked with "pending sync" status
• No data loss even during extended offline periods
• Storage capacity: Thousands of punch records (device storage dependent)

Sync Attempt Schedule Continues:

• Device continues attempting sync every 10 minutes even while offline
• Purpose: Detect when connectivity is restored automatically
• Process: 
  • Every 10 minutes, the device attempts to contact the server.
  • If connection successful: Immediately begin sync process.
  • If connection fails: Wait another 10 minutes and retry.
• No User Intervention Required: Sync resumes automatically when the network is restored

Extended Offline Scenarios:

Offline 24+ Hours:

• Trigger: Device offline continuously for more than 24 hours
• User Impact: 
  • When employee enters PIN next day, Work Date Selector appears
  • Employee must consciously select work date for punch
  • Prevents accidental misattribution of punches to wrong date
• Rationale: After 24 hours, system assumes calendar day has changed and requires explicit date selection to maintain data integrity

Red Offline Indicator:

• Displayed at bottom-left corner of PIN Entry Screen
• Visual Design: Red bar 
• Purpose: Alerts administrators and employees that device operating in offline mode
• Implication: Punches being stored locally and will sync later

Multiple Days Offline:

• Scenario: Device offline Monday through Thursday, comes online Friday
• Local Database State: 
  • Contains punches from Monday, Tuesday, Wednesday, Thursday (all pending sync)
• Work Date Selection Screen: 
  • Highlights incomplete punch sequences 
  • Employees can complete incomplete punches from the previous day. For example, if an employee did not clock out on Thursday, it will appear under Incomplete Punches from Yesterday. If the clock-out was completed, then on Friday only the Today and Previous Punches sections will be displayed while device is offline.
  • Highlights under Today section for Friday. 
  • Shows all dates with unsynced punches in the previous punches card view.
• When Device Comes Online: 
  • All accumulated punches from all days sync to server automatically
  • Large batch sync may take several minutes depending on volume
  • After sync complete, only today's entries display prominently
  • If incomplete punches are found, then it will be shown in the incomplete punches from yesterday (Only for one day before assignment) highlighted with a red background. 
  • Previous days' entries are synced, so they won't be displayed.

New Assignment Added While Offline:

• Scenario: New employee hired, added to the system on Wednesday afternoon
• Device State: Offline since Monday
• Employee Attempt: New employee tries to punch in on Wednesday evening
• Process: 
  1. Employee enters PIN.
  2. PIN not found in local cached database (device hasn't synced since before the employee was added).
  3. Device attempts to query the server (offline, cannot reach).
  4. After the second failed PIN attempt, the Identification Form displayed.
  5. Employee completes form.
  6. Temporary local record created.
  7. Employee can punch in/out.
• Resolution: When the device comes online, the sync process matches the temporary record to the new employee profile on the server (if credentials match exactly).

Export Capability While Offline:

• Administrators can still activate the export function.
• Exported Data: All locally stored punches, including unsynchronized ones.
• Purpose: Backup during extended outages, troubleshooting, and precautionary data preservation.
• Note: Export represents only punches on this specific device, not organization-wide data.

Phase 4: Recovery Sync (Priority Process)

When a device transitions from offline to online, a special recovery sync process ensures data integrity and minimizes sync conflicts.

Recovery Sync Trigger: Device detects network connectivity restored after an offline period.

Priority Processing - No 10-Minute Wait:

• Normal Sync: Waits for the next 10-minute interval.
• Recovery Sync: Initiates immediately upon detecting connectivity.
• Rationale: Prioritize uploading locally stored data as quickly as possible to prevent data loss and enable supervisor review.

Recovery Sync Step-by-Step Process

Step 1: Immediate Sync Initiation

• Device detects network connectivity (Wi-Fi reconnected or cellular data available).
• Device sends a connection test ping to the server.
• Server responds successfully.
• Recovery sync begins within seconds (not 10 minutes).

Step 2: Push Local Offline Data FIRST

Critical Sequence: Upload before download

Upload Process:

• Device identifies all punches with "pending sync" status.
• Prioritization: Punches sorted chronologically (oldest first).
• Device bundles punches into batch.
• Batch transmitted to server with "recovery sync" flag.
• Server processes with elevated priority.

Why Upload First:

• Preserves all locally captured data immediately.
• Prevents data loss if the device fails during recovery.
• Enables supervisors to review offline period punches ASAP.
• Reduces local storage burden quickly.

Upload Completion:

• Server confirms receipt and processing of all offline punches.
• Device marks successfully uploaded punches as "synced".
• Failed punches remain "pending sync" for next cycle.
• Upload completion logged with timestamp and record count.

Step 3: Pull Server Updates SECOND

After a successful upload, the device requests updates from the server:

Downloaded Data:

• Any timeclock configuration changes made during the offline period.
• New employees added to the system.
• Assignment changes (new assignments, ended assignments).
• Punch corrections made by admin/supervisors via web interface.
• Updated language translations.
• Profile updates (name changes, PIN changes).

Download Processing:

• Device receives update package from server.
• Local database updated with fresh data.
• Cached employee list refreshed.
• Configuration settings applied.
• Result: Device now operating with the most current server state.

Step 4: Clear Local Cache Post-Sync

Conditional Cache Clearing: Only if all offline data is successfully synced.

Cache Clearing Process:

• Device verifies zero punches remain with "pending sync" status.
• If verification passes: 
  • Delete successfully synced punch records from local database.
  • Reset offline operation indicators.
  • Log cache clearing event.
• If verification fails (some punches still pending): 
  • Do NOT clear cache.
  • Keep all data intact.
  • Failed punches will retry on the next sync cycle.
  • Administrator alerted to review sync fail report.

Step 5: Incorrect PIN Form Fill - Credential Mismatch Handling

Scenario: Employee completed the identification form during the offline period, but the entered credentials do not match any employee in the server database.

Recovery Sync Behavior:

• Device attempts to upload punches associated with form-filled temporary record.
• Server attempts to match credentials (First Name, Last Name, Last 4 SSN).
• No Match Found: Server cannot attribute punches to employee.
• Server logs entry in "Aqore Zen Time Sync Fail Report".
• Critical Decision: Info is NOT removed from device locally.
  • Rationale: Preserves data in case of data entry error by employee.
  • Allows the administrator to review and manually correct.
  • Prevents irreversible data loss.

Local Record Persistence:

• Temporary employee record remains on device.
• Punches remain in the local database.
• Marked as "sync failed" rather than "synced."
• If Same Employee Returns:
  • Can still access their local record by filling form with the same credentials.
  • Can continue accumulating punches locally.
  • Administrator Action Required: Must correct employee profile or manually attribute punches in web interface.

Recovery Sync Performance Considerations:

• Large offline period (hundreds of punches): May take 2-5 minutes to complete full recovery sync
• Visual progress indicator may display: "Syncing offline data” to sync completed"
• During recovery sync, device remains fully operational for employee punching
• New punches entered during recovery sync are queued and included in next sync cycle