2. Architecture & How It Works

2.0 Data Flow

Understanding the data flow is essential before configuring anything.

Biometric Device (fingerprint / face / card / PIN)
        │
        │  punch event
        ▼
CAMS Biometric Gateway (cloud)
  ┌─────────────────────────────────────────┐
  │  Protocol Engine                         │
  │  - Translates device-specific protocols  │
  │  - Normalises JSON payload               │
  │  - Caches punches during outages         │
  │  - Validates AuthToken                   │
  └─────────────────────────────────────────┘
        │
        │  HTTP POST  →  your Callback URL
        │  (raw JSON, no auth headers needed)
        ▼
navari_cams_biometric — attendance() controller
  ┌─────────────────────────────────────────┐
  │  cams_call.py                            │
  │  1. Parse JSON body                      │
  │  2. Detect payload type:                 │
  │     a) RealTime PunchLog                 │
  │     b) PunchLog (historical batch)       │
  │  3. Validate AuthToken                   │
  │  4. Resolve UserID → Employee            │
  │  5. handle_attendance_log()  OR          │
  │     handle_punch_logs()                  │
  │  6. Create Employee Check-in record      │
  │  7. update_last_sync_time()              │
  │  8. Return {"status": "done"}            │
  └─────────────────────────────────────────┘
                      │
                      ▼
         FrappeHR — Employee Check-in
  ┌─────────────────────────────────────────┐
  │  Doctype: Employee Checkin              │
  │  - employee                             │
  │  - time                                 │
  │  - shift                                │
  │  - log_type (IN / OUT)                  │
  │  - custom_original_time (preserved UTC) │
  └─────────────────────────────────────────┘
                      │
                      ▼
           FrappeHR Attendance Processing
      (Shift Assignment → Attendance → Payroll)

2.1 Two Payload Paths

The CAMS Gateway delivers punches in two different JSON formats, and the app handles both:

• RealTime Path: used for live punches. The device fires a callback the moment someone punches. Payload contains a single RealTime.PunchLog object.
• PunchLog Path: used for historical retrieval via the "Load Punchlog" button. The CAMS API returns a batch PunchLog.Log array with multiple entries.

The attendance() controller in cams_call.py inspects the incoming payload and routes it to the correct handler function.