Mumosa - AI-Driven Retail Supply Chain Management System

A comprehensive, microservices-based retail supply chain management platform that leverages AI/ML for forecasting, route optimization, and analytics.

🚀 Features

Core Functionality

• 📊 Real-time Dashboard - Comprehensive overview of retail operations
• 🔮 AI-Powered Forecasting - Multiple ML models (Prophet, LSTM, XGBoost, Ensemble)
• 🗺️ Route Optimization - Advanced algorithms for delivery optimization
• 🏪 Store Management - Complete store lifecycle management
• 📦 Product Management - Inventory tracking and analytics
• 📈 Advanced Analytics - Deep insights into business performance

Technical Features

• Microservices Architecture - Scalable and maintainable design
• Real-time Data Processing - Live updates and notifications
• RESTful APIs - Comprehensive API endpoints
• Containerized Deployment - Docker-based infrastructure
• Monitoring & Observability - Prometheus + Grafana integration
• Responsive UI - Modern React frontend with Tailwind CSS

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Frontend│    │   Go Backend    │    │  Python Services│
│   (Port 3000)   │◄──►│   (Port 8080)   │◄──►│  (Port 8000/8001)│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   PostgreSQL    │
                    │   (Port 5432)   │
                    └─────────────────┘

Service Breakdown

1. Frontend (React + TypeScript + Tailwind)

   • Modern, responsive UI
   • Real-time data visualization
   • Interactive dashboards

2. Backend (Go + Gin)

   • RESTful API endpoints
   • Database operations
   • Business logic

3. Forecast Service (Python + FastAPI)

   • ML model training and inference
   • Time series forecasting
   • Model evaluation

4. Routing Service (Python + FastAPI)

   • Route optimization algorithms
   • Vehicle routing problem solving
   • Geographic clustering

5. Database (PostgreSQL)

   • Reliable data storage
   • ACID compliance
   • Complex queries support

🛠️ Technology Stack

Frontend

• React 18 - UI framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• React Query - Data fetching
• React Router - Navigation
• Recharts - Data visualization
• Lucide React - Icons

Backend

• Go 1.21 - Backend language
• Gin - Web framework
• GORM - ORM
• PostgreSQL - Database
• Redis - Caching

ML Services

• Python 3.11 - ML runtime
• FastAPI - API framework
• Prophet - Time series forecasting
• TensorFlow/Keras - Deep learning
• XGBoost - Gradient boosting
• OR-Tools - Optimization
• Pandas/NumPy - Data processing

Infrastructure

• Docker - Containerization
• Docker Compose - Orchestration
• Nginx - Reverse proxy
• Prometheus - Monitoring
• Grafana - Visualization

📦 Installation & Setup

Prerequisites

• Docker & Docker Compose
• Node.js 18+ (for development)
• Go 1.21+ (for development)
• Python 3.11+ (for development)

Quick Start (Production)

1. Clone the repository

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

2. Start all services

   docker-compose up -d

3. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8080
   • Forecast Service: http://localhost:8000
   • Routing Service: http://localhost:8001
   • Grafana: http://localhost:3001 (admin/admin)

Development Setup

1. Frontend Development

   cd frontend
   npm install
   npm run dev

2. Backend Development

   cd retail-backend
   go mod download
   go run cmd/main.go

3. Forecast Service Development

   cd forecast-service
   pip install -r requirements.txt
   uvicorn api.main:app --reload --port 8000

4. Routing Service Development

   cd routing-service
   pip install -r requirements.txt
   uvicorn api.main:app --reload --port 8001

🚀 Usage

Dashboard

• View real-time metrics and KPIs
• Monitor store performance
• Track inventory levels
• Analyze sales trends

Forecasting

1. Select a forecasting model (Prophet, LSTM, XGBoost, or Ensemble)
2. Configure forecast parameters
3. Generate predictions
4. View accuracy metrics and confidence intervals

Route Optimization

1. Select optimization algorithm (Dijkstra, A*, OR-Tools VRP)
2. Configure route parameters
3. Optimize delivery routes
4. View route maps and statistics

Store Management

• Add, edit, and delete stores
• Track store performance
• Manage store information
• View store analytics

Product Management

• Manage product catalog
• Track inventory levels
• Monitor product performance
• Set reorder points

📊 API Documentation

Main Backend (Go)

• Base URL: http://localhost:8080
• Health: GET /health
• Stores: GET/POST/PUT/DELETE /stores
• Products: GET/POST/PUT/DELETE /products
• Sales: GET/POST/PUT/DELETE /sales
• Analytics: GET /analytics/*

Forecast Service (Python)

• Base URL: http://localhost:8000
• Health: GET /health
• Models: GET /models
• Forecast: POST /forecast
• Training: POST /models/{model}/train

Routing Service (Python)

• Base URL: http://localhost:8001
• Health: GET /health
• Optimize: POST /optimize
• Routes: GET/POST/PUT/DELETE /routes

🔧 Configuration

Environment Variables

Frontend

VITE_API_BASE_URL=http://localhost:8080
VITE_FORECAST_API_URL=http://localhost:8000
VITE_ROUTING_API_URL=http://localhost:8001

Backend

DB_HOST=localhost
DB_PORT=5432
DB_NAME=mumosa
DB_USER=mumosa_user
DB_PASSWORD=mumosa_password
DB_SSL_MODE=disable
PORT=8080

Forecast Service

DATABASE_URL=postgresql://mumosa_user:mumosa_password@localhost:5432/mumosa
MODEL_PATH=/app/models
LOG_LEVEL=INFO

Routing Service

DATABASE_URL=postgresql://mumosa_user:mumosa_password@localhost:5432/mumosa
LOG_LEVEL=INFO

📈 Monitoring

Prometheus Metrics

• Application metrics available at /metrics endpoints
• Custom business metrics
• Performance monitoring

Grafana Dashboards

• Pre-configured dashboards for:
  • System performance
  • Business metrics
  • ML model performance
  • API usage statistics

🧪 Testing

Frontend Tests

cd frontend
npm test

Backend Tests

cd retail-backend
go test ./...

API Tests

# Test all services
./scripts/test_apis.sh

🚀 Deployment

Production Deployment

1. Set up production environment variables
2. Configure SSL certificates
3. Set up monitoring and alerting
4. Deploy using Docker Compose or Kubernetes

Kubernetes Deployment

kubectl apply -f infra/k8s/

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📝 License

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

🆘 Support

• Documentation: Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

Phase 1: Core Features ✅

• Basic CRUD operations
• Dashboard implementation
• ML forecasting models
• Route optimization

Phase 2: Advanced Features 🚧

• Real-time notifications
• Advanced analytics
• Mobile app
• Multi-tenant support

Phase 3: Enterprise Features 📋

• Advanced security
• Audit logging
• API rate limiting
• Performance optimization

---

Built with ❤️ for modern retail supply chain management