A comprehensive full-stack platform enabling customers to find, book, and pay skilled technicians for professional repairs, maintenance, and engineering services. Built with the MERN stack and featuring AI-powered matching, real-time communication, and M-Pesa payment integration.
🔗 Visit the app: https://dumuwaks.ementech.co.ke
Production Ready! The platform is live and accepting real users. Create your account to start:
- Customers: Find and book skilled technicians for your maintenance needs
- Technicians: Showcase your skills and connect with customers
- Real Payments: Integrated M-Pesa payment system (Kenya)
- Real-Time Matching: AI-powered technician matching algorithm
# Clone the repository
git clone <repository-url>
cd dumuwaks
# Quick setup
cp .env.docker.example .env.docker
nano .env.docker # Configure your environment
# Start with Docker (Recommended)
./scripts/docker-dev.sh
# OR manual setup
cd backend && npm install && npm run dev
cd frontend && npm install && npm run devAccess the app:
- Frontend: http://localhost:3000
- Backend API: http://localhost:5000
- API Docs: http://localhost:5000/api-docs
📖 Detailed setup: See QUICK_START.md
- 🔐 Authentication & Authorization - JWT-based secure auth with role management
- 👥 User Management - Customer, Technician, Admin, Support roles
- 🛠️ Service Booking - 99+ service types across 12 categories
- 💰 Smart Pricing - Dynamic pricing with distance, urgency, and time factors
- 💳 M-Pesa Integration - Seamless mobile payments
- 🤖 AI Matching - Intelligent technician matching algorithm
- 💬 Real-time Messaging - In-app chat between customers and technicians
- 📍 Location Services - Distance-based pricing and technician discovery
- ⭐ Rating & Reviews - Two-way rating system
- 🎫 Support System - Comprehensive ticket-based support
- 💳 M-Pesa Integration - Seamless STK Push payments
- 💰 Booking Fee System - 20% refundable deposit (held in escrow)
- 🔄 Completion Payment - Automatic collection of remaining balance
- 💸 Technician Payouts - 85% payout to technicians via M-Pesa B2C
- 📊 Transparent Pricing - Clear breakdown of all fees
- 🤖 Automatic Processing - Platform commission (15%) handled automatically
- ⚡ Dynamic Pricing - Based on urgency, distance, and time
- 📱 Admin Dashboard - Manage pending payouts and batch processing
- Service completion verification
- Matching preferences
- Session-based search
- Document encryption
- API rate limiting
- Comprehensive logging
- Runtime: Node.js 18+
- Framework: Express.js
- Database: MongoDB 7.0
- Cache: Redis
- Authentication: JWT
- Payment: M-Pesa Daraja API
- Documentation: Swagger/OpenAPI
- Testing: Jest
- Framework: React 18 + TypeScript
- Build Tool: Vite
- State Management: Redux Toolkit
- Routing: React Router v6
- Styling: Tailwind CSS
- HTTP Client: Axios
- UI Components: Custom component library
- Server: VPS (Ubuntu 24.04, PM2 + Nginx)
- CI/CD: GitHub Actions (zero-downtime deploy)
- SSL: Let's Encrypt / Certbot
- Containerization: Docker + Docker Compose (local dev)
- Monitoring: Health checks + PM2 logging
- Database: MongoDB Atlas (managed)
dumuwaks/
├── backend/ # Node.js/Express API
│ ├── src/
│ │ ├── controllers/ # Route controllers
│ │ ├── models/ # Mongoose models
│ │ ├── routes/ # API routes
│ │ ├── services/ # Business logic
│ │ ├── middleware/ # Custom middleware
│ │ ├── utils/ # Utility functions
│ │ ├── jobs/ # Background jobs
│ │ └── server.js # Entry point
│ ├── Dockerfile
│ └── package.json
│
├── frontend/ # React/TypeScript app
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── pages/ # Page components
│ │ ├── store/ # Redux store
│ │ ├── services/ # API services
│ │ ├── utils/ # Utility functions
│ │ └── App.tsx # Root component
│ ├── Dockerfile
│ ├── nginx.conf
│ └── package.json
│
├── docs/ # Documentation
│ ├── api/ # API documentation
│ ├── deployment/ # Deployment guides
│ ├── features/ # Feature documentation
│ ├── guides/ # How-to guides
│ ├── backend/ # Backend docs
│ └── fixes/ # Bug fixes & solutions
│
├── scripts/ # Utility scripts
│ ├── docker-dev.sh # Development deployment
│ └── docker-prod.sh # Production deployment
│
├── docker-compose.yml # Development setup
├── docker-compose.prod.yml # Production setup
├── .env.docker.example # Environment template
├── QUICK_START.md # Quick start guide
└── README.md # This file
- Quick Start Guide - Get up and running in 5 minutes
- Environment Variables - Configuration reference
- Docker Deployment - Containerized deployment
- API Routes Summary - All available endpoints
- Swagger Setup - Interactive API docs
- Swagger Testing - Testing with Swagger UI
- Pricing System - How pricing works
- M-Pesa Integration - Payment integration
- Booking Fee System - Escrow & fees
- AI Matching - Matching algorithm
- Support System - Ticket system
- Database Schema - MongoDB collections
- Implementation Summary - Architecture overview
- Contributing Guide - How to contribute
- VPS Deployment Guide - Production VPS deployment
- CI/CD Strategy - Full CI/CD pipeline details
- Docker Deployment Guide - Local Docker setup
- Node.js 18+ and npm
- MongoDB 7.0+
- Redis (optional, for caching)
- M-Pesa Developer Account
cd backend
# Install dependencies
npm install
# Configure environment
cp .env.example .env
nano .env
# Seed pricing data
npm run seed:pricing
# Start development server
npm run devcd frontend
# Install dependencies
npm install
# Configure environment
cp .env.example .env
nano .env
# Start development server
npm run dev# One command to start everything
./scripts/docker-dev.sh
# Or manually
docker-compose up -d
docker-compose logs -f# Backend tests
cd backend
npm test
# Frontend tests
cd frontend
npm testThe app is deployed on a VPS with zero-downtime blue-green deployments via GitHub Actions.
Production URLs:
- Frontend: https://dumuwaks.ementech.co.ke
- API: https://api.ementech.co.ke
- Health Check: https://api.ementech.co.ke/api/v1/health
Infrastructure:
- Ubuntu 24.04 VPS with PM2 + Nginx
- SSL via Let's Encrypt
- GitHub Actions CI/CD pipeline
- Automated rollback on health check failure
Pushing to master triggers automatic deployment.
📖 Full guide: VPS Deployment Guide | CI/CD Strategy
- Configure environment:
cp .env.docker.example .env.docker
nano .env.docker # Set development values- Start services:
./scripts/docker-dev.sh- Verify:
docker-compose ps
docker-compose logs -f📖 Full guide: Docker Deployment Guide
- JWT authentication with secure token storage
- Password hashing with bcrypt
- Environment variable protection
- Rate limiting on sensitive endpoints
- CORS configuration
- Input validation and sanitization
- Secure M-Pesa API integration
- Document encryption for sensitive data
We welcome contributions! Please see CONTRIBUTING.md for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Backend Development: Full-stack API with Node.js/Express
- Frontend Development: React/TypeScript SPA
- DevOps: Docker containerization and deployment
- M-Pesa Daraja API for payment integration
- MongoDB for database
- React and TypeScript communities
- All contributors and testers
- Documentation: See docs/ folder
- Issues: GitHub Issues
- Mobile app (React Native)
- Advanced analytics dashboard
- Multi-language support
- SMS notifications via Africa's Talking
- Automated testing suite (Jest + React Testing Library)
- Performance monitoring (New Relic/Sentry)
- CI/CD pipeline (GitHub Actions)
- Enhanced technician verification (KYC)
- Video consultations (Agora integration)
Built with ❤️ in Kenya
Connecting skilled technicians with customers who need them
