From b3e09667c30cf859e7aa1a3d6723432cbd79b6d7 Mon Sep 17 00:00:00 2001 From: Anastasia <142572092+LuminaEnvision@users.noreply.github.com> Date: Thu, 11 Dec 2025 16:41:19 +0700 Subject: [PATCH] feat: add comprehensive developer documentation page with sidebar navigation --- app/docs/layout.tsx | 15 + app/docs/page.tsx | 905 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 907 insertions(+), 13 deletions(-) create mode 100644 app/docs/layout.tsx diff --git a/app/docs/layout.tsx b/app/docs/layout.tsx new file mode 100644 index 0000000..0ad2b00 --- /dev/null +++ b/app/docs/layout.tsx @@ -0,0 +1,15 @@ +import type { Metadata } from "next"; + +export const metadata: Metadata = { + title: "DeCleanup Network Developer Documentation", + description: "Technical documentation for DeCleanup Rewards - Quick start guide, architecture, smart contracts, and API reference", +}; + +export default function DocsLayout({ + children, +}: { + children: React.ReactNode; +}) { + return <>{children}; +} + diff --git a/app/docs/page.tsx b/app/docs/page.tsx index 327764b..19b0033 100644 --- a/app/docs/page.tsx +++ b/app/docs/page.tsx @@ -1,15 +1,72 @@ -import type { Metadata } from "next"; +"use client"; + +import { useState, useEffect, useRef } from "react"; import Link from "next/link"; -export const metadata: Metadata = { - title: "DeCleanup Network Documentation", - description: "Technical documentation for DeCleanup Network", -}; +const sections = [ + { id: "quick-start", title: "Quick Start" }, + { id: "tech-stack", title: "Tech Stack" }, + { id: "architecture", title: "Architecture Overview" }, + { id: "environment", title: "Environment Setup" }, + { id: "commands", title: "Development Commands" }, + { id: "contracts", title: "Smart Contracts" }, + { id: "structure", title: "Project Structure" }, + { id: "testing", title: "Testing" }, + { id: "deployment", title: "Deployment" }, + { id: "api-routes", title: "API Routes" }, + { id: "security", title: "Security Notes" }, + { id: "troubleshooting", title: "Troubleshooting" }, + { id: "resources", title: "Resources & Links" }, +]; export default function DocsPage() { + const [activeSection, setActiveSection] = useState("quick-start"); + const [sidebarOpen, setSidebarOpen] = useState(false); + const sectionRefs = useRef<{ [key: string]: HTMLElement | null }>({}); + + useEffect(() => { + const handleScroll = () => { + const scrollPosition = window.scrollY + 150; + + for (const section of sections) { + const element = sectionRefs.current[section.id]; + if (element) { + const offsetTop = element.offsetTop; + const offsetHeight = element.offsetHeight; + + if ( + scrollPosition >= offsetTop && + scrollPosition < offsetTop + offsetHeight + ) { + setActiveSection(section.id); + break; + } + } + } + }; + + window.addEventListener("scroll", handleScroll); + return () => window.removeEventListener("scroll", handleScroll); + }, []); + + const scrollToSection = (sectionId: string) => { + const element = sectionRefs.current[sectionId]; + if (element) { + const offset = 100; + const elementPosition = element.offsetTop; + const offsetPosition = elementPosition - offset; + + window.scrollTo({ + top: offsetPosition, + behavior: "smooth", + }); + setSidebarOpen(false); + } + }; + return (
-
+
{/* Back Button */}

- Documentation + Developer Documentation

- Coming Soon + Technical guide for DeCleanup Rewards

-
-

- Technical documentation will be available here soon. -

+ {/* Mobile Overlay */} + {sidebarOpen && ( +
setSidebarOpen(false)} + /> + )} + +
+ {/* Sidebar Navigation */} + + + {/* Mobile Sidebar Toggle */} + {!sidebarOpen && ( + + )} + + {/* Main Content */} +
+ {/* Quick Start */} +
(sectionRefs.current["quick-start"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Quick Start +

+

+ Get DeCleanup Rewards running locally in minutes. +

+ +

+ Prerequisites +

+
    +
  • Node.js 18+
    • +
  • Base-compatible wallet (MetaMask, Coinbase Wallet, etc.)
    • +
  • Git
    • +
+ +

+ Installation +

+
+ 
+                  {`git clone https://github.com/DeCleanup-Network/decleanup-mini-app.git
+cd decleanup-mini-app
+npm install
+cp .env.example .env.local
+# Edit .env.local with your configuration
+npm run dev`}
+
+
+ +

+ For detailed local testing instructions, see the{" "} + + Local Testing Guide on GitHub + + . +

+
+ + {/* Tech Stack */} +
(sectionRefs.current["tech-stack"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Tech Stack +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Category + + Technologies +
+ Frontend + + Next.js 14, TypeScript, Tailwind CSS +
+ Blockchain + + Wagmi v2, Viem, Base (L2) +
+ Wallet + + Farcaster SDK, WalletConnect, MetaMask, Coinbase Wallet +
+ Storage + + IPFS (Pinata) +
+ Smart Contracts + + Solidity 0.8.20, Hardhat +
+
+
+ + {/* Architecture Overview */} +
(sectionRefs.current["architecture"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Architecture Overview +

+
+
+
Next.js Client
+
↓
+
Wallet Layer
+
↓
+
Domain Logic
+
↓
+
Smart Contracts
+
+
+ +

+ Key Flows +

+
    +
  • + Cleanup Submission: Photo → IPFS → On-chain +
    • +
  • + Verification: Verifier dashboard → Review → Approve/Reject +
    • +
  • + Rewards: Automatic $bDCU distribution +
    • +
  • + Impact Products: Dynamic NFT minting and level progression +
    • +
+ +

+ For detailed system architecture, see the{" "} + + System Architecture documentation on GitHub + + . +

+
+ + {/* Environment Setup */} +
(sectionRefs.current["environment"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Environment Setup +

+

+ Configure your environment variables for local development. Copy{" "} + + .env.example + {" "} + to{" "} + + .env.local + {" "} + and fill in your values. +

+ +

+ Network Configuration +

+
    +
  • Chain ID
    • +
  • RPC URLs
    • +
+ +

+ Contract Addresses +

+
    +
  • Impact Product NFT
    • +
  • Verification Contract
    • +
  • Reward Distributor
    • +
  • $bDCU Token
    • +
+ +

+ IPFS/Pinata +

+
+

+ Important: Pinata keys must be server-side only. Use{" "} + PINATA_API_KEY, NOT{" "} + NEXT_PUBLIC_PINATA_API_KEY +

+
+
    +
  • Server-side API keys
    • +
+ +

+ Farcaster +

+
    +
  • Neynar API key
    • +
  • Base App ID
    • +
+ +

+ WalletConnect +

+
    +
  • Project ID
    • +
+ +

+ See the{" "} + + .env.example file on GitHub + {" "} + for the complete list of required variables. +

+
+ + {/* Development Commands */} +
(sectionRefs.current["commands"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Development Commands +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Command + + Description +
+ npm install + + Install dependencies +
+ npm run dev + + Start dev server +
+ npm run build + + Build for production +
+ npm run test + + Run tests +
+ npm run lint + + Lint code +
+ npm run generate:metadata + + Generate NFT metadata +
+
+
+ + {/* Smart Contracts */} +
(sectionRefs.current["contracts"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Smart Contracts +

+

+ Core Contracts +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+ Contract + + Description +
+ ImpactProductNFT + + Dynamic NFT (10 levels) +
+ VerificationContract + + Cleanup submissions +
+ bDCURewardDistributor + + Auto token distribution +
+ $bDCU Token + + ERC20 reward token +
+
+ +

+ Reward Structure +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Action + + Reward +
Level Claim + 10 $bDCU +
Weekly Streak + 2 $bDCU +
Referral + 3 $bDCU (both parties) +
Impact Form + 5 $bDCU +
Verification + 1 $bDCU +
+
+
+ + {/* Project Structure */} +
(sectionRefs.current["structure"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Project Structure +

+
+
    +
  • + app/ - Next.js routes +
    • +
  • + components/ - Reusable UI components +
    • +
  • + lib/ - Business logic (contracts, IPFS, verification) +
    • +
  • + contracts/ - Solidity smart contracts +
    • +
  • + scripts/ - Utility scripts +
    • +
+
+
+ + {/* Testing */} +
(sectionRefs.current["testing"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Testing +

+

+ For local development testing, follow the setup steps in Quick Start. Ensure your wallet is connected to Base Sepolia testnet. +

+ +

+ Mobile Testing +

+

+ For mobile testing instructions, see the{" "} + + Local Testing Guide + + . +

+ +

+ Testing Checklist +

+
    +
  • Wallet connection and network switching
    • +
  • Photo upload and IPFS storage
    • +
  • Cleanup submission and verification flow
    • +
  • Reward distribution and Impact Product minting
    • +
+
+ + {/* Deployment */} +
(sectionRefs.current["deployment"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Deployment +

+

+ Frontend (Vercel) +

+
    +
  1. Push code to GitHub repository
    2. +
  2. Connect repository to Vercel
    3. +
  3. Configure environment variables in Vercel dashboard
    4. +
  4. Deploy
    5. +
+ +

+ Smart Contracts (Hardhat) +

+
+ 
+                  {`npx hardhat run scripts/deploy.js --network base`}
+
+
+ +
+

+ Remember: Set all required environment variables in your deployment platform before deploying. +

+
+
+ + {/* API Routes */} +
(sectionRefs.current["api-routes"] = el)} + className="mb-16 scroll-mt-24" + > +

+ API Routes +

+
+ + + + + + + + + + + + + + + + + + + + +
+ Route + + Method + + Description +
+ /api/ipfs/upload + POST + Proxy IPFS uploads +
+ /api/health + GET + Health check +
+
+
+ + {/* Security Notes */} +
(sectionRefs.current["security"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Security Notes +

+
    +
  • + Pinata API keys are server-side only: Never expose API keys in client-side code. Use server-side API routes for IPFS uploads. +
    • +
  • + IPFS uploads proxied through API route: All IPFS operations go through /api/ipfs/upload to protect credentials. +
    • +
  • + Wallet connection requires user approval: All wallet operations require explicit user consent. +
    • +
  • + Network switching enforced: The app enforces Base network only to prevent transactions on wrong chains. +
    • +
+
+ + {/* Troubleshooting */} +
(sectionRefs.current["troubleshooting"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Troubleshooting +

+
+
+

+ Wallet Connection Issues +

+

+ Ensure your wallet extension is installed and unlocked. Try refreshing the page or switching networks manually. +

+
+
+

+ IPFS Upload Failures +

+

+ Verify your Pinata API keys are correctly set in .env.local. Check that keys are server-side only (no NEXT_PUBLIC_ prefix). +

+
+
+

+ Contract Interaction Errors +

+

+ Confirm you're on the correct network (Base Sepolia for testing). Verify contract addresses in your environment variables match the deployed contracts. +

+
+
+
+ + {/* Resources & Links */} +
(sectionRefs.current["resources"] = el)} + className="mb-16 scroll-mt-24" + > +

+ Resources & Links +

+

+ External Resources +

+ + +

+ GitHub Documentation +

+ +
+
); } -