Fuuud

Smart Food Ordering Platform with AI Intelligence and Blockchain Rewards

Fuuud is a production-ready food commerce platform designed for emerging markets. It combines native food ordering, AI-powered recommendations, and multi-chain blockchain payments with Stellar-powered micro-rewards infrastructure. The platform enables seamless vendor onboarding, intelligent customer discovery, and scalable reward distribution through blockchain technology.

---

Strategic Vision

Fuuud builds modern food economy infrastructure with the following objectives:

• Seamless Ordering Experience: Intuitive, mobile-first interface optimized for low-bandwidth environments
• Vendor Digitization: Simple tools for food businesses to manage menus, pricing, and sales analytics
• User Rewards: Automatic incentive mechanisms for order completion and engagement
• Flexible Payments: Multi-chain blockchain support for diverse payment methods
• Scalable Settlements: Instant, low-cost vendor payouts via Stellar infrastructure

---

Core Capabilities

Smart Ordering Engine

• Real-time vendor discovery with location-based filtering
• Responsive cart and checkout flow
• Mobile-first design optimized for emerging market connectivity
• Complete order history and reorder functionality

Order Management & Tracking

• Live order status updates from preparation to delivery
• Transparent vendor-to-customer communication
• Historical order analytics and trending patterns

Vendor Management Platform

• Menu and pricing administration
• Inventory and availability control
• Sales analytics and performance metrics
• Automatic payout notifications

AI Recommendation System

• Budget-constrained meal suggestions
• Personalized vendor recommendations
• Dietary preference and cuisine learning
• Demand forecasting for vendor optimization

Reward Distribution System

• Automatic reward calculation (2–5% per order)
• Referral program infrastructure
• Loyalty tier system
• Blockchain-verified reward ledger

Multi-Chain Blockchain Infrastructure

• Primary Layer: Stellar network for micro-rewards and settlements
• Low transaction fees (0.00001 XLM base)
• High-frequency transaction support
• Testnet and mainnet compatibility
• Future expansion to Polygon, Arbitrum, and other chains

---

Technical Architecture

Frontend Infrastructure

• Framework: Next.js 14 with React 18
• Styling: Tailwind CSS with custom design system
• UI Components: Modular, reusable component library
• Build Target: Production-optimized with SSG/SSR support

Backend Infrastructure

• Runtime: Node.js with Express.js
• Database: MongoDB with Mongoose ODM
• Authentication: JWT-based with role-based access control
• Blockchain Integration: Stellar SDK with testnet support

Service Layer Architecture

/backend
  /controllers        Current request handlers
  /models             Current MongoDB schemas
  /routes             Current API route definitions
  /services           Current external integrations
  /middleware         Authentication and shared middleware
  app.js              Express server configuration

/frontend
  /src/pages          Current Next.js page routes
  /src/components     Current reusable React components
  /src/styles         Tailwind and global styles
  next.config.js      Next.js build configuration

Target Modular Architecture

As Fuuud grows into a food discovery marketplace, the backend should move toward feature modules. Each module owns its routes, controller, service, and model files.

/backend/src/modules
  /auth               Login, registration, roles, sessions
  /users              Customer profiles, health preferences, wallets
  /vendors            Vendor onboarding, menu tools, analytics
  /orders             Cart checkout, order lifecycle, reorder flows
  /payments           Card, transfer, USSD, gateway references
  /escrow             Hold customer payment until delivery is complete
  /payouts            Vendor settlement and payout history
  /rewards            XLM rewards, referrals, loyalty, bonuses
  /blockchain         Stellar SDK and future Soroban escrow contracts
  /ai                 Health-aware food recommendations
  /feed               Vendor videos, images, captions, hashtags, sounds
  /comments           Customer comments on food posts
  /follows            Customer-to-vendor follow graph
  /riders             Rider registration, verification, availability
  /deliveries         Delivery assignment, tracking, proof of delivery
  /dispatch-partners  Third-party logistics company integrations
  /notifications      Admin, vendor, rider, and customer messages
  /admin              Approvals, campaigns, disputes, platform controls
  /whatsapp           WhatsApp ordering and vendor/customer messages

---

Getting Started

System Requirements

• Node.js 18.x or higher
• npm 9.x or higher
• MongoDB 5.x or higher (local or Atlas)
• Git 2.x or higher

Installation Guide

1. Repository Setup

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

2. Backend Configuration

cd backend
npm install

# Create environment configuration
cp .env.example .env

