Athenian Geotracking

Developer starting point

This baseline documents location storage and mapping code. It does not claim an external geocoder response, consent flow, or production location capture has been exercised.

Admin Workflow

1. Install and Activate

When the plugin is activated, it creates the custom tracking table used to store technician location records.

2. Configure Google Maps

An administrator adds a Google Maps JavaScript API key on the plugin settings screen.

3. Connect a Field Client

A technician-facing mobile app, browser workflow, or companion tracking service sends location updates to the plugin's REST endpoint.

4. Monitor the Technician Map

Operations staff open the Technician Map inside the WordPress admin. The map loads recent technician data and refreshes automatically.

5. Use Visibility for Dispatch Decisions

Dispatchers can use the live map as an operational reference when assigning services, checking availability, reviewing field coverage, or coordinating support.

---

Customer / Technician Workflow

The current plugin does not include a bundled customer-facing or technician-facing frontend interface. It is designed to receive technician location updates from an external field client.

A typical technician workflow would be:

1. Technician logs into a mobile app or technician dashboard.
2. The client obtains permission to access device location.
3. The client periodically posts GPS coordinates, speed, heading, and status to the REST endpoint.
4. Athenian Geotracking updates the technician's latest location record.
5. Admin users see the technician's current field presence on the map.

This separation keeps the WordPress plugin focused on ingestion, storage, and admin visibility while allowing the technician experience to be implemented in a mobile app, Unÿa technician dashboard, or other field client.

---

Technical Architecture

Plugin Bootstrap

Primary file:

athenian-geotracking.php

The plugin defines core constants:

• ATHENIAN_GEO_VERSION
• ATHENIAN_GEO_FILE
• ATHENIAN_GEO_DIR
• ATHENIAN_GEO_URL

It initializes a namespaced autoloader and boots the main plugin orchestrator on plugins_loaded.

Main Orchestrator

Primary class:

Athenian\Geo\Core\Plugin

Responsibilities:

• Instantiate REST API handler
• Instantiate admin map handler
• Instantiate settings handler
• Register REST routes on rest_api_init
• Boot admin screens and settings

REST API Layer

Primary class:

Athenian\Geo\Core\Rest_Api

Namespace:

athenian-geo/v1

Routes:

| Method | Route | Purpose | Permission | |---|---|---|---| | POST | /technician-location | Receive technician location updates | Current implementation uses open development callback | | GET | /technicians | Return recent technician location records | manage_options |

The REST layer validates required fields, normalizes optional heading/speed values, stores updates through the locations table class, and returns normalized JSON responses.

Database Layer

Primary class:

Athenian\Geo\Core\Locations_Table

Responsibilities:

• Resolve custom table name
• Create the table on activation
• Upsert latest technician location
• Retrieve recent technician locations with optional status filtering

Admin Map Layer

Primary class:

Athenian\Geo\Admin\Admin_Map

Responsibilities:

• Register the Technician Map admin page
• Enqueue Google Maps when configured
• Enqueue admin CSS and JavaScript
• Localize REST URL, nonce, default filters, and map defaults
• Render the map container and missing-key notice

Settings Layer

Primary class:

Athenian\Geo\Admin\Settings

Responsibilities:

• Register the Google Maps API key option
• Add the settings section and field
• Render the settings page under WordPress Settings

Autoloader

Primary class:

Athenian\Geo\Includes\Autoloader

The autoloader maps the Athenian\Geo\ namespace to the plugin's local core, admin, and includes-style directories. The implementation uses lowercased relative paths and underscore-based filenames for the currently loaded class files.

---

Data Model

Custom Table

Table name:

{$wpdb->prefix}ath_geo_locations

Table Columns

| Column | Type | Purpose | |---|---:|---| | id | bigint unsigned | Auto-incrementing row ID | | technician_id | bigint unsigned | Technician post ID, intended to reference a Unÿa technician record | | lat | double | Latest latitude | | lng | double | Latest longitude | | heading | float NULL | Optional movement heading | | speed | float NULL | Optional movement speed | | status | varchar(32) | Technician state such as available, busy, or offline | | updated_at | datetime | Last update timestamp |

Indexes

| Index | Purpose | |---|---| | Primary key on id | Unique row identity | | Key on technician_id | Faster technician-specific updates/lookups | | Key on updated_at | Recent activity filtering |

Configuration Option

| Option | Purpose | |---|---| | ath_geo_google_maps_api_key | Stores the Google Maps JavaScript API key used by the admin map |

---

REST API Details

Update Technician Location

POST /wp-json/athenian-geo/v1/technician-location

Example payload:

{
  "technician_id": 123,
  "lat": 36.1627,
  "lng": -86.7816,
  "heading": 180,
  "speed": 22.4,
  "status": "available"
}

Example response:

{
  "success": true,
  "technician_id": 123,
  "lat": 36.1627,
  "lng": -86.7816,
  "status": "available",
  "updated_at": "2026-07-01 10:30:00"
}

Required fields:

• technician_id
• lat
• lng

Optional fields:

