---
title: "2. Architecture & How It Works"
space: "CAMS Biometric Integration"
url: "https://docs.navari.co.ke/cams-biometric/architecture-how-it-works"
updated: "2026-05-27"
---

### 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.