Feat/integration

README.md

@@ -1,73 +1,243 @@
-**DeCleanup Rewards** is a decentralized application (dApp) build on steller network and designed to:
-a) **tokenize IRL impact created via global/local cleanup efforts**
-b) **incentivize environmental actions via DeFi mechanics**.
-The platform promotes environmental stewardship globally, with plans to activate global/local communities and scale across multiple blockchain ecosystems.
+# DeCleanup dApp
 
-![Screenshot of the Main Page](https://beige-defiant-spoonbill-537.mypinata.cloud/ipfs/QmWjckBnwWkidWtTQwR17TrQWoo9j3FX5LLwRg8s3n12cN)
+A decentralized application for environmental cleanup initiatives built with Next.js, TypeScript, and Web3 technologies.
 
-## OSS data
+## 🚀 Features
 
-**dApp GitHub repository** - 🔗👉 https://github.com/DeCleanUp-DCU/Dapp
+- **Web3 Integration**: Seamless blockchain interactions
+- **Modern UI**: Built with Tailwind CSS and shadcn/ui
+- **Type Safety**: Full TypeScript support
+- **Responsive Design**: Mobile-first approach
+- **Authentication**: Secure user authentication
+- **Real-time Updates**: Live data synchronization
 
-**Smart Contract GitHub Repository** - 🔗👉 https://github.com/DeCleanUp-DCU/Smart-Contract
+## 📁 Project Structure
 
-**Smart Contract onchain** [Arbiscan](https://arbiscan.io/address/0xf21389b64e0eb749fd150d0c44742692e19a69c8)
+This project follows a professional, scalable architecture:
 
-## Uniqueness
+```
+src/
+├── app/              # Next.js App Router pages
+├── components/       # React components (organized by feature)
+├── context/          # React Context providers
+├── hooks/            # Custom React hooks
+├── lib/              # Utilities, constants, and helpers
+├── services/         # API and Web3 service functions
+├── styles/           # Global styles and CSS
+└── types/            # TypeScript type definitions
+```
 
-**How DeCleanup dApp works**: Participants engage in cleanups, submit proof via photos, and earn dynamic NFTs that evolve based on their contributions. More details in our [Mirror Article](https://mirror.xyz/decleanupnet.eth/ZzncKRu-Q-leEZkQ48Txm-NQRxG_hH3V3wyHaYUKfYI).
+For detailed structure documentation, see [STRUCTURE.md](./STRUCTURE.md).
 
-**User-Centric Design & Functionality**: The DeCleanup dApp offers a seamless user experience with an intuitive interface, allowing individuals and communities to easily submit proof of cleanups and earn dynamic NFTs, reflecting real-world impact on-chain. The verification system ensures quick approval for rewards, making the process simple and efficient.
-More details in our [Guide](https://mirror.xyz/decleanupnet.eth/A5uzOpx9HUgXZEopCKUsbgffw9SajL4Q9eECgrguq-4).
+## 🛠️ Tech Stack
 
-**Gasless Approach**: We chose Arbitrum for its low gas fees, with only the first claim requiring gas payment, while the rest of the experience is gasless. This eliminates barriers to onboarding non-tech-savvy users into Web3, enhancing real-world impact - our key KPI. Gasless transactions make Web3 more accessible to everyday people.
+- **Framework**: Next.js 15 with App Router
+- **Language**: TypeScript
+- **Styling**: Tailwind CSS
+- **UI Components**: shadcn/ui
+- **Web3**: Ethers.js, Wagmi, RainbowKit
+- **Authentication**: NextAuth.js
+- **State Management**: React Context + TanStack Query
+- **Package Manager**: npm/yarn/bun
 
-**Contribution to Ecosystem Growth**: By integrating environmental action with blockchain technology, making it intuitive and practically gasless for the end user, DeCleanup boosts on-chain activity through introducing new wallets and increases community engagement.
+## 🚀 Getting Started
 
-**Innovation in Application**: DeCleanup tokenizes real-world impact, converting environmental efforts into on-chain assets, which can be recognized as valuable impact products in the broader blockchain ecosystem.
+### Prerequisites
 
-**Community Onchain Activation**: Gamification elements like leaderboards and challenges via [Guild XYZ](https://guild.xyz/decleanup-network) allow users to earn extra points and compete for top spots. High-ranking users make it to the whitelist, encouraging participation and collaboration within the network.
+- Node.js 18+
+- npm, yarn, or bun
+- Git
 
-## dApp and Dynamic NFT Collection
+### Installation
 
-![9 Levels NFTs](https://beige-defiant-spoonbill-537.mypinata.cloud/ipfs/QmZELVjF8H5VvG1BxhunXK4n6LuK17RBuis5yRepEqxARk)
+1. **Clone the repository**
 
-The collection items have common traits that remain consistent with each NFT upgrade:
+   ```bash
+   git clone <repository-url>
+   cd dapp
+   ```
 
-- **Category**: Cleanup Impact NFT
-- **Type**: Dynamic
-- **Impact**: Environmental
+2. **Install dependencies**
 
-There are dynamic traits, which grow every three cleanups:
+   ```bash
+   npm install
+   # or
+   yarn install
+   # or
+   bun install
+   ```
 
-- **Rarity**: Common (1-3 cleanups), Rare (4-6 cleanups), Legendary (7-9 cleanups), Unique (10 cleanups)
-- **Level**: Newbie (1-3 cleanups), Pro (4-6 cleanups), Hero (7-9 cleanups), Guardian (10 cleanups)
+3. **Set up environment variables**
 
-And dynamic traits which grow with every cleanup done:
+   ```bash
+   cp .env.example .env.local
+   ```
 
-- **Impact Value**: 1 (first cleanup) to 10 (last cleanup)
-- **DCU Points**: 10 (first cleanup) to 100 (last cleanup)
+   Configure your environment variables:
 
-While the first two categories of traits determine the general information required for this impact product’s classification on the Impact Marketplace, the last categories are mainly dynamic traits, which will determine the rewards value via Impact Marketplace DeFi utility and will contribute for user’s IRL impact rank.
-Read more on this topic in the article by EcoSynthesisX on [Mirror](https://mirror.xyz/ecosynthesisx.eth/zOdeuaeFfJUFScZZKu1OGF7cWCiRgUHQSGE-14cf8fo).
+   ```env
+   NEXT_PUBLIC_API_URL=http://localhost:3000/api
+   NEXT_PUBLIC_DECLEANUP_CONTRACT_ADDRESS=your_contract_address
+   NEXTAUTH_SECRET=your_nextauth_secret
+   NEXTAUTH_URL=http://localhost:3000
+   ```
 
-![Example of Traits](https://beige-defiant-spoonbill-537.mypinata.cloud/ipfs/QmfUA1PomqfsXPZod2oo79nrMq17xT1Rxo8EdWxwFFVHxM)
+4. **Run the development server**
 
-## Partnerships and Community Activation
+   ```bash
+   npm run dev
+   # or
+   yarn dev
+   # or
+   bun dev
+   ```
 
-Initial community outreach was established by partnership proposals with the key networks such as GreenPill Network and ReFi DAO. [ReFi](https://x.com/refiphangan/status/1837797388368728419?s=61)
-and GreenPill Phangan, in particular are active in the [Monthly Earth Day](https://x.com/highlyartistic/status/1837668300425429023?s=61) movement. The other ReFi node that is organizing cleanups is [ReFi Tulum](https://x.com/refitulum/status/1838290711961112606?s=61)
-Additional partnerships with [Aqua Purge web3](https://x.com/aquapurgeweb3/status/1822565379593449715?s=61) have furthered our global reach. These communities organize regular cleanups and were the first we have targeted.
-Recent community that joined the Network, [HEMJapan](https://x.com/hemjapan?s=21), impressed us with 12 new wallets applied with the proofs after their recent Monthly Earth Day [cleanup](https://x.com/hemjapan/status/1838096871035928649?s=61).
-Moreover, we are establishing partnerships with like minded projects. As example, DeCleanup and [Cleanify](https://x.com/cleanify_vet?s=21) have a collaborative strategy to promote each other, motivating both communities to organize more cleanups, and providing additional incentives for them.
+5. **Open your browser**
+   Navigate to [http://localhost:3000](http://localhost:3000)
 
-## RoadMap
+## 📝 Available Scripts
 
-![The Roadmap](https://beige-defiant-spoonbill-537.mypinata.cloud/ipfs/QmcAgDypdKSRtUkoaBGp3puYRWEuyEjT5BauuVmXDYz7y1)
+- `npm run dev` - Start development server with Turbopack
+- `npm run build` - Build for production
+- `npm run start` - Start production server
+- `npm run lint` - Run ESLint
+- `npm run format` - Format code with Prettier
 
-The roadmap highlights the following stages for development and expansion:
+## 🏗️ Architecture
 
-1. **Community Activation (22.11.2024)**: Finalize partner onboarding and establish the foundation for continued network growth.
-2. **Marketing (Q4 2024)**: Engage more communities through focused marketing and participation in events such as Monthly Earth Day.
-3. **Expansion (Q2 2025)**: Scale the platform to multiple blockchain networks to increase reach and global participation.
-4. **DeCleanup 2.0 (Q4 2025)**: Launch full platform features, evaluate performance, and refine strategies for long-term sustainability.
+### Component Organization
+
+Components are organized by functionality:
+
+- **`/components/layout/`** - Layout components (Header, Footer)
+- **`/components/forms/`** - Form components (Login, Registration)
+- **`/components/features/`** - Feature-specific components
+- **`/components/common/`** - Reusable common components
+- **`/components/ui/`** - Base UI components (shadcn/ui)
+
+### Service Layer
+
+- **`/services/api/`** - REST API service functions
+- **`/services/web3/`** - Blockchain interaction services
+
+### Utility Functions
+
+- **`/lib/utils/`** - Reusable utility functions
+- **`/lib/constants/`** - Application constants
+- **`/lib/validators/`** - Validation functions
+
+## 🔧 Configuration
+
+### TypeScript
+
+The project uses strict TypeScript configuration with:
+
+- Path aliases for clean imports
+- Strict type checking
+- Modern ES features
+
+### ESLint & Prettier
+
+- Airbnb TypeScript ESLint configuration
+- Prettier for code formatting
+- Husky for pre-commit hooks
+
+### Tailwind CSS
+
+- Custom design system
+- Responsive breakpoints
+- Dark mode support
+
+## 🌐 Web3 Integration
+
+### Supported Networks
+
+- Ethereum Mainnet
+- Polygon
+- Arbitrum One
+- Test networks (Goerli, Mumbai)
+
+### Contract Integration
+
+- DeCleanup smart contracts
+- Wallet connection (RainbowKit)
+- Transaction management
+
+## 📱 Responsive Design
+
+The application is built with a mobile-first approach and supports:
+
+- Mobile devices (320px+)
+- Tablets (768px+)
+- Desktop (1024px+)
+- Large screens (1280px+)
+
+## 🧪 Testing
+
+```bash
+# Run tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## 📦 Deployment
+
+### Vercel (Recommended)
+
+1. Connect your GitHub repository to Vercel
+2. Configure environment variables
+3. Deploy automatically on push to main branch
+
+### Manual Deployment
+
+```bash
+# Build the application
+npm run build
+
+# Start production server
+npm run start
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Code Style
+
+- Follow TypeScript best practices
+- Use ESLint and Prettier
+- Write meaningful commit messages
+- Add tests for new features
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+If you encounter any issues or have questions:
+
+1. Check the [documentation](./STRUCTURE.md)
+2. Search existing [issues](../../issues)
+3. Create a new issue with detailed information
+
+## 🙏 Acknowledgments
+
+- [Next.js](https://nextjs.org/) - React framework
+- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS
+- [shadcn/ui](https://ui.shadcn.com/) - UI components
+- [Ethers.js](https://ethers.org/) - Ethereum library
+- [RainbowKit](https://rainbowkit.com/) - Wallet connection
+
+---
+
+Built with ❤️ for a cleaner future