• heading
• speed
• status

Default status:

available

List Recent Technician Locations

GET /wp-json/athenian-geo/v1/technicians?minutes_recent=30&status=available

Example response:

[
  {
    "technician_id": 123,
    "name": "Technician Name",
    "lat": 36.1627,
    "lng": -86.7816,
    "heading": 180,
    "speed": 22.4,
    "status": "available",
    "updated_at": "2026-07-01 10:30:00"
  }
]

The endpoint resolves each technician_id with get_post() and uses the post title as the displayed technician name when available.

---

WordPress Hooks and Integration Points

Hooks Used

| Hook | Purpose | |---|---| | plugins_loaded | Boot the main plugin orchestrator | | rest_api_init | Register geotracking REST routes | | admin_menu | Add admin map/settings menu entries | | admin_enqueue_scripts | Load map CSS/JS only on the map screen | | admin_init | Register settings fields/options | | register_activation_hook | Create the geotracking custom table |

External Services

| Service | Purpose | |---|---| | Google Maps JavaScript API | Admin map rendering | | WordPress REST API | Field-client ingestion and admin retrieval |

Athenian Platform Touchpoints

Athenian Geotracking is built to support the Athenian Unÿa service stack. The current implementation assumes technician IDs can be resolved as WordPress posts, which aligns with a Unÿa-style technician data model. It is most naturally paired with:

• Athenian Unÿa service booking
• Technician dashboards or mobile apps
• Dispatch/admin workflows
• Service order assignment tools
• Customer ETA and notification systems
• Future route optimization or availability logic

---

Security and Permissions Notes

The current implementation includes two permission paths:

• GET /technicians is restricted to users with manage_options.
• POST /technician-location currently uses __return_true as its permission callback, with an inline development note indicating no authentication is required.

A can_update_location() method exists and checks for logged-in users with the read capability, but it is not currently assigned to the update route.

Before production deployment, the update endpoint should be hardened. Recommended production approaches include:

• Require authenticated technician users.
• Validate that the authenticated user is allowed to update the submitted technician_id.
• Use application passwords, JWT, OAuth, or a signed request token for mobile clients.
• Add nonce verification for browser-based technician dashboards.
• Add rate limiting or request throttling.
• Validate coordinate ranges.
• Sanitize and constrain accepted status values.
• Log rejected requests for operational review.

This plugin has the right architectural separation for production security, but the location-ingestion permission callback should be treated as a development-mode implementation until hardened.

---

Implementation Observations

Duplicate File Naming Patterns

The ZIP includes both hyphenated and underscored versions of some class files:

admin/admin-map.php
admin/admin_map.php
core/locations-table.php
core/locations_table.php

The autoloader currently resolves the loaded class names to underscore-style files such as:

admin/admin_map.php
core/locations_table.php

The duplicate files appear to be legacy or compatibility copies. They should be reviewed and consolidated to reduce maintenance ambiguity.

Upsert Behavior

Locations_Table::upsert_location() attempts an update first and inserts if the update reports false or 0 affected rows. Because $wpdb->update() can return 0 when a matching row exists but the values did not change, repeated identical updates could potentially create duplicate technician rows unless the database table has a unique technician constraint.

Recommended improvement:

• Add a unique key on technician_id if the table is intended to store one latest row per technician.
• Change insert fallback logic to only insert when no existing technician row exists.
• Consider using explicit select-then-update/insert logic or SQL ON DUPLICATE KEY UPDATE with a unique key.

Coordinate Validation

Current validation checks that technician ID, latitude, and longitude are present, but it treats falsy numeric values as invalid. That means valid coordinates such as 0 could fail validation. While this may not matter for the intended U.S. service footprint, a production-grade global implementation should use range-aware validation:

• Latitude between -90 and 90
• Longitude between -180 and 180
• Technician ID greater than 0

Admin UX

The admin interface is intentionally lightweight. It provides the map container and missing-key warning, while the JavaScript handles map initialization, marker rendering, and refresh behavior. This keeps the first version simple while leaving room for richer filters, technician panels, route overlays, and assignment actions.

---

Technical Strengths

• Clean separation between bootstrap, REST API, database table, settings, and map UI.
• Uses a dedicated custom table instead of overloading post meta for high-frequency location state.
• Provides a simple REST contract that can be consumed by mobile apps or field clients.
• Limits the admin retrieval endpoint to administrators.
• Loads Google Maps only when the admin map page is active.
• Provides a warning when Google Maps is not configured.
• Uses recent/status filters to keep the admin map focused on operationally relevant technicians.
• Provides a strong foundation for Unÿa dispatch, technician, and field-service workflows.

---

Example Implementation Scenario

A mobile nail service operation uses Athenian Unÿa to manage bookings and technician assignments. Technicians check in through a mobile dashboard that sends location updates every few minutes while they are active. A dispatcher opens the Technician Map in WordPress and sees available technicians near upcoming appointment locations. Instead of texting the team for updates, the dispatcher can make assignment decisions with live field context already visible in the admin workflow.

---