Giveth DApp - Development Environment

Giveth is a decentralized donation platform (DApp) built on Next.js with multi-blockchain support, enabling users to donate and create charitable projects transparently and efficiently.

🚀 Quick Start

Frontend Only

# Clone repository with submodules
git clone https://github.com/GiveVN/Give.git
cd Give

# Initialize submodules  
git submodule update --init --recursive

# Install dependencies
yarn install

# Create environment file
cp .env.example .env.local
# Edit .env.local with your WalletConnect Project ID

# Start frontend
yarn dev

Full Stack (Frontend + Backend) - RECOMMENDED

# Prerequisites: Docker Desktop running

# 1. Setup backend database
cd Impact-Graph
docker-compose -f docker-compose-local-postgres-redis.yml up -d

# 2. Configure environment
cp config/example.env config/development.env
# Edit development.env with database credentials

# 3. One-command setup (bypasses broken migration system)
npm run db:setup:dev

# 4. Start backend
npm start

# 5. Start frontend (new terminal, from Give directory)
cd ..
yarn dev

URLs:

• Frontend: http://localhost:3010
• Backend: http://localhost:4000/health
• GraphQL: http://localhost:4000/graphql
• AdminJS: http://localhost:4000/admin (login: test-admin@giveth.io / admin)

Why Not Use Standard Migrations?

The original migration system (npm run db:migrate:run:local) has architectural issues:

• 243+ migrations with schema conflicts
• Not designed for idempotent execution
• Fails on existing databases with constraint violations
• Test environment uses manual approach, development should too

Our db:setup:dev script uses the proven working approach from the test environment, ensuring reliable setup for all developers.

📋 System Requirements

• Node.js: >= 16.x
• Yarn: >= 1.22.x
• Git: Latest version
• PowerShell: 7.x (Windows recommended)

🏗️ Project Structure

Give/
├── src/                    # Main source code
│   ├── components/         # React components
│   ├── pages/             # Next.js pages
│   ├── hooks/             # Custom React hooks
│   ├── lib/               # Utility libraries
│   ├── providers/         # Context providers
│   └── types/             # TypeScript definitions
├── pages/                 # Next.js routing
├── public/                # Static assets
├── Docs/                  # 📚 Documentation (Submodule)
├── Assets/                # 🎨 Brand assets (Submodule)
├── cypress/               # E2E testing
└── styles/                # Global styles

🔧 Environment Configuration

Create .env.local file in the root directory:

# Development Environment
NEXT_PUBLIC_ENV=development

# Blockchain RPC URLs
NEXT_PUBLIC_XDAI_NODE_URL=https://rpc.gnosischain.com

# WalletConnect Configuration (Required)
NEXT_PUBLIC_WALLET_CONNECT_ID=your_project_id_here

# Backend Integration
NEXT_PUBLIC_BASE_ROUTE=https://impact-graph.serve.giveth.io
NEXT_PUBLIC_BACKEND_LINK=https://impact-graph.serve.giveth.io/graphql
NEXT_PUBLIC_FRONTEND_LINK=http://localhost:3010

🔑 Getting WalletConnect Project ID

1. Visit https://cloud.reown.com/
2. Create account and sign in
3. Create new project for your DApp
4. Copy Project ID and add to .env.local

🛠️ Available Scripts

Quick Commands (Recommended)

# Start services
yarn backend          # Start backend only
yarn dev              # Start frontend only  
yarn start:all        # Start both backend + frontend

# Status check
yarn status           # Check if services are running

Full Script List

# Development
yarn dev              # Start development server (port 3010)
yarn build            # Build for production  
yarn start            # Start production server

# Testing
yarn test             # Run Jest tests
yarn test:watch       # Run tests in watch mode
yarn cypress:open     # Open Cypress GUI
yarn cypress:run      # Run Cypress headless

# Code Quality
yarn lint             # Run ESLint
yarn lint:fix         # Fix ESLint errors
yarn format           # Format with Prettier
yarn type-check       # TypeScript type checking

🌐 Technical Stack

