# KPI Dashboard and Reporting

## Purpose

This document defines business, operational, and product metrics that can be built from the current backend model.

## Platform Business KPIs

| KPI | Why It Matters | Likely Data Source |
| --- | --- | --- |
| New estate signups | Measures pipeline creation | Estate signup status and created date |
| Approved signups | Measures sales/admin throughput | Estate signup status |
| Active estates | Measures paying customer base | Estate status and subscription status |
| Pending payments | Measures revenue stuck before activation | EstatePayment status |
| Confirmed payments | Measures collected revenue events | EstatePayment status and confirmedAt |
| Plan mix | Shows Starter, Growth, Enterprise distribution | Estate subscriptionPlan |
| Suspended estates | Flags churn or payment risk | Estate status |
| Sales admin activity | Tracks pipeline operations | AuditLog actor and action |

## Estate Operations KPIs

| KPI | Why It Matters | Likely Data Source |
| --- | --- | --- |
| Active residents | Indicates resident coverage | Resident status |
| Active guards | Indicates guard setup completeness | Guard status |
| Visitor passes created | Measures resident adoption | VisitorPass createdAt |
| Active visitor passes | Shows current expected traffic | VisitorPass status and validity window |
| Check-ins | Measures actual gate activity | VisitSession checkinTime |
| Checkouts | Measures exit compliance | VisitSession checkoutTime |
| Open visits | Finds visitors not checked out | VisitSession status |
| Denied or conflicted events | Highlights gate issues | VisitSession status, OfflineSyncItem conflict |
| Incidents logged | Tracks security events | Incident timestamp/type |

## Product Adoption KPIs

| KPI | Why It Matters |
| --- | --- |
| Residents creating passes | Shows resident adoption, not just admin setup |
| Guards using QR scan vs manual code | Shows quality of visitor pass usage |
| Offline sync usage | Shows connectivity or device behavior |
| Feature access changes | Shows estate customization demand |
| OTP login volume | Indicates active user base |
| Support tickets per active estate | Signals product friction |

## Dashboard Views

### Super Admin Dashboard

Recommended cards:

- total estates
- active estates
- pending signup reviews
- pending payments
- active users
- active residents
- active guards
- visitors today
- incidents this week
- recent audit logs

Recommended filters:

- date range
- estate status
- subscription plan
- payment provider
- signup status

### Sales Admin Dashboard

Recommended cards:

- new signups
- approved signups
- pending follow-up
- conversion to payment
- plan selection mix
- estates awaiting payment

Recommended table columns:

- estate name
- location
- unit count
- signup status
- plan selected
- selected payment provider
- created date
- last activity

### Estate Admin Dashboard

Recommended cards:

- residents
- guards
- visitors expected today
- visitors currently inside
- incidents this week
- expired or revoked passes

Recommended operational lists:

- open visits
- recent check-ins
- recent incidents
- guards by device
- active passes expiring soon

## Reporting Cadence

Daily:

- active estates with gate activity
- pending payments
- failed or conflicted offline sync
- open visits not checked out

Weekly:

- visitor volume by estate
- pass creation by residents
- incident summary
- guard activity summary
- sales pipeline progress

Monthly:

- active estate count
- revenue by plan
- payment provider distribution
- customer activity and churn risk
- support volume by estate

## Report Exports

Useful export types:

- estate resident list
- guard list and device assignments
- visitor pass history
- visit session log
- incident report
- payment confirmation report
- audit log report

Recommended export controls:

- restrict exports to authorized admins
- include date range filters
- include estate scope
- log export actions in audit logs
- avoid exporting secrets or OTP values

## Data Quality Checks

Monitor:

- residents without active linked users
- guards without device IDs where device tracking is required
- estates with active subscriptions but no recent activity
- payments pending for too long
- passes with validity windows in the past but still active
- visit sessions missing checkout after a defined time
- duplicate or conflicting offline client events