Skip to content

Home

Jump to bottom
Dawid Olko edited this page May 10, 2025 · 3 revisions

SmartRecommender Wiki

Welcome to the official wiki for SmartRecommender, a comprehensive full-stack product recommendation platform. This wiki provides documentation on how to use, configure, and extend the system.

Table of Contents

  1. Overview
  2. Getting Started
  3. Architecture
  4. Recommendation Algorithms
  5. Database Structure
  6. API Documentation
  7. Contribution Guidelines
  8. Troubleshooting

Overview

SmartRecommender is a full-stack platform that delivers personalized product recommendations by combining machine learning, uncertainty modeling, and user behavior analysis. The system enhances user experience through dynamic, intelligent suggestions based on real-world data.

Key Features:

  • Advanced product recommendations using multiple algorithms
  • Comprehensive admin dashboard with analytics
  • Enhanced user experience with personalized suggestions
  • Smart search functionality with typo tolerance

Tech Stack:

  • Backend: Python, Django, PostgreSQL
  • Frontend: React
  • Machine Learning: scikit-learn

Getting Started

Prerequisites

  • Python 3.8+
  • Node.js 14+
  • PostgreSQL 12+

Installation

Quick Start with Scripts

We provide ready-to-use startup scripts for both Windows and Linux:

Windows:

# Start backend
cd backend
start.bat

Start frontend (in a new terminal)


cd frontend
start.bat

Linux/macOS:

# Start backend
cd backend
chmod +x start.sh
./start.sh

Start frontend (in a new terminal)

cd frontend chmod +x start.sh ./start.sh

Manual Setup

Backend (Django):

  1. Create and activate a virtual environment:
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install backend dependencies:
pip install -r requirements.txt

  1. Configure your PostgreSQL database in .env (see .env.example for template)

  2. Apply database migrations and seed data:

python manage.py migrate
python manage.py seed
  1. Start the backend server:
python manage.py runserver

The backend will be available at http://127.0.0.1:8000/.

Frontend (React):

  1. Navigate to the frontend directory:
cd frontend
  1. Install frontend dependencies:
npm install
  1. Start the frontend server:
npm start

The frontend will be available at http://localhost:3000/.

Architecture

SmartRecommender follows a modern microservices architecture with clear separation between the frontend and backend components:

Backend Components

  • Django REST Framework: Provides API endpoints for all functionality
  • PostgreSQL Database: Stores product, user, and recommendation data
  • ML Processing Modules: Implements the various recommendation algorithms

Frontend Components

  • React Application: Provides the user interface
  • Redux State Management: Handles application state
  • Material UI Components: Provides consistent styling

Recommendation Algorithms

SmartRecommender implements six distinct recommendation approaches:

1. Collaborative Filtering

Recommends products based on purchase patterns of similar users. We implement both user-based and item-based collaborative filtering.

Detailed documentation

2. Content-Based Filtering

Recommends products with similar attributes to those a user has previously shown interest in.

Detailed documentation

3. Association Rules

Identifies products frequently bought together using the Apriori algorithm.

Detailed documentation

4. Fuzzy Search

Provides intelligent search with typo tolerance and partial matching capabilities.

Detailed documentation

5. Sentiment Analysis

Analyzes customer reviews to recommend positively reviewed products.

Detailed documentation

6. Probabilistic Methods

Predicts user purchase probabilities and product demand using statistical methods.

Detailed documentation

Database Structure

The system uses PostgreSQL with a comprehensive schema of 24 interconnected tables:

Core Entities

  • Users
  • Products
  • Categories
  • Tags

E-Commerce Functionality

  • Orders
  • Cart
  • Complaints

Recommendation Tables

  • Similarities
  • Interactions
  • Associations

Analytics Tables

  • Sentiment
  • Purchase Patterns
  • Risk Assessment

See the database documentation directory for complete database documentation and entity relationship diagrams.

API Documentation

Authentication Endpoints

Endpoint Method Description
/api/auth/login/ POST User login
/api/auth/register/ POST User registration
/api/auth/logout/ POST User logout

Contribution Guidelines

We welcome contributions to the SmartRecommender project! Please see CONTRIBUTING.md for details on how to submit changes.

Development Workflow

  1. Fork the repository
  2. Create a feature branch
  3. Implement your changes
  4. Write or update tests
  5. Submit a pull request

Code Style

  • Python code follows PEP 8
  • JavaScript code follows Airbnb style guide
  • Use meaningful variable names and include comments

Troubleshooting

Common Issues

Backend won't start

Problem: The Django server fails to start with database errors.

Solution: Check your database configuration in the .env file. Make sure your PostgreSQL server is running and the credentials are correct.

Frontend can't connect to backend

Problem: The React app shows API connection errors.

Solution: Ensure the backend server is running and check the API URL in the frontend's .env file.

Data seeding fails

Problem: The python manage.py seed command fails.

Solution: Check that your database migrations have been applied properly with python manage.py migrate.

Getting Help

If you encounter issues not covered here:

  1. Check the existing GitHub Issues
  2. Open a new issue with detailed information about your problem
  3. Contact the development team via GitHub
# SmartRecommender Wiki

Welcome to the official wiki for SmartRecommender, a comprehensive full-stack product recommendation platform. This wiki provides documentation on how to use, configure, and extend the system.