# Fill local values in .env using .env.example as the template.
# Never commit .env.

npm run dev

Backend API accessible at http://localhost:5000

3. Frontend Configuration

cd ../frontend
npm install

# Create environment configuration
cp .env.local.example .env.local

# Fill local values in .env.local using .env.local.example as the template.

npm run dev

Frontend application accessible at http://localhost:3000

---

Configuration

Do not put real secrets in the README, issues, pull requests, screenshots, or commits.

Use the checked-in example files only as templates:

• backend/.env.example
• frontend/.env.local.example

Create local files from those templates and keep them private:

cp backend/.env.example backend/.env
cp frontend/.env.local.example frontend/.env.local

The real files are ignored by Git. Only .env.example and .env.*.example files should be committed.

---

API Reference

Authentication Endpoints

Method	Endpoint	Description
POST	/api/auth/register	Register user or vendor account
POST	/api/auth/login	Authenticate and receive JWT token

Vendor Endpoints

Method	Endpoint	Description
GET	/api/vendors	List all verified vendors
GET	/api/vendors/:id/menu	Retrieve vendor menu items
POST	/api/vendor/menu	Add new menu item (vendor only)
GET	/api/vendor/orders	Retrieve vendor orders (vendor only)

Order Management

Method	Endpoint	Description
POST	/api/orders	Create new order
GET	/api/orders/:id	Retrieve order details

Reward System

Method	Endpoint	Description
POST	/api/rewards/process	Process and distribute rewards

Integration Endpoints

Method	Endpoint	Description
POST	/webhook/whatsapp	WhatsApp bot webhook handler

---

Data Models

User Schema

{
  name: String,                    // Full name
  email: String,                   // Unique email address
  password: String,                // bcrypt-hashed password
  walletAddress: String,           // Stellar public key
  rewardsBalance: Number,          // Accumulated rewards in USD
  role: String,                    // 'user' | 'vendor' | 'admin'
  createdAt: Date,
  updatedAt: Date
}

Vendor Schema

{
  name: String,                    // Business name
  email: String,                   // Unique email address
  password: String,                // bcrypt-hashed password
  menu: [ObjectId],                // Array of FoodItem references
  createdAt: Date,
  updatedAt: Date
}

FoodItem Schema

{
  name: String,                    // Menu item name
  price: Number,                   // Price in USD
  image: String,                   // Image URL
  available: Boolean,              // Availability status
  vendorId: ObjectId,              // Reference to Vendor
  createdAt: Date,
  updatedAt: Date
}

Order Schema

{
  userId: ObjectId,                // Reference to User
  vendorId: ObjectId,              // Reference to Vendor
  items: [
    {
      itemId: ObjectId,
      name: String,
      price: Number,
      quantity: Number
    }
  ],
  totalAmount: Number,             // Order total in USD
  status: String,                  // 'pending' | 'confirmed' | 'delivered'
  rewardAmount: Number,            // Calculated reward (2-5% of total)
  rewardTxHash: String,            // Stellar transaction hash
  createdAt: Date,
  updatedAt: Date
}

---

Security Implementation

Authentication & Authorization

• JWT tokens with 7-day expiration window
• Role-based access control (RBAC) for vendor and admin operations
• Secure password hashing with bcrypt (10 salt rounds)

Data Protection

• Environment variable isolation for sensitive configuration
• Stellar secret keys restricted to backend only
• CORS configuration for frontend origin only
• Input validation and sanitization on all endpoints

Infrastructure Security

• HTTPS/TLS enforcement in production
• Secure MongoDB connection with authentication
• Rate limiting on authentication endpoints
• Comprehensive error handling without data leakage

---

AI Recommendation Engine

Functionality

The AI assistant provides intelligent recommendations through the following mechanisms:

• Budget-Based Suggestions: Meal recommendations filtered by user budget constraints
• Vendor Intelligence: Performance-based vendor ranking and discovery
• Cuisine Personalization: Learning user preferences over order history
• Demand Forecasting: Vendor analytics for popular items and optimal pricing

Current Implementation

Mock recommendation responses with structure for LLM integration. Production deployment integrates with OpenAI or similar LLM services.

Extension Points

• Historical order analysis for preference learning
• Real-time inventory integration
• Multi-language support for diverse markets
• Dietary restriction and allergy management

---

Stellar Blockchain Integration

Reward Distribution Architecture

