Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/edgar2420/QrPermision/llms.txt

Use this file to discover all available pages before exploring further.

PermisosQR ships two reporting surfaces: a live dashboard that auto-refreshes every 30 seconds and gives a real-time snapshot of the whole operation, and a summary report with full date-range filtering for historical analysis. Together they answer the questions operators care about most — how many QR codes are in use right now, how many employees came back on time, which operators process the most permissions, and at what times of day activity peaks. All statistics are computed directly from the PostgreSQL database in parallel queries, keeping response times low even as the permission log grows.

​
Dashboard Stats

GET /api/reports/dashboard executes four database queries in parallel via Promise.all and returns their results as a single object. No query parameters are accepted — the dashboard always reflects the full dataset as of the moment of the request. API reference 
curl http://localhost:4000/api/reports/dashboard \
  -H "Authorization: Bearer <token>"
Full response shape 
{
  "success": true,
  "data": {
    "qr": {
      "available": "142",
      "active": "7",
      "expired": "0",
      "disabled": "3",
      "total": "152"
    },
    "permissions": {
      "total_permissions": "1048",
      "compliant": "931",
      "non_compliant": "117",
      "active_now": "7",
      "overdue": "2"
    },
    "averages": {
      "avg_time_used": "18.43",
      "avg_delay": "1.07",
      "avg_allowed": "16.25"
    },
    "recent_activity": [
      {
        "id": 1048,
        "qr_id": 12,
        "received_by": "Carlos Quispe",
        "allowed_minutes": 15,
        "exit_time": "2024-06-15T14:22:00.000Z",
        "return_time": "2024-06-15T14:38:00.000Z",
        "time_used_minutes": "16.00",
        "delay_minutes": "1.00",
        "is_compliant": false,
        "enabled_by_name": "Operador Sur"
      }
    ]
  }
}
Field reference

qr

Live count of every QR code in each status bucket, plus the grand total. Reflects the qr_codes table in real time.

permissions

All-time permission tallies including how many are currently open (active_now) and how many are overdue right now.

averages

Mean time_used_minutes, delay_minutes, and allowed_minutes across all completed permissions only. Values are rounded to 2 decimal places.

recent_activity

The five most recently created permissions (regardless of status), enriched with the enabling operator’s name.
All three average fields (avg_time_used, avg_delay, avg_allowed) are computed exclusively from rows where return_time IS NOT NULL. Open permissions — those still in progress — are excluded from the average calculations to avoid skewing results with incomplete data.
The frontend dashboard component polls this endpoint automatically every 30 seconds using a setInterval hook, ensuring the counters stay current without a manual refresh.

​
Summary Report

GET /api/reports/summary returns aggregate statistics filtered by an optional date range. It is designed for end-of-shift or end-of-period review and is accessed from the Reports screen in the frontend. Query parameters
ParameterTypeDescription
startDatestring (ISO 8601)Include permissions with created_at ≥ startDate
endDatestring (ISO 8601)Include permissions with created_at ≤ endDate
If neither parameter is supplied, the report covers all time. API reference 
curl "http://localhost:4000/api/reports/summary?startDate=2024-01-01&endDate=2024-12-31" \
  -H "Authorization: Bearer <token>"
Full response shape 
{
  "success": true,
  "data": {
    "summary": {
      "total": "1048",
      "compliant": "931",
      "non_compliant": "117",
      "avg_time": "18.43",
      "avg_delay": "1.07",
      "max_delay": "47.25"
    },
    "by_admin": [
      { "name": "Operador Norte", "total": "412", "compliant": "389" },
      { "name": "Operador Sur",   "total": "388", "compliant": "321" },
      { "name": "Operador Este",  "total": "248", "compliant": "221" }
    ],
    "hourly_distribution": [
      { "hour": "7",  "total": "38"  },
      { "hour": "8",  "total": "127" },
      { "hour": "9",  "total": "203" },
      { "hour": "10", "total": "188" },
      { "hour": "12", "total": "91"  },
      { "hour": "13", "total": "145" },
      { "hour": "17", "total": "256" }
    ]
  }
}
Response field reference
FieldDescription
summary.totalTotal permission count in the date range
summary.compliantPermissions where is_compliant = true
summary.non_compliantPermissions where is_compliant = false
summary.avg_timeAverage time_used_minutes (2 decimal places)
summary.avg_delayAverage delay_minutes across all permissions
summary.max_delayWorst single delay in the period (2 decimal places)
by_adminTop 10 operators ranked by total permissions processed, with individual compliance counts
hourly_distributionPermission counts grouped by the hour component of exit_time — useful for identifying peak exit windows

​
Overdue Detection

The dashboard’s overdue count surfaces a critical real-time metric: permissions where an employee has not yet returned and their allowed time has already elapsed. The SQL condition used is: 
COUNT(*) FILTER (
  WHERE return_time IS NULL
    AND exit_time < NOW() - INTERVAL '1 minute' * allowed_minutes
) AS overdue
In plain terms: a permission is overdue when the QR is still active (no return has been recorded) and the current time is past the originally authorized deadline. For example, if an employee was granted 15 minutes starting at 09:00 and it is now 09:18 with no return recorded, that permission counts as overdue.
The overdue count is computed at query time — it is only as current as the last dashboard refresh. The frontend refreshes every 30 seconds, so the worst-case lag before an overdue permission appears on the dashboard is 30 seconds. For immediate visibility, use the QR Management screen, which shows a live per-second elapsed timer on every active QR row.

​
Frontend Reports Screen

The Reports page (/reports) in the React frontend presents the summary data with two side-by-side visualizations:

Hourly Distribution Chart

A horizontal bar chart showing permission counts for each hour of the day the exit_time falls in. Bars are scaled relative to the busiest hour, with the count displayed inside each bar. Only hours with at least one permission appear.

By-Operator Table

A ranked list of the top 10 operators (by total permissions). Each row shows the operator’s compliance rate as an inline progress bar, their total permissions, and a compliance percentage.
Date range filtering is available via two date-picker inputs at the top of the page. Clicking Filtrar re-fetches the summary for the selected window. Leaving both inputs empty resets to the all-time view.

Build docs developers (and LLMs) love

Get started for freeTalk to us