🧠 QueryMind SmartCRM

AI-Powered Customer Relationship Management System using FastAPI, PostgreSQL, Neo4j, Qdrant, Gemini AI, and Machine Learning.

SmartCRM AI Database Platform

SmartCRM is a multi-database CRM demo that combines PostgreSQL, Neo4j, Qdrant, and a churn-prediction machine learning module behind a FastAPI backend. The repository has been reorganized into production-friendly, lowercase snake_case folders so it is easier to understand, maintain, and publish on GitHub.

Overview

The system exposes CRM data through a REST API and a browser dashboard. PostgreSQL powers the core customer and order data, Neo4j models social relationships, Qdrant handles vector similarity search, and the machine learning module predicts churn risk from customer behavior.

Features

• REST API built with FastAPI
• Dashboard UI served from the backend
• PostgreSQL customer and order analytics
• Neo4j graph traversal and influence analysis
• Qdrant vector similarity search for customers and products
• Churn prediction model powered by scikit-learn
• Separate setup scripts for each service boundary

System Architecture

flowchart LR
    U[User / Browser] --> B[backend / FastAPI]
    B --> P[database / PostgreSQL]
    B --> G[graph_database / Neo4j]
    B --> V[vector_database / Qdrant]
    B --> Q[query_router / intent router]
    B --> M[machine_learning / churn model]
    Q --> P
    Q --> G
    Q --> V

Loading

Technology Stack

• Python 3.10+
• FastAPI
• Uvicorn
• PostgreSQL
• Neo4j
• Qdrant
• scikit-learn
• NumPy
• Faker

Repository Structure

project-root/
├── backend/
│   ├── app/
│   └── requirements.txt
├── database/
│   ├── schema/
│   ├── seed/
│   ├── services/
│   ├── requirements.txt
│   └── setup_db.py
├── docs/
│   └── SETUP_GUIDE.md
├── graph_database/
│   ├── schema/
│   ├── seed/
│   ├── services/
│   └── requirements.txt
├── machine_learning/
│   ├── churn_model.py
│   ├── churn_model.pkl
│   └── label_encoder.pkl
├── query_router/
│   └── query_router.py
├── vector_database/
│   ├── collections/
│   ├── seed/
│   ├── services/
│   └── requirements.txt
├── attendance_system_final.ino
├── run_all_setup.ps1
└── README.md

Installation

1. Install Python 3.10 or newer.
2. Install PostgreSQL.
3. Install Docker Desktop if you will run Qdrant locally.
4. Create and activate a virtual environment.
5. Install the service dependencies:

pip install -r database\requirements.txt
pip install -r graph_database\requirements.txt
pip install -r vector_database\requirements.txt
pip install -r backend\requirements.txt

6. Follow the detailed Windows instructions in docs/SETUP_GUIDE.md.

Environment Variables

Each service keeps its own local .env file. These files are intentionally excluded from version control.

• POSTGRES_URL - PostgreSQL connection string used by the database service and ML module
• NEO4J_URL - Neo4j bolt URL
• NEO4J_USER - Neo4j username
• NEO4J_PASSWORD - Neo4j password
• QDRANT_HOST - Qdrant host, usually localhost
• QDRANT_PORT - Qdrant port, usually 6333
• GEMINI_API_KEY - Optional AI router key for intent routing

Running the Project

Start the API from the backend folder:

cd backend
uvicorn app.main:app --reload --port 8000

Helpful URLs:

• Dashboard: http://localhost:8000/
• API docs: http://localhost:8000/docs
• Health check: http://localhost:8000/health

You can also use run_all_setup.ps1 from the project root to install dependencies and run the setup scripts.

API Overview

The backend keeps the existing API surface intact. Main route groups include:

• /customers - customer browsing and churn-related endpoints
• /analytics - dashboard metrics and ML predictions
• /graph - Neo4j graph queries
• /similarity - Qdrant similarity search
• /ai - natural-language query router

Database Components

• database contains the PostgreSQL schema, seed data, and service layer.
• graph_database contains the Neo4j schema, seed script, and service layer.
• vector_database contains the Qdrant collection setup, seed script, and service layer.

Each database keeps its own requirements.txt so service dependencies remain isolated and easy to install.

Machine Learning Module

The machine_learning folder contains the churn model training and inference script plus the generated model artifacts.

• churn_model.py trains and runs churn prediction
• churn_model.pkl stores the trained model
• label_encoder.pkl stores the label encoder used by inference

📸 Screenshots

🏠 QueryMind Dashboard

The main dashboard providing an overview of customer insights, analytics, and AI-powered CRM features.

---

🤖 AI Query Assistant

Natural language interface that enables users to interact with CRM data using AI-powered queries.

---

📉 Customer Churn Prediction

Machine learning model that predicts customer churn and provides actionable insights for retention strategies.

---

🌐 Social Graph Explorer

Interactive graph visualization powered by Neo4j to explore customer relationships and network connections.

---

Future Improvements

• Add automated tests for the backend and service layers
• Add CI validation for formatting and dependency checks
• Externalize sample credentials into documented template files
• Add a deployment workflow for the FastAPI backend
• Split the dashboard assets into a dedicated frontend package if the UI grows further

Contributors

• Original academic project contributors
• Repository maintenance and structure cleanup by Copilot

License

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