# User Personas and Workflows

## Platform Roles

| Role | Scope | Main Responsibilities |
| --- | --- | --- |
| Super Admin | Platform-wide | Manage estates, payments, plans, providers, OTP settings, integrations, users, and feature access |
| Sales Admin | Platform-wide | View estate pipeline, support sales/onboarding, inspect approved operational data where enabled |
| Estate Admin | Estate-scoped | Manage residents, guards, estate operations, feature settings, visitors, passes, incidents, and reports |
| Security Supervisor | Estate-scoped | Manage guards, view residents, review visitors, revoke passes, review incidents |
| Guard | Estate-scoped | Check visitors in/out, use QR/manual codes, sync offline data, report incidents |
| Resident | Estate-scoped | Create visitors and visitor passes, view own relevant records |

## Persona: Super Admin

Goals:

- control platform operations
- approve estates before activation
- confirm payments
- manage pricing and payment providers
- monitor usage and audit logs

Key workflows:

- review estate signup
- approve or reject estate
- configure payment providers
- confirm payment and activate estate
- manage subscription plans
- manage role feature settings

Success metrics:

- pending signups reviewed quickly
- payment confirmations completed accurately
- active estates increasing
- low support escalations from onboarding

## Persona: Estate Admin

Goals:

- keep resident and guard records accurate
- reduce gate delays
- monitor incidents and visitor activity
- ensure only authorized users access estate workflows

Key workflows:

- add residents
- add guards and assign devices
- view visitor passes and sessions
- manage incidents
- configure supported estate features for residents and guards

Success metrics:

- fewer resident complaints
- complete resident list
- guards using digital check-in
- clear incident history

## Persona: Guard

Goals:

- validate visitors quickly
- avoid admitting unauthorized visitors
- keep records accurate during busy periods
- keep working when internet is unstable

Key workflows:

- scan QR pass
- enter manual visitor code
- check visitor in
- check visitor out
- report incident
- sync offline events

Success metrics:

- short visitor wait time
- low denied/invalid pass confusion
- no lost visit logs during connectivity issues
- accurate guard/device attribution

## Persona: Resident

Goals:

- invite visitors without repeated phone calls
- avoid delays for expected visitors
- revoke or limit visitor access when needed

Key workflows:

- create visitor profile
- create visitor pass
- share QR/manual code
- review visitor pass status

Success metrics:

- successful visitor entry
- low gate follow-up calls
- clear pass validity and usage

## Core Workflow: Estate Onboarding

1. Estate admin submits public signup with estate and admin details.
2. Estate is created as `PENDING`.
3. Estate admin account is created but suspended.
4. Super admin reviews the signup.
5. Super admin approves, rejects, or suspends the signup.
6. Approved estate selects a plan and payment provider.
7. Estate initializes hosted checkout or records manual payment.
8. Super admin confirms payment.
9. Estate status changes to `ACTIVE`.
10. Estate admin account becomes active.

## Core Workflow: Visitor Pass Creation

1. Resident or estate admin creates a visitor profile.
2. Resident or estate admin creates a pass.
3. System generates QR token and manual visitor code.
4. Pass is assigned a validity window and pass type.
5. Visitor receives access details outside the backend workflow.
6. Guard validates pass at the gate.

## Core Workflow: Gate Check-In

1. Visitor arrives at the gate.
2. Guard scans QR token or enters manual visitor code.
3. System verifies pass status, validity window, estate scope, and entry limit.
4. System records visit session with guard, device, and gate context.
5. Entry count is updated.
6. Pass status changes when usage limit is exhausted.

## Core Workflow: Checkout

1. Visitor leaves the estate.
2. Guard finds active visit session.
3. Guard records checkout.
4. System stores checkout time and exit gate.
5. Audit log captures the action.

## Core Workflow: Offline Gate Operation

1. Guard device bootstraps active pass and resident data.
2. Device handles check-in events during connectivity issues.
3. Device submits offline events when connectivity returns.
4. Backend applies valid events.
5. Conflicted events are marked for review.

## Core Workflow: Incident Reporting

1. Guard or supervisor creates incident.
2. Incident is linked to estate and guard.
3. Metadata can capture extra context.
4. Estate admin or supervisor reviews the record.
5. Follow-up can be handled through operations process.