FieldControl ZA — Master Operations Guide

FieldControl is an enterprise field workforce operating system engineered specifically for South African telecommunications, commercial HVAC, electrical civils, mining contractors, and security infrastructure companies.

1. BigQuery Functional Sharding Architecture

FieldControl operates on a two-tier database topology hosted on Google Cloud BigQuery (Project: tvb-network-379518):

• Tier 1: Single General Core Database (FIELDCONTROL_DB_CLIENTS): Holds master tenant registries, SaaS subscriptions, and administrative user credentials.
• Tier 2: Dedicated Operational Functional Databases: Divided across domain containers (FIELDCONTROL_DB_EMPLOYEES, FIELDCONTROL_DB_CONTRACTORS, FIELDCONTROL_DB_CLOCK_LOGS, FIELDCONTROL_DB_TIMESHEETS, FIELDCONTROL_DB_INVENTORY, FIELDCONTROL_DB_FINANCE_INVOICES, FIELDCONTROL_DB_CHECKLISTS). Each client business operates within an isolated sharded table (biz_<clientId>).

2. Geofenced GPS Clock-In (150m Proximity Rules)

Field technicians register attendance via mobile browsers using GPS hardware fixes. Proximity is computed on the fly using the great-circle Haversine formula against designated site coordinates:

// Haversine Distance Calculation (Metres)
$dLat = deg2rad($lat2 - $lat1);
$dLon = deg2rad($lon2 - $lon1);
$a = sin($dLat / 2) * sin($dLat / 2) +
     cos(deg2rad($lat1)) * cos(deg2rad($lat2)) *
     sin($dLon / 2) * sin($dLon / 2);
$c = 2 * atan2(sqrt($a), sqrt(1 - $a));
$distanceMeters = 6371000 * $c; // Earth radius: 6,371,000m

If the calculated distance is ≤ 150 meters, the clock event is marked as Verified (≤150m). Events outside this perimeter are flagged in red on the supervisor dashboard.

3. BCEA Timesheets & Overtime Rules

In adherence to Section 9 and Section 10 of the Basic Conditions of Employment Act:

• Regular Hours: Capped at 45 ordinary hours per week (or 9 hours per day for a 5-day week).
• Overtime Multiplier: Overtime is calculated at 1.5x the regular hourly billing rate.
• Supervisor Sign-Off: Once verified by a site manager, the timesheet status updates to Approved, enabling instant printable payroll export.

4. Van Stock & Spare Parts Consumption

Every technician's vehicle maintains an independent rolling inventory ledger. When parts (e.g. optical splice trays, breakers, cables) are consumed on a job card:

1. The technician logs the consumed quantity against the active Work Order.
2. The truck inventory quantity is deducted in real-time.
3. If the remaining stock falls below the minimum threshold, an automated Low Stock alert is triggered.
4. The part line-item cost is automatically carried over to the work order's final invoice.

5. Subcontractor COIDA & B-BBEE Compliance

Subcontractors cannot be assigned to hazardous work orders without verified compliance records:

• COIDA Good Standing: Tracks expiration dates with automated alerts at 30, 14, and 7 days prior to expiry.
• B-BBEE Recognition: Supports Levels 1 through 8 with recognition multipliers (Level 1: 135% procurement recognition).
• CIPC Registration: Validates South African corporate registration numbers (e.g. 2023/102938/07).

6. On-Site Invoicing & Paystack Integration

Upon customer sign-off on glass, FieldControl compiles labor hours, callout fees, parts consumed, and standard 15% South African VAT into an instant invoice:

POST /api/invoices/create
{
  "work_order_id": "WO-1049",
  "customer_name": "Discovery Health Towers",
  "labor_amount_zar": 950.00,
  "callout_fee_zar": 450.00,
  "parts_amount_zar": 491.00
}

The system returns a payment link redirecting the customer to a secure Paystack checkout supporting Instant EFT, Capitec Pay, and credit cards.

7. REST API Endpoints Reference

© 2026 TVB Network (Pty) Ltd. FieldControl ZA Technical Documentation