Skip to content

overview.md

Latest commit

 

History

History
974 lines (617 loc) · 11.6 KB

overview.md

File metadata and controls

974 lines (617 loc) · 11.6 KB
Raw

GeoQuest — Full Project Overview

Project Summary

GeoQuest is a location-based exploration and rewards platform built as a MiniPay Mini App on the Celo ecosystem.

The product combines:

  • real-world exploration,
  • merchant-sponsored foot traffic campaigns,
  • GPS verification,
  • gamified trails,
  • NFT collectibles,
  • and instant cUSD rewards.

Players physically move through real neighborhoods completing quests at sponsored locations. Merchants fund reward pools to attract verified visitors. The platform coordinates movement, verification, payouts, analytics, and progression.

The experience should feel like:

  • a real-world adventure game,
  • mixed with local discovery,
  • powered invisibly by Web3 infrastructure.

The crypto layer should remain mostly abstracted from users.

Core Vision

GeoQuest transforms cities into playable economic networks.

The platform’s primary objective is:

incentivizing real-world movement and local commerce through gamified exploration.

The deeper business objective is:

building a programmable proof-of-presence advertising and loyalty network.

Product Goals

Player Goals

Players should be able to:

  • discover nearby trails,
  • physically visit locations,
  • complete challenges,
  • earn stablecoin rewards,
  • collect NFT stamps,
  • compete socially,
  • and explore their city in a fun way.

Merchant Goals

Merchants should be able to:

  • create sponsored stops or trails,
  • fund reward pools,
  • attract local visitors,
  • track verified foot traffic,
  • launch campaigns quickly,
  • and measure ROI.

Platform Goals

GeoQuest should:

  • onboard users into MiniPay,
  • drive real-world activity,
  • generate merchant revenue,
  • maintain low fraud,
  • scale city-by-city,
  • and create a sticky gameplay loop.

Product Category

GeoQuest belongs to:

  • Location-Based Gaming
  • Move-to-Earn
  • GameFi
  • Local Commerce Infrastructure
  • Proof-of-Presence Advertising
  • Gamified Loyalty Systems

Primary User Personas

1. Explorer Player

Age: 18–35

Motivations:

  • earning small rewards,
  • discovering places,
  • social competition,
  • collecting badges,
  • exploring neighborhoods.

Behavior:

  • completes trails,
  • shares progress,
  • competes with friends,
  • returns weekly.

2. Local Merchant

Examples:

  • cafés,
  • restaurants,
  • bookstores,
  • markets,
  • gyms,
  • bars,
  • event venues.

Motivations:

  • more foot traffic,
  • customer discovery,
  • measurable marketing ROI,
  • repeat visits.

Behavior:

  • funds campaigns,
  • tracks analytics,
  • rotates offers,
  • creates promotions.

3. Trail Creator / Ambassador

Motivations:

  • city exploration,
  • community building,
  • earning commissions,
  • curating experiences.

Behavior:

  • designs trails,
  • writes trivia,
  • recruits merchants,
  • moderates content.

Core Product Concept

The platform revolves around:

Trails

A trail is:

  • a sequence of real-world stops,
  • grouped by a theme,
  • connected through map navigation,
  • funded by merchants or sponsors.

Examples:

  • Coffee Crawl
  • Historical Downtown Trail
  • Art Gallery Quest
  • Weekend Food Trail
  • Music Festival Hunt
  • University Campus Quest

Each trail contains:

  • multiple stops,
  • challenges,
  • rewards,
  • and collectibles.

Core Gameplay Loop

Player Flow

Step 1 — Open Mini App

Player launches GeoQuest inside MiniPay.

App requests:

  • wallet access,
  • GPS permission,
  • optional notifications.

Step 2 — Browse Nearby Trails

Player sees:

  • map of nearby quests,
  • reward amounts,
  • estimated duration,
  • difficulty,
  • popularity,
  • categories.

Step 3 — Select Trail

Trail details include:

  • total stops,
  • distance,
  • estimated reward,
  • merchants involved,
  • special NFTs,
  • time remaining.

Step 4 — Navigate to Stop

Player physically walks toward destination.

Map updates live using GPS.

