# Awda Platform

> Digital loyalty program infrastructure in Saudi Arabia operating natively within Apple Wallet and Google Wallet, eliminating the need for standalone mobile apps.

## System Overview

Awda is a multi-tenant loyalty platform built for retail businesses, cafes, salons, and clinics. Customers scan branch-specific QR codes to register, save dynamically generated pass bundles to their default wallet (Apple Wallet on iOS or Google Wallet on Android), and track their points, stamps, or cashback balances in real time.

---

## Architectural Layout

The platform is split into:
*   **Web Application (Next.js)**:
    *   `/apps/brand`: Brand administration dashboard and staff-facing operations panel.
    *   `/apps/web`: Corporate landing pages and SEO-optimized platform marketing.
*   **Core Packages**:
    *   `/packages/google-wallet`: Node wrapper for Google Wallet REST APIs, handling Class and Object creation, campaign templates, and updates.
    *   `/packages/apple-pass`: Builder engine for signing and packaging `.pkpass` files for iOS clients.

---

## Core Database Schema (Prisma)

Important data entities used across transactions and APIs:
*   `Business`: Stores brand-specific configurations, including primary colors, logo texts, and wallet integrations.
*   `Pass`: Defines active program types (`STAMPS`, `POINTS`, `VISITS`, `CASHBACK`), configuration boundaries (stamps required, cashback percentage), and layouts.
*   `CustomerPass`: Maps individual customer records to their issued wallet serial numbers, platform types (`ios` vs `google`), and dynamic balances.
*   `Transaction`: Ledger entries tracking balances, operations (`STAMP_ADD`, `STAMP_REMOVED`, `POINTS_ADD`, `POINTS_REMOVED`), branch locations, and staff actions.
*   `DeviceRegistration`: Maps Apple APNs push tokens to serial numbers for dynamic lock-screen updates.

---

## Core API Endpoints

### 1. Loyalty & Transactions

#### `POST /api/loyalty/stamps`
*   **Purpose**: Adds stamps to a customer's pass.
*   **Payload**: `{ phone: string, amount: number, branchId: string }`
*   **Notes**: Automatically triggers Apple APNs silent push updates and syncs Google Wallet object properties.

#### `DELETE /api/loyalty/stamps`
*   **Purpose**: Reverses/undos the last stamp addition.
*   **Payload**: `{ phone: string, branchId: string }`
*   **Notes**: Locates the most recent transaction entry matching the timestamp window, reverses the exact points ledger value, and posts a `STAMP_REMOVED` audit line.

#### `POST /api/loyalty/points`
*   **Purpose**: Increments points balance on a points-based pass.
*   **Payload**: `{ phone: string, amount: number, branchId: string }`

#### `POST /api/loyalty/cashback`
*   **Purpose**: Records customer purchases and adds cashback amounts in halalahs.
*   **Payload**: `{ phone: string, amount: number, branchId: string }`

#### `POST /api/loyalty/notify`
*   **Purpose**: Staff-initiated custom notification broadcast.
*   **Payload**: `{ message: string, passId: string }`
*   **Security**: Requires active staff credential validation (`!staff.isActive` block).

---

## Apple APNs & Google Wallet Sync Routines

*   **APNs Integration**:
    *   Sends silent push notifications to registered tokens.
    *   **Pruning**: Catch blocks capture `410 Gone` HTTP status responses from APNs, indicating that the customer has removed the pass, and delete the stale token record from `DeviceRegistration`.
*   **Google Wallet Sync**:
    *   Direct REST updates via `GoogleWalletClient`.
    *   Auth error bubbles check for genuine `403` credentials and prevent resource overlaps.
    *   Uses campaign Class-level templates for bulk user messaging.