MarketMatic Smart Assistant Backend

A robust, multi-tenant Smart Assistant backend powered by RAG (Retrieval-Augmented Generation) technology. This service provides intelligent chat interfaces with advanced knowledge retrieval, user authentication, document management, and tenant isolation.

---

📋 Table of Contents

• Features
• Architecture
• Tech Stack
• Prerequisites
• Installation
• Configuration
• Usage
• API Endpoints
• Database Models
• Project Structure
• Docker Deployment
• Development
• Troubleshooting
• Contributing
• License

---

🚀 Features

Core Functionality

• 🤖 RAG-Powered Chat: Intelligent question answering using Retrieval-Augmented Generation
• 👥 Multi-Tenant Architecture: Secure tenant isolation with role-based access control
• 🔐 Authentication & Authorization: JWT-based auth with superadmin, admin, and user roles
• 📄 Document Management: Upload and process PDFs, DOCX, and text documents
• 🧠 Vector Embeddings: Semantic search using Chroma vector database
• 💾 Chat Sessions: Persistent conversation history with context awareness
• 📊 Analytics & Insights: Knowledge gap tracking and chat analytics
• 🔄 Fallback LLM: Ollama with Groq API fallback for resilience
• ⚙️ Tool Integration: Extensible tool execution framework

Advanced Features

• Adaptive Relevance Filtering: Dynamic threshold adjustment based on retrieval quality
• Deduplication & Diversity: Smart selection of context chunks
• Domain-Specific Guidance: Pre-configured prompts for various business domains
• User Memory Management: Persistent user preferences and interaction history
• Rate Limiting & Error Handling: Production-grade error management
• Health Checks: Built-in service monitoring
• CORS Support: Cross-origin request handling

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Frontend Application                     │
├─────────────────────────────────────────────────────────────┤
                              │
                    HTTP/REST (CORS)
                              │
┌─────────────────────────────────────────────────────────────┐
│              Express.js Backend (Port 8000)                 │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────┐                │
│  │   Auth Routes    │  │  Chat Routes     │                │
│  │  (Auth/Roles)    │  │  (RAG Pipeline)  │                │
│  └──────────────────┘  └──────────────────┘                │
│  ┌──────────────────┐  ┌──────────────────┐                │
│  │ Document Routes  │  │ Session Routes   │                │
│  │ (Upload/Parse)   │  │ (Chat History)   │                │
│  └──────────────────┘  └──────────────────┘                │
├─────────────────────────────────────────────────────────────┤
│  Services Layer                                              │
│  ┌────────────────────────────────────────────────┐         │
│  │  RAG Service  │  Embedding  │  Tool Service    │         │
│  │  (Main Logic) │  Service    │  (Extensible)    │         │
│  └────────────────────────────────────────────────┘         │
├─────────────────────────────────────────────────────────────┤
                    │                   │
        ┌───────────┼───────────┬───────┴──────────┐
        │           │           │                  │
    MongoDB      ChromaDB    Ollama              Groq API
    (Metadata)   (Vectors)   (Local LLM)        (Fallback)

Flow Diagram: RAG Pipeline

1. User Query (Text)
   │
   ├─→ Embedding Service (Generate vector embedding)
   │
   ├─→ ChromaDB Query (Retrieve relevant chunks)
   │
   ├─→ Adaptive Filtering (Threshold validation)
   │
   ├─→ Deduplication (Remove near-duplicates)
   │
   ├─→ Context Selection (Diversity & relevance)
   │
   ├─→ System Prompt Builder (Domain guidance)
   │
   ├─→ Ollama/Groq (Generate answer)
   │
   └─→ Response with Sources + Logging

---

💻 Tech Stack

---

📋 Prerequisites

• Node.js: v20 or higher
• npm: v10 or higher
• MongoDB: v5.0+ (local or cloud)
• Docker & Docker Compose (for containerized deployment)
• Ollama (optional, for local LLM): https://ollama.ai
• Groq API Key (for fallback LLM): https://console.groq.com

---

🛠️ Installation

1. Clone the Repository

git clone https://github.com/sanudasandipa/MarketMatic-Smart-Assistant-backend.git
cd MarketMatic-Smart-Assistant-backend

2. Install Dependencies

npm install

3. Set Up Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Configure the following variables (see Configuration section).

4. Initialize Database

# Start MongoDB (if local)
mongod

# Seed superadmin user
npm run seed

5. Verify Setup

npm run dev

Visit http://localhost:8000/health to confirm the backend is running.

---

🔧 Configuration

Environment Variables

Create a .env file with the following configuration:

# ─── Server ────────────────────────────────────────────────────
NODE_ENV=development
PORT=8000
FRONTEND_URL=http://localhost:3000

# ─── Database ──────────────────────────────────────────────────
MONGODB_URI=mongodb://localhost:27017/smart-assistant
# OR for cloud:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/smart-assistant

# ─── ChromaDB (Vector Database) ────────────────────────────────
CHROMA_HOST=localhost
CHROMA_PORT=8000
CHROMA_COLLECTION_PREFIX=smart_assistant

# ─── Embedding Service ────────────────────────────────────────
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIMENSION=384

