# GateFlow Setup Guide

Audience: client-side event staff using the official GateFlow Client.

This guide covers the real customer path only:

1. create your account or sign in on the website
2. create and prepare the operation on your GateFlow account, including generating an Operation Key
3. download GateFlow Client
4. open GateFlow Client on the Gate Device and paste the Operation Key
5. click **Activate Operation**. The Gate Device activates, downloads the operation, and becomes Ready for Offline Use in one guided step
6. approve scanners locally
7. run entry locally
8. click **End Operation** when the event is over

The Operation Key is the only way to set up a Gate Device. The Gate Device never asks for your GateFlow account email or password.

If you are setting up the website, Cloudflare, Paymob, or other internal systems, use [INTERNAL_SETUP_GUIDE.md](docs/INTERNAL_SETUP_GUIDE.md) instead.

## Before you start

Required:

- one Gate Device (any laptop, desktop, or mini PC running Microsoft Windows)
- the official GateFlow Client package
- a GateFlow account
- a count of how many admissions you need per ticket type (e.g. 10,000 General Admission, 500 VIP)
- staff phones on the same local Wi-Fi as the Gate Device

Not required:

- a guest list upload. GateFlow is admission-inventory based - it does NOT need guest names, emails, or phone numbers. Each QR admission is independently unguessable and gets distributed through your own channels (paper tickets, stickers, printed passes, wristbands, WhatsApp, Instagram, email, bank transfer, cash, your existing ticketing platform, anything you already use).

Helpful:

- `Start_GateFlow.bat`
- internet access for activation, preparation, reconnect checks, and sync. Internet is not required during live admissions after the Gate Device is prepared. Local Wi-Fi is still needed throughout the event so staff phones can reach the Gate Device.

## 1. Create your account and prepare the operation on the website

The account-side flow is five steps. Website prepares; Gate Device runs.

1. Open the GateFlow website, sign in, and open the account page.
2. **Operation**. Create the operation with the basics: name, date, venue.
3. **Access types**. Add one row per access type with a quantity - for example: `General Admission` 10,000, `VIP` 500, `Staff` 100, `Media` 50, `Sponsor` 30. No gates to configure here, no attendee-list upload, no names, no emails, no phone numbers.
4. **Generate**. Review the operation, the access types, the total admissions, and your available balance, then click **Generate admissions**. GateFlow mints that many unique, unguessable QR admissions.
5. **Export**. **Download CSV with links** (one row per admission with a unique `ticket_url` you can print on tickets, share over WhatsApp, paste into a CRM, or hand to any distribution tool) and **Download QR ZIP** (one printable SVG per admission, grouped by access type where practical). If you mint additional rows later, **Download latest generated batch** gives you a CSV and ZIP for just the rows you minted.
6. **Operation Key**. Generate the Operation Key, follow the activation checklist on screen, and paste the key into GateFlow Client on the Windows Gate Device. The Operation Key only allows a Gate Device to activate this operation, run admissions offline, and sync results back. It is not your account password and it cannot view billing, account settings, or other operations. It is shown once when you generate it - copy it then.

Before activation, you can still adjust this operation from your account. After the Operation Key is activated on a Windows Gate Device, the operation is finalized here so live entry runs from one consistent setup. The view-only summary keeps showing the operation details, the Gate Device status, the sync status, and the CSV / ZIP re-downloads for distribution.

To add more admissions before activation (extra General Admission batch, last-minute VIPs, additional staff, etc.), open the operation and use **Add more admissions** on the Access types step. GateFlow generates the new rows and keeps every existing admission intact. The latest-generated-batch downloads let you distribute only the rows you just minted. After activation, account-side admission changes go through support at `hello@gateflow.vip`; on-site emergency QR control (block / unblock) is available on the Gate Device dashboard.

GateFlow does not accept attendee-list uploads. Each admission is anonymous and tied to a unique QR; the operator distributes the QRs through whatever channel already works for the event (paper, stickers, badges, wristbands, links, your existing ticketing platform, etc.). GateFlow does not pick the channel.