When inside geofence radius:

  • stop unlocks,
  • challenge activates.

Step 5 — Complete Challenge

Possible challenge types:

  • QR scan,
  • trivia,
  • photo upload,
  • NFC tap,
  • code entry,
  • merchant interaction.

Challenge completion triggers:

  • verification,
  • backend validation,
  • NFT mint eligibility.

Step 6 — Receive Stamp

Player receives:

  • NFT location stamp,
  • XP points,
  • leaderboard progression.

Step 7 — Complete Full Trail

After all stops:

  • cUSD payout released,
  • special achievement unlocked,
  • progression updated.

Merchant System

Merchant Registration

Merchant creates account through dashboard.

Merchant onboarding includes:

  • business name,
  • category,
  • address,
  • GPS coordinates,
  • operating hours,
  • logo/images,
  • payout wallet.

Merchant Features

Create Stops

Merchant defines:

  • stop location,
  • challenge type,
  • rewards,
  • active hours,
  • promotions.

Fund Reward Pools

Merchant deposits:

  • cUSD budget,
  • daily cap,
  • reward-per-user.

Smart contract escrows funds.

Analytics Dashboard

Merchant sees:

  • total visits,
  • verified visits,
  • trail completions,
  • repeat visitors,
  • conversion rates,
  • active campaigns.

Promotional Offers

Merchant can attach:

  • discounts,
  • free items,
  • QR coupons,
  • loyalty bonuses.

Reward System

Reward Types

Stablecoin Rewards

Primary currency:

  • cUSD

Reward models:

  • fixed payout,
  • pooled payout,
  • bonus streak rewards.

NFT Rewards

NFTs represent:

  • completed stops,
  • achievements,
  • event participation,
  • rare seasonal collectibles.

NFT standards:

  • ERC-1155 preferred.

XP / Progression

Off-chain progression includes:

  • levels,
  • explorer rank,
  • streaks,
  • badges.

NFT System

NFT Stamp Metadata

Each NFT contains:

  • trail ID,
  • stop ID,
  • timestamp,
  • rarity,
  • location hash,
  • artwork,
  • season/event info.

NFT Utility

NFTs should:

  • unlock prestige,
  • display achievements,
  • support collections,
  • grant future perks.

NFTs are NOT speculative assets.

Geolocation System

GPS Mechanics

Core mechanic:

  • user must physically reach location.

Default unlock radius:

  • 30–50 meters.

Geofence Validation

Validation includes:

  • GPS coordinates,
  • timestamp consistency,
  • movement speed,
  • accelerometer data,
  • device fingerprinting.

Anti-Cheat System

This is mission-critical.

Threats

  • GPS spoofing,
  • emulator abuse,
  • fake movement,
  • screenshot replay,
  • QR sharing,
  • multi-account farming.

Mitigation Layers

Backend Co-Signing

No reward valid without backend signature.

Movement Validation

Validate:

  • walking speed,
  • movement continuity,
  • accelerometer consistency.

Dynamic QR Codes

Merchant QR refreshes periodically.

Time Validation

Impossible movement patterns flag account.

Device Reputation

Track suspicious devices and accounts.

Social Features

Friends

Players can:

  • add friends,
  • compare progress,
  • send trail invites.

Leaderboards

Leaderboard types:

  • city-wide,
  • weekly,
  • trail-specific,
  • merchant-specific.

Squad Mode

Teams complete trails together.

Possible mechanics:

  • bonus multipliers,
  • group achievements,
  • timed races.

Event System

Seasonal Events

Examples:

  • Christmas Hunt,
  • City Festival Trail,
  • Restaurant Week Quest.

Limited-Time Trails

Trails expire after:

  • hours,
  • days,
  • weekends.

Creates urgency and replayability.

Economic Model

Merchant Pays

Merchant funds:

  • reward pool,
  • platform fee,
  • optional promotions.

Platform Earns

Revenue streams:

  • percentage of reward pools,
  • featured placement,
  • premium analytics,
  • event sponsorship,
  • custom trail creation.

Smart Contract Architecture

Blockchain

Use:

  • Celo Mainnet

Contracts

GeoQuestTrail.sol

