payfrit-beacon-ios/CLAUDE.md

Payfrit Beacon iOS

Native Swift iOS app for provisioning iBeacon hardware at restaurant tables. Repo: payfrit-beacon-ios on Forgejo.

Purpose

Utility app for restaurant setup staff to:

1. Scan for nearby BLE iBeacons (iBeacon + BLE + QR code)
2. Check UUID against known bulk manufacturer defaults (ban list)
3. Assign table names to beacons (smart-incremented)
4. Provision beacon hardware via BLE GATT (DX-Smart, BlueCharm, KBeacon)
5. Save beacon + auto-create service point records via API

Environment

• Server: dev.payfrit.com (DEBUG) / biz.payfrit.com (RELEASE)
• API Base: https://dev.payfrit.com/api (dev) / https://biz.payfrit.com/api (prod)
• Config: APIConfig.swift — uses #if DEBUG compiler flag
• OTP: Dev server uses magic OTP 123456 (no Twilio)

Database (via API — no direct SQL)

Table	PK	Key Columns
Beacons	ID	UUID, Name, BusinessID, IsActive
ServicePoints	ID	BusinessID, Name, TypeID, Code, SortOrder, IsActive, BeaconID
Businesses	ID	Name, ParentBusinessID

Note: POST /api/beacons/save.php auto-creates a ServicePoint when saving a beacon.

API Endpoints Used

All endpoints are .php. Auth = X-User-Token header.

Method	Endpoint	Auth	Purpose
POST	/auth/loginOTP.php	No	Send OTP to phone
POST	/auth/verifyLoginOTP.php	No	Verify OTP, get token
POST	/businesses/list.php	Yes	List user's businesses
POST	/servicepoints/list.php	Yes	List service points for business
POST	/servicepoints/save.php	Yes	Create/update service point
POST	/servicepoints/delete.php	Yes	Delete service point
POST	/beacon-sharding/allocate_business_namespace.php	Yes	Allocate UUID+Major shard
POST	/beacon-sharding/get_beacon_config.php	Yes	Get complete beacon config
POST	/beacon-sharding/allocate_servicepoint_minor.php	Yes	Auto-assign minor value
POST	/beacon-sharding/resolve_business.php	Yes	Resolve business by UUID+Major
POST	/beacons/list.php	Yes	List beacons for a business
POST	/beacons/lookupByMac.php	Yes	Lookup beacon by MAC address
POST	/beacons/wipe.php	Yes	Decommission a beacon
GET	/users/profile.php	Yes	Get user profile

Build & Deploy

Build in Xcode targeting iOS 17+. No local testing — deploy to device for BLE testing.

Project Structure

PayfritBeacon/
├── App/
│   ├── AppPrefs.swift              UserDefaults keys
│   ├── AppState.swift              ObservableObject — auth state, nav, business selection
│   └── PayfritBeaconApp.swift      App entry point
├── Models/
│   ├── BeaconConfig.swift          Provisioning config (UUID, major, minor, txPower, etc.)
│   ├── BeaconType.swift            Enum: DXSmart, BlueCharm, KBeacon, Unknown
│   ├── Business.swift              Business model
│   └── ServicePoint.swift          Service point model
├── Provisioners/
│   ├── ProvisionerProtocol.swift   Protocol — all provisioners implement this
│   ├── DXSmartProvisioner.swift    DX-Smart CP28 GATT provisioner (24-step write sequence)
│   ├── BlueCharmProvisioner.swift  BlueCharm BC037 provisioner
│   ├── KBeaconProvisioner.swift    KBeacon provisioner
│   ├── FallbackProvisioner.swift   Unknown device fallback
│   └── ProvisionError.swift        Shared error types
├── Services/
│   ├── APIClient.swift             Actor-based REST client, all API calls
│   ├── APIConfig.swift             Base URLs, timeouts, dev/prod toggle
│   ├── BLEManager.swift            CoreBluetooth scanning + beacon type detection
│   └── SecureStorage.swift         Keychain-based token storage
├── Utils/
│   ├── BeaconBanList.swift         Known bad UUID prefixes (factory defaults)
│   ├── BeaconShardPool.swift       64 Payfrit shard UUIDs
│   └── UUIDFormatting.swift        UUID string formatting extensions
└── Views/
    ├── BusinessListView.swift      Business selection screen
    ├── DevBanner.swift             Orange "DEV" banner overlay
    ├── LoginView.swift             OTP login screen
    ├── QRScannerView.swift         Camera-based QR code scanner for beacon pairing
    ├── RootView.swift              Root navigation
    └── ScanView.swift              Main scan + provision UI

Key Architecture Notes

• Modular provisioners: Each beacon manufacturer has its own provisioner conforming to ProvisionerProtocol. No more monolithic BeaconProvisioner.swift.
• Actor-based API: APIClient is a Swift actor (thread-safe by design).
• Secure storage: Auth tokens stored in Keychain via SecureStorage, not UserDefaults.
• BLE scanning: BLEManager handles CoreBluetooth device discovery and beacon type identification.
• DX-Smart protocol: 24-step write sequence including frames 3-6 disable (full Android parity).
• QR scanner: Camera-based QR code scanning for beacon pairing workflows.