Support if needed: the Help Center at [gateflow.vip/help](https://gateflow.vip/help) covers every part of GateFlow in plain language; for anything not answered there, email `hello@gateflow.vip`.

Every account includes 100 admissions each month so teams can explore GateFlow, test their setup, and prepare before live operations.

## 2. Activate the Gate Device

A Gate Device can be any laptop, desktop, or mini PC running Microsoft Windows.

1. Start `GateFlow.exe`.
2. On the first screen ("Activate Operation"), paste the **Operation Key** generated on your GateFlow account.
3. Click **Activate Operation**.

Activate Operation runs as a single guided step. The screen walks through Activating Operation Key, Binding this Gate Device, Downloading operation, and Preparing offline data, then shows **Ready for Offline Use**. The Gate Device contacts GateFlow once, exchanges the Operation Key for a device-scoped credential, downloads the operation your account prepared (admission inventory, QR signing key, and the admissions allocation for this Gate Device), and stores everything in the local SQLite store.

Time rule:

- the Gate Device uses its own local time for operation windows, scanning activity, and dashboard timestamps.
- confirm the Gate Device clock is correct before doors open.

Admission credentials are tied to the operation you prepared on the website. The Gate Device never authors admissions locally, and each QR is only valid for the operation it was issued under.

Important:

- No account email or password is ever requested on the Gate Device. The Operation Key is the only setup credential.
- The Operation Key is scoped to one operation and a limited number of Gate Devices. It cannot view billing, edit other operations, or sign you in to your GateFlow account.
- The Operation Key is shown once on the website. Copy it now. Before activation, if it is lost, regenerate on the website (this revokes the prior key). After a Gate Device activates the key, the operation is finalized on the account side; emergency Gate Device changes during a live operation go through support at `hello@gateflow.vip`.
- If the network drops between activation and downloading the operation, the screen offers **Retry preparation** so the Gate Device finishes setup without you having to enter the Operation Key again.
- After the first successful activation, live operation stays local on the Gate Device.

## 3. Approve scanners

Scanner phones do not become active automatically. Scanner approval stays local on the Gate Device. Phones reach the Gate Device over the venue's local Wi-Fi.

On each phone:

1. open the scanner URL shown in the dashboard
2. enter a scanner name or ID
3. choose the gate
4. tap `Request approval`

The Gate Device dashboard then shows that phone as `pending`.

From the dashboard, staff can:

- `Accept`
- `Decline`
- `Block`
- `Unblock`

Only `Accept` allows the phone to scan.

Important scanner rules:

- every phone must be approved from the local dashboard
- blocked phones cannot reconnect or scan until they are unblocked
- refreshing or reopening the scanner page sends that phone back through approval
- blocked scanners stay blocked until they are manually unblocked

Practical note:

- the first phone visit may show a browser trust warning because the scanner page uses local HTTPS
- the phone may also ask for camera permission

## 4. Run entry locally

Once the Gate Device is Ready for Offline Use and scanners are approved:

- validation happens locally
- duplicate protection happens locally
- scanner approval stays local
- per-device scan counters update locally
- the dashboard stays local
- the operation keeps running even if internet is unreliable

The dashboard shows:

- operation status
- inside now
- admitted
- pace per minute
- live scanner count
- per-gate admits and occupancy
- scanner device status and per-device scan counters
- sync state
- account admissions state

## 5. End the operation

When doors close:

1. Press **End Operation** on the Gate Device dashboard.
2. New admissions stop immediately. The final results are frozen locally.
3. The Gate Device auto-syncs the final results to the website.
4. Once the website accepts the sync, the operation moves to **closed** and consumption is committed against your account.

If the Gate Device is offline when you end the operation:

- it still ends locally and stops admitting.
- the dashboard shows **Pending Sync** until the Gate Device reconnects.
- once online, the sync finishes automatically and the operation moves to closed.
- no next production operation can be prepared on this Gate Device until the pending sync completes.

If the Gate Device is locked because of a tamper or integrity problem:

- **End Operation** still stops admissions immediately.
- the Gate Device displays "This Gate Device is locked until recovery is completed."
- prepare or start the next operation on another approved Gate Device, or contact support.

## 6. Understand confirmed admissions and usage

GateFlow uses confirmed admissions managed from the website account.

The usage rule is narrow:

`1 usage = the first successful admission of a unique QR for that operation`

These do not count again:

- duplicate scans
- denied scans
- retries
- re-entry

Important distinction:

- per-device scanner counters are operational only
- billable usage follows only the first-time unique admission rule

## 7. What happens if internet or confirmed admissions are an issue

If internet is unreliable:

- the active operation keeps running locally.
- scanner approval still works locally.
- validation still works locally.
- sync catches up later.

If confirmed admissions are low:

- the website and the client will warn you.
- the current operation can keep running.
- buy more confirmed admissions before the next production operation.

If confirmed admissions run out during a live operation:

- the active operation does not stop immediately.
- GateFlow Client keeps validating every QR locally against the prepared operation records and the configured rules. The Gate Device does not admit anyone whose QR is invalid, unknown, used, or blocked.
- once the Gate Device has admitted as many unique QRs as the last known confirmed-admission balance allowed for, further new admissions are refused and the scanner shows `Admissions full - top up`.
- exits, re-entries, duplicates, and blocked tickets still respond normally at the gate.
- buy more confirmed admissions before the next operation. The next Operation Key activation refreshes the balance for that operation.

## 8. Starting the next operation

Before the next operation:

1. end the previous operation locally and wait for it to reach **closed**.
2. prepare the new operation on the website and generate a new Operation Key for it.
3. paste the new Operation Key into GateFlow Client and click **Activate Operation**. The Gate Device activates against the new operation and becomes Ready for Offline Use in one step.

The previous admission inventory, QR signing key, and usage ledger are replaced by the newly prepared operation. Blocked scanners stay blocked. Non-blocked scanners must request approval again.

A Gate Device cannot prepare the next operation while the previous one is still **ended_pending_sync** or **locked**.

## 9. Event-day checklist

Before doors open:

1. confirm the operation is prepared on the website and an Operation Key has been generated
2. confirm the Gate Device is on the venue Wi-Fi
3. confirm staff phones are on the same local Wi-Fi as the Gate Device
4. paste the Operation Key into GateFlow Client and click **Activate Operation**. Wait for **Ready for Offline Use**.
5. keep the dashboard open on the Gate Device
6. share the scanner URL with staff
7. confirm each phone appears as `pending`
8. explicitly approve each phone before it scans
9. test one valid ticket and confirm:
    - the phone device counter changes
    - the dashboard shows the same device counter
    - the Admitted KPI on the dashboard increases by one

For quick answers during setup or event day, use [FAQ.md](FAQ.md).
