A Web3-powered digital collectibles platform for iconic world landmarks
- Project Overview
- Architecture
- Tech Stack
- Project Structure
- Core Features
- Data Flow
- Components Documentation
- State Management
- Web3 Integration
- Getting Started
- Deployment
- Environment Variables
- Future Enhancements
Wandr is an innovative NFT tourism platform that allows users to explore iconic world landmarks and collect them as unique digital collectibles. Built on the Polygon Amoy testnet, it combines the excitement of travel discovery with blockchain-powered ownership.
Transform the way people experience and remember landmarks by creating a digital passport of collectible memories, bridging physical tourism with Web3 technology.
- Gamified Exploration: Discover landmarks through an interactive global map
- Digital Ownership: Claim landmarks as NFTs stored on blockchain
- Personal Collection: Build and showcase your digital travel passport
┌─────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
│ │ Next.js │ │ React 19 │ │ TailwindCSS │ │ Leaflet ││
│ │ App Router│ │ Components │ │ Styling │ │ Maps ││
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ STATE MANAGEMENT │
│ ┌─────────────────────────┐ ┌─────────────────────────────────┐ │
│ │ NFT Context │ │ Local Storage │ │
│ │ (React Context API) │ │ (Persistent User Data) │ │
│ └─────────────────────────┘ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ WEB3 LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
│ │ RainbowKit │ │ Wagmi │ │ Viem │ │WalletConnect││
│ │ (UI) │ │ (Hooks) │ │ (Interface) │ │ (Protocol) ││
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ BLOCKCHAIN LAYER │
│ ┌─────────────────────────────────┐ │
│ │ Polygon Amoy Testnet │ │
│ │ (EVM-Compatible Chain) │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
The application follows a Component-Driven Architecture with:
- Presentation Layer: React components with TailwindCSS styling
- Business Logic Layer: Custom hooks and context providers
- Data Layer: Static landmark data + localStorage persistence
- Integration Layer: Web3 providers for blockchain connectivity
| Technology | Version | Purpose |
|---|---|---|
| Next.js | 16.1.1 | React framework with App Router, SSR, and optimizations |
| React | 19.2.3 | UI component library with latest concurrent features |
| TypeScript | 5.x | Type-safe development |
| Technology | Version | Purpose |
|---|---|---|
| TailwindCSS | 4.x | Utility-first CSS framework |
| PostCSS | - | CSS processing and optimization |
| Poppins & DM Sans | - | Custom typography via Google Fonts |
| Technology | Version | Purpose |
|---|---|---|
| Leaflet | 1.9.4 | Interactive map rendering |
| React-Leaflet | 5.0.0 | React bindings for Leaflet |
| CARTO Dark Tiles | - | Dark-themed map tile layer |
| Technology | Version | Purpose |
|---|---|---|
| RainbowKit | 2.2.10 | Beautiful wallet connection UI |
| Wagmi | 2.19.5 | React hooks for Ethereum |
| Viem | 2.43.3 | TypeScript interface for EVM |
| WalletConnect | - | Multi-wallet connection protocol |
| Technology | Purpose |
|---|---|
| TanStack React Query | Server state management and caching |
| React Context API | Global state for NFT claims |
| localStorage | Persistent user data storage |
| Technology | Purpose |
|---|---|
| ESLint | Code linting and quality |
| Babel React Compiler | Automatic component optimization |
wandr/
├── 📁 public/
│ └── 📁 fonts/ # Custom font files
│
├── 📁 src/
│ ├── 📁 app/ # Next.js App Router pages
│ │ ├── 📄 layout.tsx # Root layout with providers
│ │ ├── 📄 page.tsx # Homepage with hero section
│ │ ├── 📄 globals.css # Global styles and animations
│ │ │
│ │ ├── 📁 explore/ # Landmark exploration page
│ │ │ └── 📄 page.tsx # Map + grid view of landmarks
│ │ │
│ │ ├── 📁 collection/ # User's NFT collection
│ │ │ └── 📄 page.tsx # Personal collection dashboard
│ │ │
│ │ └── 📁 landmark/ # Dynamic landmark pages
│ │ └── 📁 [id]/ # Dynamic route parameter
│ │ └── 📄 page.tsx # Individual landmark detail
│ │
│ ├── 📁 components/ # Reusable UI components
│ │ ├── 📄 index.ts # Component exports
│ │ ├── 📄 Navbar.tsx # Navigation with wallet connect
│ │ ├── 📄 LandmarkCard.tsx # Landmark display card
│ │ └── 📄 MapComponent.tsx # Interactive Leaflet map
│ │
│ ├── 📁 context/ # React Context providers
│ │ └── 📄 NFTContext.tsx # NFT claim state management
│ │
│ ├── 📁 data/ # Static data sources
│ │ └── 📄 landmarks.ts # Landmark definitions & types
│ │
│ └── 📁 providers/ # Application providers
│ └── 📄 Web3Provider.tsx # RainbowKit + Wagmi setup
│
├── 📄 next.config.ts # Next.js configuration
├── 📄 tailwind.config.ts # TailwindCSS configuration
├── 📄 tsconfig.json # TypeScript configuration
├── 📄 package.json # Dependencies and scripts
└── 📄 README.md # This file
- Technology: Leaflet with React-Leaflet wrapper
- Features:
- Dark-themed CARTO tile layer
- Custom animated markers for each landmark
- Color-coded markers (purple for claimed, violet for available)
- Smooth fly-to animations when selecting landmarks
- Popup cards with quick landmark info
- Toggle between map view and grid view
-
6 Featured Landmarks (expandable):
- Eiffel Tower (France)
- Colosseum (Italy)
- Taj Mahal (India)
- Machu Picchu (Peru)
- Great Wall of China (China)
- Statue of Liberty (USA)
-
Landmark Data Structure:
interface Landmark { id: string; name: string; description: string; coordinates: { lat: number; lng: number }; imageUrl: string; images: string[]; // Multiple images for gallery funFacts: string[]; // Educational content country: string; category: string; // Monument, Historical Site, etc. }
-
Wallet Connection: RainbowKit modal with multiple wallet support
-
Claim Flow:
- User connects Web3 wallet
- Navigates to landmark detail page
- Clicks "Claim NFT" button
- Simulated blockchain transaction (2s delay)
- NFT stored in user's collection
-
Token Generation:
tokenId: `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
- Stats Display: Total collected, remaining, completion percentage
- Progress Bar: Visual completion indicator
- NFT Cards: Display claimed landmarks with token ID and claim date
- Wallet-Specific: Collections are tied to wallet addresses
- Mobile-First: Optimized for all screen sizes
- Animated Navbar: Shrinks on scroll with glass-morphism effect
- Touch-Friendly: Map interactions work on mobile devices
┌──────────┐ ┌───────────┐ ┌─────────────┐ ┌──────────────┐
│ User │ │ UI Layer │ │ NFT Context │ │ localStorage │
└────┬─────┘ └─────┬─────┘ └──────┬──────┘ └──────┬───────┘
│ │ │ │
│ Click "Claim" │ │ │
│────────────────>│ │ │
│ │ │ │
│ │ claimNFT(id) │ │
│ │─────────────────>│ │
│ │ │ │
│ │ │ Generate tokenId │
│ │ │──────────┐ │
│ │ │ │ │
│ │ │<─────────┘ │
│ │ │ │
│ │ │ Update state │
│ │ │──────────┐ │
│ │ │ │ │
│ │ │<─────────┘ │
│ │ │ │
│ │ │ Persist data │
│ │ │──────────────────>│
│ │ │ │
│ │ State updated │ │
│ │<─────────────────│ │
│ │ │ │
│ UI re-renders │ │ │
│<────────────────│ │ │
│ │ │ │
- On Mount: Load claimed NFTs from localStorage (wallet-specific key)
- On Claim: Update React state → Trigger useEffect → Save to localStorage
- On Wallet Change: Clear state → Load new wallet's data from localStorage
File: src/providers/Web3Provider.tsx
Wraps the application with Web3 capabilities.
Configuration:
- Chain: Polygon Amoy Testnet
- Theme: Dark theme with purple accent (#a855f7)
- SSR: Enabled for Next.js compatibility
File: src/context/NFTContext.tsx
Manages NFT claim state globally.
Exposed Values:
{
claimedNFTs: ClaimedNFT[]; // Array of claimed NFTs
claimNFT: (id: string) => void; // Claim function
isLandmarkClaimed: (id: string) => boolean;
totalClaimed: number; // Count of claimed NFTs
}File: src/components/Navbar.tsx
Responsive navigation with:
- Logo and brand name
- Navigation links (Home, Explore, Collection)
- RainbowKit Connect Button
- Mobile hamburger menu
- Scroll-based shrink animation
File: src/components/MapComponent.tsx
Interactive map component featuring:
- Custom SVG markers with claim status indication
- Fly-to animations via
MapControllersub-component - Popup cards on marker click
- Dynamic imports for SSR compatibility
File: src/components/LandmarkCard.tsx
Reusable card for displaying landmarks:
- Image with hover zoom effect
- Status badge (Claimed/Available)
- Category tag
- Claim button with loading state
- Link to detail page
Purpose: Manage user's claimed NFTs across the application
State Shape:
interface ClaimedNFT {
landmarkId: string;
claimedAt: Date;
tokenId: string;
}Storage Key Pattern: nft-tourism-claimed-{walletAddress}
- Simplicity: Single concern (NFT claims) doesn't require complex state
- Performance: React 19's concurrent features optimize re-renders
- Bundle Size: No additional dependencies
- Native Integration: Works seamlessly with Next.js App Router
Via RainbowKit + WalletConnect:
- MetaMask
- Coinbase Wallet
- WalletConnect (200+ wallets)
- Rainbow
- Trust Wallet
- And more...
const config = getDefaultConfig({
appName: 'Wandr',
projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,
chains: [polygonAmoy], // Polygon Amoy Testnet
ssr: true,
});| Hook | Purpose |
|---|---|
useAccount() |
Get connected wallet address and status |
useConnect() |
Handle wallet connections |
useDisconnect() |
Handle wallet disconnections |
- Node.js 18.x or higher
- npm, yarn, or pnpm
- A Web3 wallet (MetaMask recommended)
- Deploy NFT smart contract on Polygon
- Implement actual minting with on-chain storage
- Add IPFS metadata storage via Pinata
- User profiles and leaderboards
- Achievement badges for milestones
- Social sharing of collections
- Geo-location verification for "real" visits
- Rare landmark drops and limited editions
- Trading marketplace for NFTs
- Premium landmark packs
- Partner with tourism boards
- NFT royalties on secondary sales
Built with ❤️ for HackXIOS '25