⛓️ ChainOverflow

The Knowledge Engine of Web3 Development.

ChainOverflow is a Q&A protocol where developers share expertise and earn through on-chain bounties and x402-powered monetization. Built for speed and transparency, it combines the best of Web2 performance with Web3 trust.

🚀 Quick Start

1. Install Dependencies: npm run setup
2. Start All Layers: npm run dev:all
   • Starts Hardhat (localhost:8545), Express Server (3001), and Vite (5173).
3. Deploy Locally: npm run deploy:local (in a separate terminal)
4. Seed Data: npm run db:seed

🏗️ Technical Architecture

ChainOverflow is built across three primary layers:

1. Smart Contracts (/contracts)

The protocol logic for on-chain bounties and vault management.

• Framework: Hardhat
• Network: Local or Base Sepolia
• Key Commands:
  • npm run compile: Compile Solidity contracts.
  • npm run dev:node: Start local Ethereum node.
  • npm run deploy:local: Deploy to localhost.
  • npm run deploy:base-sepolia: Deploy to Base Sepolia testnet.

2. Backend Server (/server)

An Express-based x402-enabled gateway and database.

• Tech Stack: TypeScript, Express, SQLite, x402.
• Key Commands:
  • npm run dev:server: Start backend with hot reload.
  • npm run db:seed: Reset and seed the local database.
  • npm run test:server: Run server-side unit/integration tests.

3. Frontend Web (/src)

A modern React application with Web3 integration.

• Tech Stack: React 19, TypeScript, Vite, Zustand, Tailwind/CSS Modules.
• Key Commands:
  • npm run dev: Start frontend dev server.
  • npm run test: Run frontend tests.

🛠️ Full CLI Reference

Command	Layer	Description
npm run setup	Root	Installs all packages across root and server folders.
npm run dev:all	Full App	Starts Web, Server, and Chain node concurrently.
npm run test:all	Testing	Runs both frontend and backend test suites.
npm run lint	General	Lints the entire codebase.
npm run format	General	Formats all files with Prettier.

📖 Documentation

Detailed information about the platform can be found in the docs folder:

• System Architecture - High-level overview.
• Deployment Architecture - Real-world production roadmap.
• Hosting Alternatives - Comparison with Cloudflare and more.
• Vercel Setup Guide - Automated zero-barrier hosting.
• State Management - How we handle global data with Zustand.
• IPFS & Indexing - Decentralized storage and deep search.
• Component Library - Overview of our React components.

🚢 Deployment

• GitHub Actions: Automate testing, linting, and Vercel Deployment (both Frontend and API).
• Vercel: Automatically hosts the React frontend and Express API as serverless functions. See VERCEL_SETUP.md for $0 setup.

1. Vercel (Recommended Hybrid Deployment)

• Workflow: Automated GitHub deployments via Actions.
• API Layer: Deployed as Vercel Functions (routed via /api/*).
• Setup Guide: See VERCEL_SETUP.md for instructions on adding secrets.

2. 4EVERLAND (Web3 Choice)

• Mechanism: Supports IPFS, Arweave, and BNB Greenfield.
• Requires: Small gas payment (Polygon MATIC) to activate API tokens.
• Decentralized Alternatives: See HOSTING_ALTERNATIVES.md for providers like 4EVERLAND or Fleek.

✨ Key Features

• x402 Monetization: Integrated with the @coinbase/x402 protocol to enable programmatic payments and x402-gated access to premium knowledge.
• High-Speed Storage: Questions and answers are stored in a performant centralized database to ensure sub-millisecond search and retrieval, avoiding the latency of decentralized storage.
• On-Chain Bounties: Trustless fund management and bounty distribution using Solidty smart contracts on the Base network.
• Democratic Voting: A reactive upvote/downvote system for reputation.
• Premium Design: Built with modern CSS, glassmorphism, and responsive layouts.