OFFER-HUB Orchestrator

 ██████╗ ███████╗███████╗███████╗██████╗       ██╗  ██╗██╗   ██╗██████╗
██╔═══██╗██╔════╝██╔════╝██╔════╝██╔══██╗      ██║  ██║██║   ██║██╔══██╗
██║   ██║█████╗  █████╗  █████╗  ██████╔╝█████╗███████║██║   ██║██████╔╝
██║   ██║██╔══╝  ██╔══╝  ██╔══╝  ██╔══██╗╚════╝██╔══██║██║   ██║██╔══██╗
╚██████╔╝██║     ██║     ███████╗██║  ██║      ██║  ██║╚██████╔╝██████╔╝
 ╚═════╝ ╚═╝     ╚═╝     ╚══════╝╚═╝  ╚═╝      ╚═╝  ╚═╝ ╚═════╝ ╚═════╝

---------------------- Marketplaces Orchestrator ----------------------

OFFER-HUB Orchestrator is a self-hosted payments orchestration system designed for Marketplaces. It manages a Web2-like experience (balances, top-ups, payments with escrow, and withdrawals) using Airtm for fund management and Trustless Work for non-custodial escrows on the Stellar network.

🚀 Features

• 💰 User Balances: Internal management of available and reserved balances.
• ⚡ Top-ups: Fast reloads via Airtm.
• 🤝 Smart Escrow: Secure checkout with non-custodial escrow via TW.
• 💸 Withdrawals: Direct withdrawals to Airtm accounts.
• 🔐 Secure & Audited: Native idempotency, audit logs, and modular architecture.

🛠️ Tech Stack

• Framework: NestJS (API Server)
• Runtime: Node.js 20 LTS
• Database: PostgreSQL (via Prisma ORM)
• Cache & Queues: Redis + BullMQ
• Monorepo: npm Workspaces

🏁 Quick Start

1. Clone and Prepare:

   git clone https://github.com/your-org/OFFER-HUB-Orchestrator.git
   cd OFFER-HUB-Orchestrator
   cp .env.example .env

2. Install Dependencies:

   npm install

3. Generate Database Client:

   npm run prisma:generate

4. Start Infrastructure (Optional): If you don't have local Postgres/Redis, use Docker:

   docker compose up -d

5. Run in Development: You can start both the API and the Worker concurrently:

   npm run dev

   Note: This starts the API on port 4000 and the Worker in the same terminal.

🏗️ Project Structure

OFFER-HUB-Orchestrator/
├── apps/
│   ├── api/          # Main NestJS server (port 4000)
│   └── worker/       # Async task processor (BullMQ)
├── packages/
│   ├── shared/       # Shared code (DTOs, Enums, Utils)
│   ├── database/     # Prisma schema and migrations
│   └── sdk/          # Official client SDK for marketplaces
├── docs/             # Comprehensive documentation
├── src/              # Legacy Next.js frontend (deprecated)
└── backend/          # Legacy Express backend (deprecated)

📚 Documentation

Comprehensive documentation is available in the /docs folder:

Quick Start

• 🧠 AI.md - Development guide for AI assistants (Read first!)
• 📖 Main Documentation - Complete documentation index

Core Documentation

• 📐 Architecture Overview - System architecture
• 📋 Project Overview - Vision, goals, and roadmap
• ❓ Problem Statement - The problems we solve
• 👥 User Personas - Who uses OFFER-HUB

Development

• 💻 Coding Standards - Code style guide
• 🔌 API Design - Backend API patterns
• 🤝 Contributing Guide - How to contribute

🎯 Use Cases

Freelance Marketplace (Primary)

Connect freelancers with clients using escrow protection:

1. Client tops up balance via Airtm
2. Client pays for project → funds go to escrow (Trustless Work)
3. Freelancer completes work
4. Client approves → funds released instantly to freelancer
5. Freelancer withdraws to Airtm

Other Marketplaces

• E-commerce: Buyer/seller escrow with delivery confirmation
• Service Marketplaces: Service booking with payment protection
• Digital Goods: Instant or escrow-based delivery
• Gig Economy: Worker/client escrow with job completion

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: /docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions

👥 Maintainers

• @Josue19-08 - Project Lead & Full-Stack Developer
• @KevinMB0220 - Core Contributor & Developer

🙏 Acknowledgments

Built with ❤️ for the decentralized marketplace future.

• NestJS - Progressive Node.js framework
• Prisma - Next-generation ORM
• BullMQ - Premium message queue
• Airtm - Payment infrastructure
• Trustless Work - Non-custodial escrow on Stellar

---

🚀 Empowering marketplaces with trustless payments 🚀

---