ML-Powered Recommendation System

A recommendation system built with FastAPI and Next.js, featuring machine learning capabilities for book recommendations.

Features

• ML Pipeline with collaborative filtering, content-based filtering, and neural embeddings
• Real-time FastAPI backend with caching
• Next.js 15 frontend with TypeScript and Tailwind CSS
• Cold start handling for new users
• Interactive learning from user feedback

Quick Start

Prerequisites

• Python 3.8+
• Node.js 18+
• npm or yarn

Setup

Automated (Recommended):

# Windows
setup.bat

# Linux/macOS
./setup.sh

Manual:

# Backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python src/backend/app/integrated_server.py

# Frontend
cd frontend
npm install
npm run dev

Access

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000

Project Structure

recsys/
├── frontend/           # Next.js TypeScript app
├── src/backend/        # FastAPI backend
├── scripts/            # Testing utilities
├── data/               # Data storage
├── models/             # ML models (generated)
├── docker-compose.yml  # Container setup
└── requirements.txt    # Dependencies

Development

# Run tests
make test

# Build production
make build

# Docker deployment
docker-compose up -d

API Endpoints

• GET /api/health - Health check
• GET /api/feed/home - Personalized recommendations
• GET /api/feed/explore - Discovery feed
• POST /api/interactions - User interactions
• GET /api/users/{id}/preferences - User preferences

ML Pipeline

Hybrid approach combining:

1. Collaborative Filtering - User-item patterns
2. Content-Based Filtering - Book metadata
3. Neural Embeddings - Deep learning representations
4. Cold Start Handling - New user preference discovery

Environment Variables

DATABASE_URL=sqlite:///./data/data.db
API_HOST=0.0.0.0
API_PORT=8000
NEXT_PUBLIC_API_URL=http://localhost:8000

Architecture

• Frontend: Next.js with server-side rendering
• Backend: FastAPI with async support
• ML: Scikit-learn and FAISS for recommendations
• Storage: SQLite for development, PostgreSQL for production
• Caching: In-memory with TTL support

Performance

• Sub-100ms API response times
• 1000+ concurrent users support
• Automatic model retraining
• Efficient similarity search with FAISS