# ─── LLM Configuration ────────────────────────────────────────
# Ollama (Local)
OLLAMA_URL=http://localhost:11434
OLLAMA_CHAT_MODEL=llama3.1:8b
OLLAMA_TIMEOUT_MS=60000

# Groq API (Fallback/Cloud)
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.1-8b-instant

# ─── RAG Configuration ────────────────────────────────────────
RAG_RELEVANCE_THRESHOLD=0.35
RAG_CONTEXT_BUDGET_CHARS=8000
RAG_NEAR_DUPLICATE_OVERLAP=0.88
RAG_MAX_HISTORY=10

# ─── JWT ───────────────────────────────────────────────────────
JWT_SECRET=your_super_secret_jwt_key_change_in_production
JWT_EXPIRY=7d

# ─── File Upload ───────────────────────────────────────────────
MAX_FILE_SIZE=52428800  # 50MB
UPLOAD_DIR=./uploads

# ─── Optional: Reranking Service ──────────────────────────────
# RERANKER_URL=http://localhost:8090
# RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-12-v2

# ─── Optional: Domain Configuration ───────────────────────────
BUSINESS_DOMAIN=pharmacy  # pharmacy, electronics, clothing, etc.

Default Domains

Pre-configured domain guidance for:

• pharmacy - Medicine availability, health products
• electronics - Specs, compatibility, troubleshooting
• clothing - Sizing, style, care instructions
• restaurant - Menu, hours, reservations
• grocery - Availability, prices, promotions
• real_estate - Listings, inquiries, bookings
• automotive - Specs, servicing, parts
• education - Courses, enrollment, fees

---

🚀 Usage

Start Development Server

npm run dev

The backend will start on http://localhost:8000

Start Production Server

npm start

Seed Superadmin User

npm run seed

This creates an initial superadmin account. Review the script for credentials.

---

📡 API Endpoints

Authentication

POST   /api/auth/register     – Create new user account
POST   /api/auth/login        – Authenticate user, return JWT
POST   /api/auth/logout       – Invalidate session
GET    /api/auth/verify       – Verify JWT token

Chat & RAG

POST   /api/admin/chat        – RAG chat (Admin/Auth required)
POST   /api/chat              – Public chat (Tenant ID required)

Documents

POST   /api/admin/documents   – Upload document
GET    /api/admin/documents   – List documents
DELETE /api/admin/documents/:id – Delete document
POST   /api/admin/documents/reindex – Re-embed all documents

Chat Sessions

GET    /api/admin/sessions    – List chat sessions
GET    /api/admin/sessions/:id – Get session details
DELETE /api/admin/sessions/:id – Delete session

Knowledge Gaps

GET    /api/admin/gaps        – Get knowledge gaps
POST   /api/admin/gaps        – Record knowledge gap

User Management

GET    /api/user/profile      – Get user profile
PUT    /api/user/profile      – Update profile
GET    /api/user/memory       – Get user memory
POST   /api/user/memory       – Update user preferences

Admin

GET    /api/admin/users       – List all users
GET    /api/admin/stats       – Get platform statistics
DELETE /api/admin/users/:id   – Remove user

Superadmin

POST   /api/superadmin/tenants     – Create tenant
GET    /api/superadmin/tenants     – List tenants
PUT    /api/superadmin/tenants/:id – Update tenant
DELETE /api/superadmin/tenants/:id – Delete tenant
GET    /api/superadmin/analytics   – System analytics

Health Check

GET    /health                – Service health status

---

📚 Database Models

User

{
  email: String (unique),
  password: String (hashed),
  firstName: String,
  lastName: String,
  tenantId: ObjectId,
  serviceId: ObjectId,
  role: Enum ['user', 'admin', 'superadmin'],
  isActive: Boolean,
  lastLogin: Date,
  createdAt: Date,
  updatedAt: Date
}

Service (Tenant/Business)

{
  name: String,
  description: String,
  domain: String,
  apiKey: String,
  isActive: Boolean,
  documentCount: Number,
  chatCount: Number,
  settings: Object,
  createdAt: Date,
  updatedAt: Date
}

Document

{
  serviceId: ObjectId,
  fileName: String,
  filePath: String,
  fileSize: Number,
  fileType: String,
  chunkCount: Number,
  embeddingComplete: Boolean,
  uploadedAt: Date,
  updatedAt: Date
}

ChatSession

{
  userId: ObjectId,
  serviceId: ObjectId,
  title: String,
  messages: [{
    role: 'user' | 'assistant',
    content: String,
    timestamp: Date
  }],
  metadata: Object,
  createdAt: Date,
  updatedAt: Date
}

RagLog

{
  userId: ObjectId,
  serviceId: ObjectId,
  query: String,
  response: String,
  retrievedChunks: [String],
  relevanceScores: [Number],
  responseTime: Number,
  model: String,
  timestamp: Date
}

KnowledgeGap

{
  serviceId: ObjectId,
  query: String,
  context: String,
  frequency: Number,
  firstOccurrence: Date,
  lastOccurrence: Date,
  resolved: Boolean
}

UserMemory