Responsibilities:

  • trail registry,
  • reward escrow,
  • completion verification,
  • payout release.

GeoQuestStamp.sol

Responsibilities:

  • NFT minting,
  • metadata storage,
  • ownership tracking.

Suggested Smart Contract Functions

Trail Contract

Functions:

  • createTrail()
  • fundTrail()
  • submitStopProof()
  • verifyTrailCompletion()
  • claimReward()
  • emergencyPause()

Stamp Contract

Functions:

  • mintStamp()
  • batchMint()
  • tokenURI()

Backend Responsibilities

The backend is essential.

This is NOT fully decentralized.

Backend Services

Trail Content Service

Stores:

  • trails,
  • challenges,
  • merchant info,
  • schedules.

Verification Engine

Handles:

  • GPS verification,
  • anti-cheat,
  • challenge validation.

Signature Service

Signs valid completions.

Notification Service

Push notifications for:

  • nearby trails,
  • streak reminders,
  • new events.

Analytics Engine

Processes:

  • player metrics,
  • merchant insights,
  • retention.

Frontend Applications

1. MiniPay Mini App

Main player app.

Tech

  • React
  • Vite
  • Tailwind
  • TypeScript

Features

  • map,
  • wallet integration,
  • quests,
  • profile,
  • rewards,
  • leaderboards.

2. Merchant Dashboard

Separate web app.

Features

  • campaign management,
  • analytics,
  • funding,
  • stop creation.

Mapping System

Map Requirements

Map should support:

  • live player location,
  • route visualization,
  • stop clustering,
  • geofencing,
  • trail overlays.

Recommended Stack

  • Mapbox GL JS
  • Turf.js

MiniPay Integration

Wallet Features

Use MiniPay SDK for:

  • wallet connection,
  • signing,
  • transactions,
  • balance display.

UX Principles

Players should:

  • never see gas fees,
  • never manually switch chains,
  • never handle complex crypto flows.

Everything should feel native.

Database Design

Core Tables

Users

  • id
  • wallet_address
  • username
  • xp
  • level
  • created_at

Trails

  • id
  • title
  • description
  • category
  • reward_pool
  • status

Stops

  • id
  • trail_id
  • latitude
  • longitude
  • challenge_type

Merchants

  • id
  • business_name
  • wallet_address
  • category

TrailCompletions

  • id
  • user_id
  • trail_id
  • completed_at

APIs

Example APIs

Player APIs

  • GET /trails/nearby
  • POST /stop/verify
  • POST /trail/claim
  • GET /leaderboard

Merchant APIs

  • POST /merchant/trail/create
  • POST /merchant/fund
  • GET /merchant/analytics

Security Requirements

Critical Areas

  • GPS validation,
  • backend signer security,
  • reward abuse prevention,
  • wallet security,
  • replay attack prevention.

Scalability Considerations

Major Scaling Challenges

  • map rendering,
  • GPS event load,
  • analytics volume,
  • notification delivery,
  • fraud detection.

MVP Scope

MVP MUST Include

Player

  • map,
  • nearby trails,
  • GPS verification,
  • QR challenges,
  • cUSD rewards,
  • basic NFT stamps.

Merchant

  • dashboard,
  • create stop,
  • fund rewards,
  • basic analytics.

Backend

  • verification,
  • anti-cheat,
  • payouts.

Recommended MVP Constraints

Start with:

  • one city,
  • one neighborhood,
  • 10 merchants,
  • 5–10 trails,
  • 100–500 users.

Avoid premature scale.

Long-Term Vision

GeoQuest eventually evolves into:

  • a city-scale incentive layer,
  • local commerce infrastructure,
  • tourism gamification platform,
  • and proof-of-presence advertising network.

Potential future integrations:

  • tourism boards,
  • public transit,
  • universities,
  • malls,
  • festivals,
  • sports events,
  • local governments.

Design Philosophy

The product should feel:

  • playful,
  • lightweight,
  • rewarding,
  • social,
  • modern,
  • and hyper-local.

NOT:

  • overly crypto-native,
  • financially speculative,
  • or technically intimidating.

The ideal user experience:

“I explored my city and got rewarded.”

Not:

“I interacted with blockchain infrastructure.”