How andrewkimjoseph/canvassing-participant works
Project Type and Purpose
• The project is a Web3, full-stack application built with Next.js. Its purpose is to serve online surveys for participants (with active Celo wallet addresses) and reward them using a secure Solidity smart contract.
• The README clearly summarizes survey booking, off-chain reward signature creation, and secure on-chain transactions using a Solidity contract (ClosedSurveyV6.sol).
File Structure
• There are two major areas:
– The “front-end” directory contains the Next.js application code (pages, components, hooks, providers, services, etc.), UI components, and configurations. It includes directories such as “app” for page routes, “components” for UI elements, “entities” for data models, “services” (subdivided into database and web3 services), and “stores” for state management.
– The “hardhat” directory holds the smart contract code and associated deployment, testing, and script files. This contains Solidity contracts (including ClosedSurveyV6.sol), deployment scripts, tests, and configurations needed for contract development.
• In addition, there is a “functions” directory within “front-end” which indicates usage of Firebase functions, potentially assisting with backend functionality like signature generation or DB interactions.
Core Components
a. Frontend (Next.js Application):
• Layout & Routing: Next.js “app” pages and custom routing.
• State Management & Providers: The “stores” directory and context providers (e.g., for Amplitude, web3, responsive design).
• Services: Two main types:
– Database-related services under “services/db”
– Blockchain interaction services under “services/web3”
• Utilities: Helpers for formatting tokens, abi definitions, etc.
b. Backend / Off-Chain Components:
• Firebase Functions: Located in “front-end/functions”. They handle auxiliary tasks like on-chain booking signatures or processing reward claims.
• Firebase Integration: Firebase authentication (anonymous) and Firestore database usage for storing survey bookings and user data.
c. Blockchain & Smart Contracts:
• Smart Contracts: The Solidity contracts in the “hardhat/contracts” directory, primarily ClosedSurveyV6.sol.
• Hardhat Environment: Contains testing, deployment scripts, and configuration files to deploy and verify contracts on the Celo network.
• Web3 Service: Front-end integration (in “services/web3”) that interacts with the deployed smart contracts.
d. External Services:
• Amplitude for analytics.
• Sentry for error monitoring.
• Firebase for authentication and real-time data.
• Celo blockchain network for executing smart contract logic.
Relationships and Interactions
• The Frontend (user interface) interacts with Firebase Authentication and Firestore to maintain participant sessions and booking data.
• When a participant books a survey, the browser communicates with backend Firebase services, which in turn may trigger off-chain signing to enable secure claim operations.
• User Action → UI → API calls through Firebase functions
• Blockchain call → Smart Contract → Response (reward claim process)
• The local development environment (Hardhat) and deployment scripts manage the lifecycle of the smart contracts, with testing feeding into the quality assurance for the entire system.
Architectural Patterns and Technologies
• MVC / Component Pattern: Next.js organizes pages and UI components (controlled via the “app” directory and reusable “components”).
• Dependency Injection / Provider Pattern: Use of multiple context providers (amplitude, web3, etc.) across the app.
• Micro-frontend / Service Separation: Separation between frontend UI, Firebase backend functions, and the independent blockchain contract system.
• Integration via APIs: The frontend calls services (both Firebase and web3) to manage survey booking and reward claiming workflows.