Intermediary Architectural Specifications

This application serves as an active hardware-agnostic orchestration layer. It bridges the gap between physical biometric/RFID edge data capture devices deployed throughout corporate departments and the central corporate directory. The service normalizes variant payload fabrics, applies business verification interval logic, and continuously relays uniform employee activity profiles downstream.

🛠️ Edge Hardware Topology & Field Integration

To accommodate diverse architectural layouts, clean office aesthetics, and remote connectivity demands outside local area networks, the framework natively accepts connections from three discrete hardware tiers via public Wi-Fi infrastructure:

Tier 1: Custom Invisible Nodes (ESP32)

Microcontrollers are programmed using the Arduino IDE or MicroPython. Upon card presentation to the hidden RC522 RFID card scanner, the microchip utilizes its internal Wi-Fi antenna to wrap the raw UID string into an HTTP POST JSON block, hitting our public API gateway directly.

Tier 2: Commercial Clocks (ZKTeco ADMS)

Biometric devices must be configured via their internal menus to operate in ADMS / Push HTTP Mode. Rather than writing into an isolated local access database, the clock automatically initiates periodic connections over public networks using proprietary tab-separated plain text packets.

Tier 3: Enterprise Hubs (Suprema BioStar)

Ultra-slim minimalist access bars stream validation events locally into a secure central BioStar 2 server controller daemon. The BioStar daemon is configured to intercept internal events and cleanly broadcast standard JSON webhooks to our middleware endpoint.

🚀 Upstream Parent System Reporting Engine

Rather than overwhelming your core corporate tracking layer with unverified, hyper-frequent card-reader raw records, this service parses and filters transactions in real time using a custom evaluation engine.

Phase 3 Rules & Status Calculation: When an employee interacts with any reader, their identifier is checked against the cached master roster. The engine assesses the department context and transitions the user's registry to an "Active" state. This state remains valid for a designated interval (e.g., 2 to 4 hours) based on departmental policy.

Once statuses are verified and packaged, the app issues an authenticated outbound REST transmission to the target parent endpoint. Built-in network error isolation ensures that if the parent system experiences temporary latency or downtime, the edge hardware receivers catch a prompt local 200 OK response, preventing access bottlenecks or queue locks at terminal physical gates.

📡 Edge Device Ingestion Endpoints

POST

/api/ingest/esp32/

Target: Custom Wi-Fi Modules (JSON)

Request Format (application/json)

{
  "card_uid": "A1B2C3D4",
  "location": "Front_Office"
}

Synchronous Client Response

{
  "status": "success",
  "message": "Ping recorded"
}

Integration & Simulation Command

Simulate real-time ESP32 edge module pings directly from your client console shell:

curl -X POST https://employee-monitoring.titangrid.live/api/ingest/esp32/ \
     -H "Content-Type: application/json" \
     -d '{"card_uid": "A1B2C3D4", "location": "Front_Office"}'

POST

/api/iclock/cdata/

Target: ZKTeco ADMS Firmware Protocol

Request Format (text/plain)

⚠️ Warning: Fields must be sequentially divided strictly by tab bytes (\t).

USER PIN=123	Card=A1B2C3D4	Time=2026-06-10 10:00:00

Hardware Response Envelope

OK
Success: Card A1B2C3D4 was successfully processed.

Integration & Simulation Command

Simulate a raw data push packet mimicking structural commercial-grade standard terminals:

curl -X POST https://employee-monitoring.titangrid.live/api/iclock/cdata/ \
     -H "Content-Type: text/plain" \
     -d "USER PIN=123\tCard=A1B2C3D4\tTime=2026-06-10 10:00:00"

POST

/api/ingest/biostar/

Target: Suprema BioStar 2 Server Relay Webhook

Request Format (application/json)

{
  "Event": {
    "UserID": "888",
    "DeviceID": "Lobby_Suprema_XPass"
  }
}

Synchronous Webhook Response

{
  "status": "Webhook acknowledged"
}

Integration & Simulation Command

Execute a mock event log payload mapping directly to premium architecture topologies:

curl -X POST https://employee-monitoring.titangrid.live/api/ingest/biostar/ \
     -H "Content-Type: application/json" \
     -d '{"Event": {"UserID": "888", "DeviceID": "Lobby_Suprema_XPass"}}'

🗂️ Directory & Core Sync Operations

GET

/api/sync-employees/

Core Task: Directory Pull (JWT Authorized)

Triggers a multi-stage background synchronization pipeline task. The middleware generates a secure JSON Web Token via external authorization points and reads the active master employee directory to ensure edge hardware sweeps map accurately to actual user cards.

Sample Output Response

{
  "message": "Successfully fetched employee data using JWT.",
  "count": 1,
  "data": [
    {
      "employee_id": "EMP-001",
      "full_name": "Jacob Zulu",
      "department": "Front Office",
      "card_assignment_uid": "A1B2C3D4"
    }
  ]
}

🪪 Administrative Workflows & Card Enrollment

POST

/api/assign-card/

Core Task: Stateless Card Assignment Gateway

Protected endpoint restricted to authenticated administrators. It captures the physical card UID from a desktop USB HID reader and maps it to the selected employee ID, instantly forwarding the assignment to the parent system via a stateless proxy request.

Request Format (application/json)

{
  "employee_id": "EMP-001",
  "card_uid": "A1B2C3D4"
}

Synchronous Gateway Response

{
  "status": "success",
  "message": "Card A1B2C3D4 successfully assigned and saved in parent system directory."
}

USB HID Reader UI Implementation

Example frontend form utilizing keyboard emulation for seamless, click-free physical card enrollment:

<!-- The HID desktop scanner types the UID directly here -->
<input 
    type="text" 
    id="hid-card-input" 
    placeholder="Awaiting hardware swipe..." 
    autofocus
>

<script>
// Form automatically submits via Enter key sent by USB Reader
fetch('/api/assign-card/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + adminToken
    },
    body: JSON.stringify({
        employee_id: "EMP-001", // Selected via admin UI
        card_uid: document.getElementById('hid-card-input').value
    })
});
</script>