Tagline: "Run Your Duka, Smarter."
A complete, production-ready SaaS platform built for small retail businesses in Kenya/East Africa.
dukaflow/
├── frontend/ # React + Vite Frontend Application
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── pages/ # Page components
│ │ ├── services/ # API service layer
│ │ ├── hooks/ # Custom React hooks
│ │ ├── utils/ # Utility functions
│ │ └── context/ # React Context providers
│ ├── public/ # Static assets
│ ├── package.json
│ └── vite.config.js
│
├── backend/ # Node.js + Express Backend API
│ ├── config/ # Database, auth, email configs
│ ├── models/ # Mongoose schemas
│ ├── controllers/ # Route controllers
│ ├── routes/ # API routes
│ ├── middleware/ # Auth, validation middleware
│ ├── services/ # Business logic services
│ ├── jobs/ # Cron jobs (6 automated tasks)
│ ├── sockets/ # Socket.io real-time setup
│ ├── utils/ # Helper utilities
│ └── package.json
│
└── README.md # This file
- Node.js 18+ installed
- MongoDB installed or MongoDB Atlas account
- npm or yarn package manager
cd frontend
npm install
npm run devFrontend will be available at: http://localhost:5173
Open a new terminal:
cd backend
npm installCreate .env file (copy from .env.example):
cp .env.example .envUpdate the .env file with your MongoDB connection string:
PORT=5000
MONGODB_URI=mongodb://localhost:27017/dukaflow
JWT_SECRET=your_super_secret_jwt_key_change_this
JWT_EXPIRE=7d
NODE_ENV=development
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
CLIENT_URL=http://localhost:5173Start the backend server:
npm run devBackend API will be available at: http://localhost:5000
- Landing Page - Conversion-optimized with animations
- Authentication - Sign In & Multi-step Sign Up
- Dashboard - Real-time stats, charts, alerts
- Inventory Management - Product CRUD, filters, search
- Sales/POS - Point of Sale interface, transaction history
- Worker Management - Team management, performance tracking
- Reports - Daily, weekly, monthly analytics
- Settings - Shop profile, billing, multi-branch
- Super Admin Panel - Platform management
- RESTful API - Complete CRUD operations
- JWT Authentication - Secure token-based auth
- Multi-Tenancy - Shop-based data isolation
- 6 Automated Cron Jobs:
- Daily Reports (9:00 PM EAT)
- Weekly Reports (Monday 8:00 AM EAT)
- Monthly P&L (1st of month 8:00 AM EAT)
- Low Stock Checks (Every 2 hours)
- Expiry Alerts (Daily 8:00 AM EAT)
- Trial Expiry (Daily midnight)
- Real-Time Updates - Socket.io integration
- Email Notifications - Automated reports & alerts
- React 19 - UI framework
- Vite - Build tool
- Tailwind CSS - Styling
- React Router - Navigation
- Recharts - Data visualization
- Socket.io Client - Real-time updates
- Axios - HTTP client
- Lucide React - Icons
- Node.js - Runtime
- Express - Web framework
- MongoDB + Mongoose - Database
- JWT - Authentication
- Socket.io - Real-time server
- Node-Cron - Scheduled tasks
- Nodemailer - Email service
- bcryptjs - Password hashing
- Business profile, settings, subscription
- Multi-branch support
- Custom categories & attributes
- Authentication, roles, permissions
- Active session tracking
- Worker management
- Inventory tracking
- Stock alerts, expiry dates
- Custom attributes (size, color, etc.)
- POS transactions
- Payment methods (Cash, M-Pesa, Card)
- Profit calculations
- Real-time alerts
- Email notifications
- User preferences
- Each shop gets isolated data
- Shop-specific rooms for real-time updates
- Subdomain routing ready (
[shop].dukaflow.com)
- Live stock updates
- Instant sale notifications
- Worker activity tracking
- Alert system
- Daily sales summaries via email
- Weekly performance insights
- Monthly P&L statements
- Smart alerts (low stock, expiry)
- JWT authentication with HTTP-only cookies
- Password hashing (bcrypt)
- Session management
- Role-based access control
/- Landing page/signin- Login/signup- Multi-step registration
/dashboard- Overview/dashboard/inventory- Product management/dashboard/sales- Sales & POS/dashboard/workers- Team management/dashboard/reports- Analytics/dashboard/settings- Configuration
/admin- Super admin panel
Frontend (.env):
VITE_API_URL=http://localhost:5000/apiBackend (.env):
PORT=5000
MONGODB_URI=mongodb://localhost:27017/dukaflow
JWT_SECRET=your_secret_key
JWT_EXPIRE=7d
NODE_ENV=development
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
CLIENT_URL=http://localhost:5173cd frontend
npm run build
vercel --prodcd backend
# Set environment variables in dashboard
npm start- Create cluster at mongodb.com/cloud/atlas
- Whitelist server IP
- Get connection string
- Update
MONGODB_URIin backend.env
- Complete Implementation Guide - Full technical details
- Deployment Guide - Production setup
- Quick Start Guide - Get started in 5 minutes
- Auth Pages Improvements - Design updates
- Primary: Indigo (#312E81)
- Accent: Terracotta (#E8835C)
- Success: Green (#10B981)
- Warning: Amber (#F59E0B)
- Danger: Red (#EF4444)
- M-Pesa: Green (#43B02A)
- Font: Inter (sans-serif)
- Numbers: JetBrains Mono (monospace)
- Buttons, Cards, Badges, Forms
- Modal, Drawer, Switch
- Navigation (Sidebar, TopBar, MobileNav)
cd frontend
npm testcd backend
npm test- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open Pull Request
This project is proprietary software. All rights reserved.
- Email: support@dukaflow.com
- Documentation: Complete Implementation Guide
- Issues: GitHub Issues
Built with ❤️ for Kenyan Dukas
Run Your Duka, Smarter.
✅ COMPLETE - Production Ready
- 11 Pages implemented
- 6 Automated cron jobs
- Real-time Socket.io integration
- Complete API layer
- Multi-tenant architecture
- Deployment configurations
Last Updated: April 8, 2026