Table of Contents

  1. [Overview](#overview)
  2. [Getting Started](#getting-started)
  3. [Architecture](#architecture)
  4. [Recommendation Algorithms](#recommendation-algorithms)
  5. [Database Structure](#database-structure)
  6. [API Documentation](#api-documentation)
  7. [Contribution Guidelines](#contribution-guidelines)
  8. [Troubleshooting](#troubleshooting)

Overview

SmartRecommender is a full-stack platform that delivers personalized product recommendations by combining machine learning, uncertainty modeling, and user behavior analysis. The system enhances user experience through dynamic, intelligent suggestions based on real-world data.

Key Features:

  • Advanced product recommendations using multiple algorithms
  • Comprehensive admin dashboard with analytics
  • Enhanced user experience with personalized suggestions
  • Smart search functionality with typo tolerance

Tech Stack:

  • Backend: Python, Django, PostgreSQL
  • Frontend: React
  • Machine Learning: scikit-learn

Getting Started

Prerequisites

  • Python 3.8+
  • Node.js 14+
  • PostgreSQL 12+

Installation

Quick Start with Scripts

We provide ready-to-use startup scripts for both Windows and Linux:

Windows:

# Start backend
cd backend
start.bat

# Start frontend (in a new terminal)
cd frontend
start.bat

Linux/macOS:

# Start backend
cd backend
chmod +x start.sh
./start.sh

# Start frontend (in a new terminal)
cd frontend
chmod +x start.sh
./start.sh

Manual Setup

Backend (Django):

  1. Create and activate a virtual environment:
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install backend dependencies:
pip install -r requirements.txt

  1. Configure your PostgreSQL database in .env (see .env.example for template)

  2. Apply database migrations and seed data:

python manage.py migrate
python manage.py seed
  1. Start the backend server:
python manage.py runserver

The backend will be available at http://127.0.0.1:8000/.

Frontend (React):

  1. Navigate to the frontend directory:
cd frontend
  1. Install frontend dependencies:
npm install
  1. Start the frontend server:
npm start

The frontend will be available at http://localhost:3000/.

Architecture

SmartRecommender follows a modern microservices architecture with clear separation between the frontend and backend components:

Backend Components

  • Django REST Framework: Provides API endpoints for all functionality
  • PostgreSQL Database: Stores product, user, and recommendation data
  • ML Processing Modules: Implements the various recommendation algorithms

Frontend Components

  • React Application: Provides the user interface
  • Redux State Management: Handles application state
  • Material UI Components: Provides consistent styling

Recommendation Algorithms

SmartRecommender implements six distinct recommendation approaches:

1. Collaborative Filtering

Recommends products based on purchase patterns of similar users. We implement both user-based and item-based collaborative filtering.

[Detailed documentation](/.methods/collaborative_filtering.md)

2. Content-Based Filtering

Recommends products with similar attributes to those a user has previously shown interest in.

[Detailed documentation](/.methods/content_based_filtering.md)

3. Association Rules

Identifies products frequently bought together using the Apriori algorithm.

[Detailed documentation](/.methods/association_rules.md)

4. Fuzzy Search

Provides intelligent search with typo tolerance and partial matching capabilities.

[Detailed documentation](/.methods/fuzzy_search.md)

5. Sentiment Analysis

Analyzes customer reviews to recommend positively reviewed products.

[Detailed documentation](/.methods/sentiment_analysis.md)

6. Probabilistic Methods

Predicts user purchase probabilities and product demand using statistical methods.

[Detailed documentation](/.methods/probabilistic_methods.md)

Database Structure

The system uses PostgreSQL with a comprehensive schema of 24 interconnected tables:

Core Entities

  • Users
  • Products
  • Categories
  • Tags

E-Commerce Functionality

  • Orders
  • Cart
  • Complaints

Recommendation Tables

  • Similarities
  • Interactions
  • Associations

Analytics Tables

  • Sentiment
  • Purchase Patterns
  • Risk Assessment

See the [database documentation](/.database/) directory for complete database documentation and entity relationship diagrams.

API Documentation

Authentication Endpoints

Endpoint Method Description
/api/auth/login/ POST User login
/api/auth/register/ POST User registration
/api/auth/logout/ POST User logout

Product Endpoints

Endpoint Method Description
/api/products/ GET List all products
/api/products/<id>/ GET Get product details
/api/products/search/ GET Search products

Recommendation Endpoints

Endpoint Method Description
/api/recommendations/user/<id>/ GET Get user-based recommendations
/api/recommendations/product/<id>/ GET Get product-based recommendations
/api/recommendations/similar/ GET Get similarity-based recommendations

Admin Endpoints

Endpoint Method Description
/api/admin/dashboard/ GET Get dashboard analytics
/api/admin/sales/forecast/ GET Get sales forecasts
/api/admin/users/churn/ GET Get churn risk assessment

Contribution Guidelines

We welcome contributions to the SmartRecommender project! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to submit changes.

Development Workflow

  1. Fork the repository
  2. Create a feature branch
  3. Implement your changes
  4. Write or update tests
  5. Submit a pull request

Code Style

  • Python code follows PEP 8
  • JavaScript code follows Airbnb style guide
  • Use meaningful variable names and include comments

Troubleshooting

Common Issues

Backend won't start

Problem: The Django server fails to start with database errors.

Solution: Check your database configuration in the .env file. Make sure your PostgreSQL server is running and the credentials are correct.

Frontend can't connect to backend

Problem: The React app shows API connection errors.

Solution: Ensure the backend server is running and check the API URL in the frontend's .env file.

Data seeding fails

Problem: The python manage.py seed command fails.

Solution: Check that your database migrations have been applied properly with python manage.py migrate.

Getting Help

If you encounter issues not covered here:

  1. Check the existing [GitHub Issues](https://github.com/dawidolko/SmartRecommender/issues)
  2. Open a new issue with detailed information about your problem
  3. Contact the development team via GitHub

Clone this wiki locally