1. Order Placement: User completes purchase ($10 order)
2. Reward Calculation: System calculates reward percentage (2–5% = $0.20–$0.50)
3. Blockchain Transaction: Create Stellar transaction with user wallet address
4. Settlement: Testnet transaction processes with instant confirmation
5. Ledger Recording: Transaction hash stored in Order document
6. Balance Update: User's reward balance updated in real-time

Technical Specifications

• Network: Stellar TESTNET (development) or PUBLIC (production)
• Base Fee: 0.00001 XLM per transaction
• Settlement Time: < 5 seconds average
• Throughput: Supports 1000+ transactions per second
• Account Funding: Development uses Stellar Development Foundation testnet faucet

Production Readiness

• Testnet configuration for development and QA
• Mainnet configuration for production deployment
• Multi-signature wallet support for vendor settlements
• Transaction monitoring and reconciliation tools

---

Project Structure

The repository currently uses a simple MVP layout. The corrected target structure below shows where each major Fuuud product area should live as the app grows: food ordering, TikTok-style food discovery, rider delivery, admin notifications, escrow payments, and Stellar/XLM rewards.

fuuud/
  backend/
    app.js
    package.json

    src/
      config/
        db.js
        env.js

      middleware/
        auth.middleware.js
        error.middleware.js
        validate.middleware.js

      modules/
        auth/
          auth.routes.js
          auth.controller.js
          auth.service.js

        users/
          user.model.js
          user.routes.js
          user.controller.js
          user.service.js

        vendors/
          vendor.model.js
          vendor.routes.js
          vendor.controller.js
          vendor.service.js
          vendor-analytics.service.js

        food/
          food-item.model.js
          food.routes.js
          food.controller.js
          food.service.js

        feed/
          post.model.js
          sound.model.js
          hashtag.model.js
          feed.routes.js
          feed.controller.js
          feed.service.js

        comments/
          comment.model.js
          comment.routes.js
          comment.controller.js
          comment.service.js

        follows/
          follow.model.js
          follow.routes.js
          follow.controller.js
          follow.service.js

        orders/
          order.model.js
          order.routes.js
          order.controller.js
          order.service.js

        payments/
          payment.model.js
          payment.routes.js
          payment.controller.js
          payment.service.js
          gateway.service.js

        escrow/
          escrow.model.js
          escrow.routes.js
          escrow.controller.js
          escrow.service.js

        payouts/
          payout.model.js
          payout.routes.js
          payout.controller.js
          payout.service.js

        rewards/
          reward.model.js
          reward.routes.js
          reward.controller.js
          reward.service.js
          leaderboard.service.js

        blockchain/
          stellar.service.js
          soroban-escrow.service.js

        ai/
          ai.routes.js
          ai.controller.js
          ai.service.js
          health-rules.js

        riders/
          rider.model.js
          rider.routes.js
          rider.controller.js
          rider.service.js

        deliveries/
          delivery.model.js
          delivery.routes.js
          delivery.controller.js
          delivery.service.js

        dispatch-partners/
          dispatch-partner.model.js
          dispatch-partner.routes.js
          dispatch-partner.controller.js
          dispatch-partner.service.js

        notifications/
          notification.model.js
          notification.routes.js
          notification.controller.js
          notification.service.js

        admin/
          admin.routes.js
          admin.controller.js
          admin.service.js
          campaign.model.js
          dispute.model.js

        whatsapp/
          whatsapp.routes.js
          whatsapp.controller.js
          whatsapp.service.js

      utils/
        logger.js
        response.js

  frontend/
    package.json
    next.config.js
    tailwind.config.js

    src/
      pages/
        _app.js
        index.js
        login.js
        register.js
        feed.js
        post/[id].js
        vendors/[id].js
        orders/[id].js
        delivery/track/[id].js
        admin/dashboard.js
        admin/notifications.js
        admin/vendors.js
        vendor/dashboard.js
        vendor/menu.js
        vendor/orders.js
        vendor/posts.js
        rider/register.js
        rider/dashboard.js

      components/
        ui/
          Button.js
          Input.js
          Modal.js

        layout/
          Navbar.js
          Sidebar.js

        ai/
          AIChat.js
          RecommendationCard.js

        feed/
          FoodPostCard.js
          FoodVideoCard.js
          CommentDrawer.js
          HashtagList.js
          SoundBadge.js
          OrderFromPostButton.js

        vendors/
          VendorCard.js
          MenuItemCard.js
          VendorStats.js

        orders/
          Cart.js
          OrderStatus.js
          CheckoutSummary.js

        delivery/
          DeliveryTracker.js
          DeliveryStatusTimeline.js

        rider/
          RiderRegistrationForm.js
          DeliveryRequestCard.js

        notifications/
          NotificationBell.js
          NotificationList.js
          NotificationCard.js

        admin/
          AdminSidebar.js
          BroadcastForm.js
          VendorApprovalTable.js
          RiderApprovalTable.js

      services/
        api.js
        auth.js
        vendors.js
        orders.js
        payments.js
        rewards.js
        feed.js
        ai.js
        notifications.js

      hooks/
        useAuth.js
        useCart.js
        useNotifications.js

      styles/
        globals.css

  contracts/
    soroban/
      fuuud-escrow/
        Cargo.toml
        src/lib.rs

  README.md
  .gitignore

