Backend Features Spec

Complete specification of 8 backend systems to be implemented

This document outlines the complete backend architecture for Web3 Cianjur, designed to match and exceed LearnWeb3.io's capabilities.

Overview — 8 Systems

#	System	Purpose	Priority
1	XP Engine	Points for every action, level system	P0
2	Content CMS	Modules, lessons, quizzes from Supabase	P0
3	Progress Tracking	Track learning journey per user	P0
4	On-Chain Credentials	NFT badges on Base (ERC-1155)	P1
5	Bounty System	Community tasks with XP rewards	P1
6	Leaderboard	Global XP ranking + realtime	P1
7	Testnet Faucet	Free testnet ETH for learners	P2
8	Advanced Auth	SIWE + GitHub + WalletConnect	P2

---

System 1: XP Engine

Foundation of the entire platform. Every user action earns XP.

XP Values

Action	XP	Frequency
Complete lesson	+100	Per lesson
Pass quiz (≥80%)	+200	Per quiz
Perfect quiz (100%)	+500	Per quiz
Complete module	+1,000	Per module
Attend IRL event	+300	Per event
Report scam (verified)	+150	Per report
Refer new user	+200	Per referral
Complete bounty	+2,000–10,000	Per bounty
7-day streak	+500	Weekly
First wallet connect	+100	One-time
Mint badge NFT	+300	Per badge

Level System

Level	XP Required	Title	Badge
1	0	Newbie	🌱
2	500	Explorer	🌐
3	2,000	Builder	🔨
4	5,000	Expert	⚡
5	15,000	Master	🏆
6	50,000	Legend	👑

Database Table

CREATE TABLE xp_events (
  id         UUID PRIMARY KEY,
  user_id    UUID REFERENCES auth.users(id),
  action     TEXT NOT NULL,
  xp_amount  INTEGER NOT NULL,
  source_type TEXT,
  source_id  TEXT,
  metadata   JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT now()
);

---

System 2: Content CMS

Replace all hardcoded JS data files with Supabase tables.

Tables

Table	Replaces	Fields
modules	learningData.js	id, title, description, emoji, color, badge_id
lessons	learningContent.js	id, module_id, title, content (markdown), video_url
quizzes	inline quiz data	id, lesson_id, pass_score, xp_reward
quiz_questions	inline questions	question, options (JSONB), correct, explanation
events	mockData.initialEvents	title, date, type, status, luma_url
team_members	mockData.initialTeamMembers	name, role, avatar_url, twitter
projects	mockData.initialProjects	name, author, tags, link

---

System 3: Progress Tracking

Database Table

CREATE TABLE user_progress (
  user_id     UUID REFERENCES auth.users(id),
  lesson_id   TEXT REFERENCES lessons(id),
  module_id   TEXT,
  status      TEXT DEFAULT 'in_progress',
  quiz_score  INTEGER,
  quiz_passed BOOLEAN DEFAULT false,
  completed_at TIMESTAMPTZ,
  UNIQUE(user_id, lesson_id)
);

CREATE TABLE user_streaks (
  user_id        UUID PRIMARY KEY,
  current_streak INTEGER DEFAULT 0,
  longest_streak INTEGER DEFAULT 0,
  last_active    DATE DEFAULT CURRENT_DATE
);

---

System 4: On-Chain Credentials

Smart Contracts

Contract	Standard	Network	Purpose
BadgeNFT.sol	ERC-1155	Base	Module completion badges
MembershipSBT.sol	ERC-5192	Base	Soulbound membership token

Mint Flow

1. User completes module → quiz score ≥ 80%

2. Backend Edge Function validates

3. Sign mint transaction (server-side wallet)

4. Submit tx to Base

5. Store tx_hash in user_badges table

6. Award XP (+300)

7. Show celebration animation

---

System 5: Bounty System

Bounty Types

Type	Example	Reward
Build	Build a dApp using Sui Move	5,000–10,000 XP
Write	Tutorial article for beginners	2,000 XP
Translate	Translate docs to Bahasa Indonesia	1,500 XP
Design	Create infographic for DeFi module	2,000 XP
Bug Report	Find & report security issues	3,000 XP
Community	Organize local meetup	5,000 XP

---

System 6: Leaderboard

• Global XP ranking with realtime Supabase subscription

• Filter by: All Time, Monthly, Weekly

• User card: rank, username, avatar, total XP, level, badges count

• Live updates via postgres_changes channel

---

System 7: Testnet Faucet

Network	Token	Drip	Cooldown
Ethereum Sepolia	sETH	0.01	24h
Base Sepolia	bsETH	0.01	24h
Arbitrum Sepolia	arbETH	0.01	24h

Faucet requires user level ≥ 2 (Explorer) to prevent abuse.

---

System 8: Advanced Auth

Method	Implementation	Phase
Email/Password	✅ Done (Supabase Auth)	—
GitHub OAuth	Supabase Auth provider	Phase 1
Google OAuth	Supabase Auth provider	Phase 1
SIWE (Sign-In with Ethereum)	Custom Edge Function	Phase 2
WalletConnect v2	wagmi connector upgrade	Phase 2

---

14 React Hooks

useXP          useModules      useLessons
useProgress    useQuiz         useBadges
useLeaderboard useEvents       useTeam
useProjects    useBounties     useFaucet
useProfile     useStreak

---

Implementation Phases

Phase 1 — Foundation (2 weeks)

• Setup Supabase tables

• Migrate hardcoded data → Supabase

• Create content hooks

• Add GitHub + Google OAuth

Phase 2 — XP + Progress (2 weeks)

• XP engine + Edge Function

• Progress tracking

• Quiz auto-grading

• Streak system

Phase 3 — On-Chain + Leaderboard (2 weeks)

• Deploy BadgeNFT on Base Sepolia

• Badge minting Edge Function

• Leaderboard API + realtime

• Profile page upgrade

Phase 4 — Advanced Features (2 weeks)

• Bounty system

• SIWE auth

• WalletConnect v2

• Testnet faucet

Phase 5 — Token Integration (3 weeks)

• Deploy $W3CJR ERC-20 contract

• Learn-to-earn reward distribution

• Token staking

• DAO governance (OpenZeppelin Governor)

---

Competitive Advantages

Features that make Web3 Cianjur unique compared to LearnWeb3.io:

Feature	Why We Win
Multi-language (ID/EN/Sunda)	LearnWeb3 is English-only
DeFi Lab	Interactive DeFi protocol explorer
Anti-Scam Center	Community-powered scam reports
IRL Event Integration	RSVP + check-in + photo gallery
$W3CJR Token	Learn-to-earn utility token
Bounties in Bahasa	Accessible to local community
Event NFT Attendance	POAP-style attendance badges
Local News Ticker	Live crypto prices + market data