{
  userId: ObjectId,
  preferences: Object,
  history: [Object],
  notes: String,
  updatedAt: Date
}

---

📁 Project Structure

MarketMatic-Smart-Assistant-backend/
├── src/
│   ├── server.js                 # Entry point
│   ├── config/
│   │   └── database.js           # MongoDB connection
│   ├── middleware/
│   │   └── auth.js              # JWT verification, role checks
│   ├── models/                  # Mongoose schemas
│   │   ├── User.js
│   │   ├── Service.js
│   │   ├── Document.js
│   │   ├── ChatSession.js
│   │   ├── RagLog.js
│   │   ├── KnowledgeGap.js
│   │   └── UserMemory.js
│   ├── routes/                  # Express route handlers
│   │   ├── auth.js
│   │   ├── admin.js
│   │   ├── superadmin.js
│   │   ├── user.js
│   │   ├── documents.js
│   │   ├── chat.js              # RAG chat endpoints
│   │   └── sessions.js
│   ├── services/                # Business logic
│   │   ├── ragService.js        # Core RAG pipeline
│   │   ├── chromaService.js     # Vector DB operations
│   │   ├── embeddingService.js  # Embeddings
│   │   ├── toolService.js       # Tool execution
│   │   ├── rerankerService.js   # Reranking (optional)
│   │   └── insightsService.js   # Analytics
│   ├── scripts/                 # Utility scripts
│   │   ├── seedSuperadmin.js
│   │   ├── reEmbed.js
│   │   └── reUpload.js
│   └── utils/
│       ├── chromaManager.js     # Chroma connectivity
│       └── tokenHelper.js       # JWT utilities
├── scripts/
│   └── reEmbedAll.js            # Batch re-embedding
├── docker-compose.yml           # Multi-container orchestration
├── Dockerfile                   # Container image
├── package.json                 # Dependencies & scripts
├── .env.example                 # Environment template
└── README.md                    # This file

---

🐳 Docker Deployment

Using Docker Compose (Recommended)

# Build and start all services
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f backend

Docker Compose Services

Services:
  - backend      (Node.js backend on port 8000)
  - mongodb      (MongoDB on port 27017, internal only)
  - chroma       (ChromaDB on port 8000, internal only)

Build Docker Image Only

docker build -t smart-assistant-backend:1.0 .

# Run container
docker run -p 8000:8000 \
  --env-file .env \
  -v smart-assistant-data:/app/chroma_data \
  smart-assistant-backend:1.0

Deploy to Azure VM

See AZURE_DEPLOYMENT.md for detailed Azure VM setup instructions.

---

💡 Development

Code Style & Linting

# Install ESLint (optional)
npm install --save-dev eslint

# Run linter
npm run lint

Hot Reload Development

npm run dev

Uses Nodemon to automatically restart on file changes.

Running Tests (if applicable)

npm test

Database Migrations

For schema changes:

1. Create a new migration script in src/scripts/migrations/
2. Run: node src/scripts/migrations/migrate-name.js
3. Document changes in migration log

---

🔧 Troubleshooting

Issue: "MongoDB Connection Error"

Solution:

# Check MongoDB is running
mongod

# Or update MONGODB_URI in .env
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/db

Issue: "ChromaDB Connection Error"

Solution:

# Ensure ChromaDB is running
# If using Docker Compose:
docker-compose up -d chroma

# Or manually:
chroma run --host localhost --port 8000

Issue: "Ollama Timeout"

Solution:

# Reduce timeout or use Groq API:
OLLAMA_TIMEOUT_MS=30000
# Enable Groq fallback:
GROQ_API_KEY=your_key

Issue: "JWT Verification Failed"

Solution:

# Verify JWT_SECRET is set correctly
echo $JWT_SECRET

# Regenerate token by logging in again
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}'

Issue: "Out of Memory"

Solution:

# Increase Node.js heap size
export NODE_OPTIONS=--max-old-space-size=4096
npm start

# Or in Docker:
docker run -e NODE_OPTIONS="--max-old-space-size=4096" ...

Issue: "CORS Errors"

Solution:

# Update FRONTEND_URL in .env
FRONTEND_URL=http://your-frontend-domain.com

---

📊 Monitoring & Logs

Health Check

curl http://localhost:8000/health

# Response:
# {
#   "status": "ok",
#   "service": "smart-assistant-backend",
#   "timestamp": "2025-05-08T10:30:00.000Z"
# }

Docker Logs

# View all services
docker-compose logs -f

# View specific service
docker-compose logs -f backend

# Follow with timestamps
docker-compose logs -f --timestamps

---

🤝 Contributing

Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature/your-feature
5. Submit a Pull Request

Guidelines

• Follow existing code style
• Add comments for complex logic
• Update README for new features
• Test thoroughly before submitting
• Use meaningful commit messages

---

📝 License

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

---

📞 Support & Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@example.com

---

🙏 Acknowledgments

• Express.js - Web framework
• MongoDB - Database
• Chroma - Vector database
• Ollama - Local LLMs
• Groq - Fast LLM inference
• Open source community

---

Built with ❤️ by MarketMatic Team

Last Updated: May 8, 2026