Frontend Technologies

• Framework: Next.js 14.2.13
• Language: TypeScript
• Styling: Styled Components
• State Management: Redux + Apollo Client
• Testing: Jest + Cypress
• Monitoring: Sentry

Blockchain Integration

• Wallet Adapters: WalletConnect, MetaMask, Coinbase
• Solana Support: @solana/wallet-adapter
• Web3 Libraries: Wagmi, Thirdweb
• Supported Networks:
  • Ethereum Mainnet
  • Gnosis Chain (xDAI)
  • Polygon
  • Optimism

🔗 Backend & API

• Backend Repository: impact-graph
• GraphQL Endpoint: https://impact-graph.serve.giveth.io/graphql
• Database: PostgreSQL with ~4,000 projects
• Architecture: GraphQL API with real-time subscriptions

🔧 Backend Services & Materialized Views

The Giveth backend relies on background services to create and maintain database materialized views. These services are disabled by default in development for performance.

Essential Services for Full Functionality:

# Enable in Impact-Graph/config/development.env for complete setup:
FILL_POWER_SNAPSHOT_BALANCE_SERVICE_ACTIVE=true
UPDATE_POWER_SNAPSHOT_SERVICE_ACTIVE=true
FILL_POWER_SNAPSHOT_SERVICE_ACTIVE=true
ENABLE_INSTANT_BOOSTING_UPDATE=true
PROJECT_REVOKE_SERVICE_ACTIVE=true
ENABLE_DB_POWER_BOOSTING_SNAPSHOT=true

Services vs Materialized Views:

Service	Creates	Purpose
Power Snapshot Services	user_project_power_view	User power balance tracking
Instant Boosting Update	project_instant_power_view	Real-time power boosting
Power Round Updates	project_givback_rank_view	Project ranking calculations
QF Round Management	project_estimated_matching_view	Quadratic funding matching

Note: Without these services, project pages may show "Project not found" errors and admin operations may fail with 500 errors.

📚 Documentation

• Setup Guide: SETUP_GUIDE.md - Comprehensive setup instructions
• Development Log: DEVELOPMENT_LOG.md - Troubleshooting and issues
• API Documentation: /Docs - Docusaurus site with multi-language support
• Brand Assets: /Assets - Logos, icons, brand guidelines

⚠️ Known Issues & Warnings

🟡 Non-Critical Warnings

• Styled Components: DOM prop warnings (gap, weight, sm, md)
• SSR Hydration: useLayoutEffect warnings in some components
• Image Optimization: Legacy objectFit props (Next.js 13 migration needed)
• Solana Wallet: UnsafeBurnerWalletAdapter in development mode
• IPFS Images: Some project images may fail to load due to gateway issues

🔴 Critical Issues

• Server Crashes: Intermittent development server crashes (exit code 4294967295)
• Memory Usage: High memory consumption during development

🔧 Workarounds

• Restart server if crashes occur: yarn dev
• Disable browser extensions if experiencing conflicts
• Use Chrome/Edge for best development experience

🐛 Troubleshooting

Common Issues

"Project ID is not defined"

Error: Project ID is not defined at wagmiConfigs.ts

• Check .env.local contains NEXT_PUBLIC_WALLET_CONNECT_ID
• Restart development server after changing environment variables

"next is not recognized"

• Run yarn install to install dependencies
• Verify Node.js version >= 16

Chrome Extension Errors

SyntaxError: "undefined" is not valid JSON

• Browser extension conflicts (Similarweb, etc.)
• Non-critical, doesn't affect core functionality

Browserslist Outdated Warning

Browserslist: caniuse-lite is outdated. Please run:
npx update-browserslist-db@latest

• Update with: yarn add caniuse-lite@latest
• Remove package-lock.json if exists (use yarn only)

Port Already in Use

Error: listen EADDRINUSE :::3010

• Kill existing process: Get-Process -Name "node" | Where-Object { $_.CommandLine -like "*3010*" } | Stop-Process
• Or use different port: yarn dev -p 3011

Backend Issues

