GFAVIP Perks Hub IT Guide

The GFAVIP Perks Hub is a new mini-app designed to enhance the GFAVIP Wallet ecosystem by introducing a dedicated platform for managing and redeeming tiered perks. This initiative aims to:

• Extend the existing wallet perks system (currently managed by team admins with redirect links) with complex, provider-verified perks (e.g., Easy China Warehouse discounts) and a new category-based browsing system (logistics, sourcing agent, broker, accounting).
• Drive member upgrades from free to paid tiers by offering tangible savings and benefits, with premium "highlight" perks (0 for Basic, 2 for Premium) to boost visibility and encourage provider upgrades.
• Integrate a campaign mode for events like the Cross Border Summit 2025, leveraging ticket validation for exclusive perks with local expiration tracking.
• Tease GFA Gems as a future ecosystem currency to boost long-term engagement.

The MVP targets a launch by October 29, 2025, with a live demo at the Summit (Nov 3-5), focusing on a mobile-friendly experience with live claims, mock redemptions, and category navigation.

The Perks Hub integrates seamlessly with the existing GFAVIP infrastructure, utilizing the following components:

• Wallet SSO (wallet.gfavip.com): Uses redirect-based authentication (GET /api/auth/sso/authorize) to pull user data (`username`, `user_id`, `tier`, `email`) via URL params. Highlights link to perks.gfavip.com via an optional GET /api/perks/highlights pull, extending the current perks management with a teaser layer.
• Ticket Validation (tickets.gfavip.com): Integrates GET /api/tickets to gate campaign perks (e.g., CBS) based on paid ticket status, with expiration dates stored locally in the database.
• Checkout (checkout.gfavip.com): Handles provider payment processing, offering an upsell link if the user isn’t a service provider, redirecting to payment for Basic or Premium tiers.
• Database (Neon PostgreSQL): Features a new local schema with tables for users, providers, perks (including categories and highlights), coupons, and redemptions. Syncs key fields (`username`, `user_id`, `tier`, `email`) with wallet.
• Emails: Automated notifications for claim confirmations, expiry warnings, and consent requests using Flask-Mail.

Key APIs to implement: Perks.gfavip.com exposes GET /api/perks/highlights; wallet handles redirects to the mini-app.

The development roadmap outlines phased enhancements post-MVP:

• V1.1 (Post-Launch): Enable full Gems functionality (redemptions, provider raffles) and admin capability to revoke provider perks.
• V1.2 (Q1 2026): Add analytics for perk usage (e.g., upsell triggers) and fully migrate bonus.crossbordersummit.com into the mini-app.
• V2.0 (Mid-2026): Transition GFA Gems to a web3 token for ecosystem-wide use, enhancing scalability and value, with adjustable highlight limits.

Risks include API sync delays (manual fallback planned) and mobile UI responsiveness (to be tested pre-demo). The Replit agent will handle initial DB/API setup, with testing focused on end-to-end flows, category filtering, and highlight display.