MVP Migration Path

• Keep the current backend/controllers, backend/models, backend/routes, and backend/services while building the MVP.
• Move to backend/src/modules when features start growing and files become hard to manage.
• Build payments first with normal gateways and backend escrow, then add Soroban escrow after the business flow is stable.
• Keep Stellar/XLM rewards separate from customer payment collection.
• Add feed, notifications, riders, and admin modules early because they are central to vendor adoption.

---

Design System

Color Palette

Element	Color Code	Usage
Primary	#f97316	Primary actions, food branding
Secondary	#7c3aed	AI features, intelligence indicators
Tertiary	#2563eb	Trust, blockchain verification
Background	#f8fafc	Page backgrounds, neutral spaces

Typography Guidelines

• Headings: Bold, high contrast, tracking-tight
• Body: Clean sans-serif (Inter system font), 16px base
• UI Elements: Rounded corners (24px, 20px, 16px)
• Spacing: 8px base grid system

---

Development Workflow

Local Development

# Terminal 1: Backend
cd backend && npm run dev

# Terminal 2: Frontend
cd frontend && npm run dev

Production Build

# Backend
cd backend
npm install --production
npm start

# Frontend
cd frontend
npm run build
npm start

Testing Workflow

1. Register test user account at /register
2. Register test vendor account at /register
3. Authenticate as vendor for menu management
4. Authenticate as user and browse vendors
5. Place order and verify reward calculation
6. Inspect Stellar transaction hash in browser console

---

Feature Status

Implemented Features

• ✓ User and vendor authentication (JWT-based)
• ✓ Vendor menu management system
• ✓ Order creation and tracking
• ✓ Reward calculation and Stellar integration
• ✓ Modern responsive UI with Tailwind CSS
• ✓ Mobile-optimized design
• ✓ WhatsApp webhook infrastructure

In Development

• AI recommendation engine with LLM integration
• Vendor dashboard analytics
• Order delivery tracking
• Multi-language support

Planned Features

• In-app wallet (fiat + crypto)
• Advanced vendor credit scoring
• Delivery logistics optimization
• Tokenized loyalty program

---

Implementation Roadmap

Phase 1: MVP (Complete)

• Core ordering and vendor workflows
• Basic reward distribution on testnet
• AI chat interface with mock responses

Phase 2: Enhanced Intelligence

• LLM-based recommendation system
• Real WhatsApp bot integration
• Polygon and Arbitrum payment support
• Vendor performance analytics

Phase 3: Ecosystem Expansion

• Delivery partner integration
• Advanced user personalization
• Tokenized rewards program
• Cross-vendor loyalty features

Phase 4: Regional Scale

• Multi-market deployment
• Advanced logistics network
• Regional payment methods
• Enterprise vendor programs

---

Contributing Guidelines

Contributions are welcome! Please read CONTRIBUTING.md for:

• Local development setup
• Branching/PR expectations
• Coding guidelines and bug reports

---

License

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

---

Support and Contact

Resources

• Issue Tracking: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Refer to API Reference section above

For Production Deployments

Contact: enterprise@codevanguard01.com

---

Deployment Considerations

Production Infrastructure Requirements

• MongoDB Atlas or self-hosted MongoDB 5.x+
• Node.js 18.x runtime environment
• Next.js hosting (Vercel recommended)
• Stellar mainnet account for production rewards
• TLS/HTTPS certificate

Performance Optimization

• Database indexing on frequently queried fields
• Redis caching for vendor and menu data
• CDN distribution for static assets
• Load balancing for backend API
• Image optimization and lazy loading

Monitoring and Observability

• Application logging with ELK stack
• Stellar transaction monitoring
• API performance metrics
• Error tracking and alerting
• Uptime monitoring

---

Fuuud: Building the future of food commerce infrastructure for emerging markets.