Chimpers World - System Overview

Technical documentation for administrators and team members

1. System Overview

Chimpers World consists of 2 core systems:

Content Platform

• Gallery (5,555 Chimpers)
• Genesis (98 1/1s)
• Lore & Story pages
• Trait explorer
• Rarity rankings

User System

• Email/password signup
• Twitter/Discord linking
• Wallet verification
• NFT ownership tracking
• Profile management

Key Concept

Users can prove NFT ownership without connecting their wallet directly. By adding a verification code to their OpenSea profile bio, they can verify safely without exposing private keys.

2. Architecture

Tech Stack

⚛️

Next.js 16

Frontend + API

🗄️

Supabase

Database

🔐

NextAuth v5

Authentication

🚀

Vercel

Hosting

System Layers

Frontend Layer

React Components → User Interaction → State Management (Context API)

↕️

API Layer (Next.js Route Handlers)

/api/wallet/* (Wallet mgmt) | /api/admin/* (Admin)

↕️

Data Layer

Supabase (Users, Wallets, NFT Ownership) | Static JSON (NFT Metadata)

↕️

External Services

Alchemy (NFT queries) | OpenSea (Profile verification) | CoinGecko (Prices)

3. Data Flow

User Registration Flow

Wallet Verification Flow

1User enters wallet address

2Server generates unique code: CHIMPERS-{random}-{wallet6chars}

3Saved to verified_wallets as pending (10 min expiry)

4User adds code to OpenSea Bio

5Server checks OpenSea API for Bio

6Code matches → Update verified_at → Verification complete!

NFT Sync Flow

Sync button click→Call Alchemy API→Receive NFT list→Update nft_ownership table

* Alchemy queries all NFTs from Chimpers & Genesis contracts

4. Admin Controls

How to Grant Admin Access

In Supabase users table, set is_admin = true for the user.

Content Editing (Lore)

Admins can edit Lore directly on individual Chimpers/Genesis detail pages.

Visit detail page→Click "Edit" button→Modify name/lore→Save

* Changes are saved to Supabase chimpers_lore / genesis_lore tables.

5. Database Schema

Main Tables

users

id, email, password_hash, twitter_id, discord_id, is_admin, created_at

verified_wallets

id, user_id, wallet_address, verification_code, verified_at, expires_at

nft_ownership

id, wallet_address, contract_address, token_id, is_current_owner, synced_at

chimpers_lore / genesis_lore

token_id, name, lore, updated_at, updated_by

6. External Services

Alchemy

• Purpose: NFT ownership queries
• API: getNFTsForOwner
• Called: On Sync NFTs button click

OpenSea

• Purpose: Wallet verification (Bio check)
• API: getAccount
• Called: On Verify button click

CoinGecko

• Purpose: ETH/USD price
• API: simple/price
• Called: Gallery listing price display

Supabase (Team Story Hub)

• Purpose: Main database + media storage
• Auth: Service Role Key (server)
• Called: All data CRUD + thumbnails, BGM, audio

Environment Variables

TEAM_SUPABASE_SERVICE_ROLE_KEY

GOOGLE_AI_API_KEY

ADMIN_SECRET

COMMISSION_SESSION_SECRET

CRON_SECRET

ALCHEMY_API_KEY

OPENSEA_API_KEY

DISCORD_WEBHOOK_COMMISSIONS

Quick Links

Supabase ↗Vercel ↗