CX Miner

CX Miner is an automated customer feedback mining platform that leverages Retrieval-Augmented Generation (RAG) and IBM watsonx.ai to collect and transform unstructured customer feedback from various channels into actionable business insights.

---

Table of Contents

• Overview
• Key Features
• Architecture
• Technology
• Getting Started
• Folder Structure
• Core Modules
• Deployment
• Contributing
• License
• Acknowledgements

---

Project Overview

CX Miner ingests, analyzes, and categorizes customer feedback from diverse channels ( including Google, Facebook, Trustpilot, Yelp, CSVs, and more). It applies AI-driven sentiment analysis, summarizes key themes, and generates reports to drive business decisions. The platform is tailored for customer service intensive industries especially travel, hospitality, and service sectors seeking to elevate their customer experience via intelligent feedback management.

---

Key Features

• Multi-channel Feedback Integration : Connectors for Google Business, Facebook Reviews, Trustpilot, Yelp, CSV, and document uploads.
• Real-time Sentiment Analysis : AI-driven processing using IBM watsonx.ai for sentiment, impact, and topic clustering.
• Actionable Insights : Automated RAG summaries, impact scoring, executive reports, and prioritized action queues.
• Smart Dashboards : Interactive dashboards and explorers for deep feedback analysis and trend tracking.
• Role-based Access Control (RBAC) : Supports roles such as Admin, Manager, Analyst, and Viewer.
• Team Collaboration : Workspace-based data segregation and multi-user management.
• Extensible Connector Framework : Easily add new feedback sources.
• Export and Reporting : Generate PDF/CSV reports, and schedule email digests.
• CX Assistant (AI Chatbot) : (Optional) Interactive AI-powered chat for instant feedback Q&A.

---

Architecture

• Frontend : Bootstrap + JavaScript (with Jinja templates for Flask integration)
• Backend : Python (Flask) with SQLAlchemy ORM, Alembic for migrations
• Database : SQLite (dev/demo), easily upgradable to PostgreSQL/MySQL via SQLAlchemy
• AI Integration : IBM watsonx.ai for vector embeddings, sentiment analysis, summarization, and executive insights
• Real-time : Flask-SocketIO for streaming updates and live dashboard features
• Containerization : Docker support for consistent deployments

Data Flow

1. Ingestion : Connector scrapes/imports reviews → normalizes data
2. AI Processing : watsonx.ai generates sentiment, summaries, suggestions
3. Storage : All data persisted in structured tables
4. Presentation : UI updates in real-time (SocketIO) for dashboards and reports
5. Action & Reporting : Users explore, tag, act, and export insights

---

Technology

• Python 3.10+
• Flask
• SQLAlchemy, Alembic
• Bootstrap 5, JavaScript
• Jinja2 Templates
• Flask-SocketIO
• IBM watsonx.ai SDK
• Docker

---

Getting Started

1. Repository Setup

git clone https://github.com/broadcomms/cxminer.git
cd cxminer
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

2. Configuration

• Copy .env.example to .env and fill in secrets (API keys, DB url, etc.)
• Never commit your .env file, make sure it is already excluded in .gitignore and .dockerignore.

3. Database Migration

Initialize Alembic/Flask-Migrate:

# Set the Flask app environment variable
export FLASK_APP=run.py
# Initialize migrations folder
flask db init
# This will create a `migrations/` folder
# Generate the first migrate
flask db migrate -m "Initial migration: create user table"

Migrate the database:

flask db upgrade

4. Running the App

flask run

or via Docker:

docker build -t cxminer .
docker run --env-file .env -p 5001:5001 cxminer

---

Folder Structure

cxminer/
│
├── app/
│   ├── __init__.py
│   ├── config.py
│   ├── models.py
│   ├── sockets.py
│   ├── extensions.py
│   ├── main/
│   ├── auth/
│   ├── account/
│   ├── workspace/
│   ├── integration/
│   ├── explorer/
│   ├── action/
│   ├── report/
│   ├── static/
│   ├── templates/
│   └── util/
│
├── migrations/
├── requirements.txt
├── Dockerfile
├── .dockerignore
├── .gitignore
├── run.py
├── README.md
├── LICENSE
├── CONTRIBUTING.md
└── .env.example

---

Core Modules

• auth/ : Registration, login, password reset, JWT/session management
• account/ : User account/profile management
• workspace/ : Multi-workspace management, RBAC, settings
• integration/ : Data connectors (Google, Facebook, Trustpilot, etc.)
• explorer/ : Deep feedback analysis and suggestions
• action/ : Action queue for needs-reply, escalation, feature requests
• report/ : Report generation, export, scheduling

---

Deployment

• Supports Docker-based deployment.
• Reference Dockerfile and environment variable templates provided.
• Staging/Production:
  • IBM CodeEngine or your preferred cloud provider.

---

Contributing

See CONTRIBUTING.md for guidelines on bug reports, feature requests, and code contributions.

---

License

Distributed under the MIT License. See LICENSE for details.

---

Acknowledgements

• IBM watsonx.ai for AI services (vector embeddings, summarization, sentiment analysis)
• Flask and open-source contributors

---

For technical documentation, API reference, and further instructions, see the docs/ directory (coming soon).

---

Copyright (c) 2025 CX Miner