🤝 Contributing to UtilityX

Welcome to UtilityX — a hybrid fintech + Web3 marketplace for telecom utilities.

We’re building a dual-rail financial system (NGN + USDT) with escrow at its core. Your contributions help make this vision real 🚀

---

📌 Contribution Philosophy

We follow these principles:

• Simplicity first (MVP mindset)
• Security is critical (especially escrow & wallet logic)
• User experience matters (fintech-level UX)
• Modular architecture (easy to scale Web2 → Web3)

---

🧱 Project Structure

Frontend (React Native)
Backend (Node.js + Express)
Smart Contracts (Web3 escrow)

---

🚀 Getting Started

1. Fork the Repository

Click Fork and clone your version:

git clone https://github.com/your-username/utilityx.git
cd utilityx

---

2. Install Dependencies

Backend

cd backend
npm install

Frontend

cd frontend
pnpm install

---

3. Environment Setup

Create a .env file:

PORT=5000
MONGO_URI=your_database_url
JWT_SECRET=your_secret

PAYSTACK_SECRET=your_key
REDIS_URL=your_redis_url

---

4. Run the Project

Backend

npm run dev

Frontend

pnpm expo start

---

🛠️ How to Contribute

🧩 Types of Contributions

We welcome:

• 🐛 Bug fixes
• ✨ New features
• 🎨 UI improvements
• ⚡ Performance optimization
• 🔐 Security improvements
• ⛓️ Smart contract development

---

🧭 Workflow

1. Create a new branch:

git checkout -b feature/your-feature-name

2. Make your changes

3. Commit clearly:

git commit -m "feat: add escrow release logic"

4. Push your branch:

git push origin feature/your-feature-name

5. Open a Pull Request 🚀

---

🧪 Code Standards

✅ General Rules

• Use TypeScript where applicable
• Keep functions small and readable
• Use meaningful variable names
• Avoid unnecessary complexity

---

📁 Naming Conventions

• camelCase → variables/functions
• PascalCase → components
• kebab-case → file names

---

🔐 Security Guidelines (VERY IMPORTANT)

When contributing to:

Wallet / Escrow:

• Never directly modify balances
• Always use transaction/ledger logic
• Validate all inputs

Smart Contracts:

• Prevent re-entrancy
• Handle edge cases (refunds, disputes)
• Test thoroughly before submission

---

🧪 Testing

Before submitting:

• Test your feature locally
• Ensure no breaking changes
• Validate API responses

---

📦 Pull Request Guidelines

Your PR must include:

• Clear title
• Description of changes
• Screenshots (if UI related)
• Test steps

---

⚠️ What NOT to Do

• ❌ Don’t push directly to main
• ❌ Don’t break existing flows
• ❌ Don’t hardcode secrets
• ❌ Don’t bypass escrow logic

---

💡 Areas You Can Contribute

• Marketplace filtering system
• Escrow engine improvements
• Wallet performance
• UI/UX enhancements
• Web3 wallet integration
• Smart contract optimization

---

🧠 Architecture Awareness

UtilityX uses a hybrid model:

Web2 → NGN → Backend Escrow
Web3 → USDT → Smart Contract Escrow

All contributions must respect this structure.

---

🙌 Community

Be respectful, collaborative, and open-minded. We’re building something ambitious together.

---

📄 License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

🚀 Final Note

UtilityX is more than an app.

It’s building a new financial layer for utilities in Africa.

Let’s build it right. 💪