"Project not found" or Admin 500 Errors

GraphQL Error: relation "public.project_givback_rank_view" does not exist

Root Cause: Missing materialized views due to disabled background services

Solutions:

1. Enable Services (Recommended): Edit Impact-Graph/config/development.env

   FILL_POWER_SNAPSHOT_BALANCE_SERVICE_ACTIVE=true
   UPDATE_POWER_SNAPSHOT_SERVICE_ACTIVE=true
   PROJECT_REVOKE_SERVICE_ACTIVE=true

   Then restart backend: cd Impact-Graph && npx ts-node --transpile-only src/index.ts

2. Manual Fix: Use materialized views creation script

   cd Impact-Graph
   node fix-all-materialized-views.js

Backend Directory Requirement

Error: Cannot find module './index.ts'

• MUST run backend from Impact-Graph/ directory:

  # ❌ Wrong (from Give/ root):
  npx ts-node --transpile-only src/index.ts
  
  # ✅ Correct (from Impact-Graph/):
  cd Impact-Graph
  npx ts-node --transpile-only src/index.ts

Backend Services Architecture

• Migrations: Only SEED data, don't create materialized views
• Background Services: Create and maintain database views via cron jobs
• Development: Services disabled by default for performance
• Production: Services enabled for full functionality

Development Environment Health Check

# Verify all components working:
1. Backend: curl http://localhost:4000/health
2. Frontend: curl http://localhost:3010
3. GraphQL: Open http://localhost:4000/graphql
4. Admin: Open http://localhost:4000/admin
5. Database Views: Check materialized views exist

🚢 Deployment

Production Build

yarn build
yarn start

Docker

docker build -t giveth-app .
docker run -p 3010:3010 giveth-app

Environment Variables for Production

NEXT_PUBLIC_ENV=production
NEXT_PUBLIC_WALLET_CONNECT_ID=your_production_id
NEXT_PUBLIC_BACKEND_LINK=https://impact-graph.serve.giveth.io/graphql
# Add other production-specific variables

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: yarn test && yarn lint
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open Pull Request

Development Workflow

1. Code Changes: Edit files in /src directory
2. Testing: Run yarn test for unit tests, yarn cypress:open for E2E
3. Building: Run yarn build for production build
4. Deployment: Docker container or Vercel

📊 Performance Metrics

• Initial Compilation: ~13.3s (10,507 modules)
• Hot Reload: 860ms - 1.4s
• Bundle Size: ~1.2GB (with submodules)
• Dependencies: 2,310 packages

🏗️ Architecture Insights

Giveth Backend Architecture

• Database Views: Materialized views managed by background cron jobs
• Service Dependencies: GraphQL resolvers depend on database views
• Development Trade-off: Services disabled for performance, manual view creation needed
• Production Setup: All services enabled for complete functionality

Key Design Patterns

• Background Services: Database maintenance via scheduled jobs
• TypeGraphQL: Schema caching requires backend restart after changes
• Error Propagation: Database errors appear as "Project not found" in frontend
• Directory Dependencies: Backend must run from Impact-Graph/ subdirectory

Development vs Production

Aspect	Development	Production
Background Services	Disabled	Enabled
Materialized Views	Manual creation	Auto-maintained
Performance	Optimized for speed	Optimized for completeness
Setup Complexity	Simple migration	Full service configuration

🔒 Security

• Environment Variables: Never commit .env.local to version control
• API Keys: Use environment variables for all sensitive data
• Wallet Security: WalletConnect provides secure wallet connections
• Sentry: Configure source maps properly for production

📄 License

This project is distributed under the GPL-3.0 License. See LICENSE for more information.

🔗 Links

• Live Site: https://giveth.io
• Documentation: https://docs.giveth.io
• GitHub Issues: Issues
• Community: Discord | Telegram

🆘 Support

If you encounter issues:

1. Check DEVELOPMENT_LOG.md for known issues
2. Search GitHub Issues
3. Create new issue with detailed description
4. Join our Discord for community support

---

Made with ❤️ by the Giveth Community