https://github.com/ray8118/anime-recommendation
NekoRec is a full-stack web application for personalized anime recommendations. It features anime browsing, detailed views, genre exploration, and content-based recommendations using FastAPI (Python) for the backend with Gemini Embeddings and React (TypeScript) for the frontend.
https://github.com/ray8118/anime-recommendation
anime-search anime-website embeddings fastapi mongodb-atlas python typescript
Last synced: about 2 months ago
JSON representation
NekoRec is a full-stack web application for personalized anime recommendations. It features anime browsing, detailed views, genre exploration, and content-based recommendations using FastAPI (Python) for the backend with Gemini Embeddings and React (TypeScript) for the frontend.
- Host: GitHub
- URL: https://github.com/ray8118/anime-recommendation
- Owner: RaY8118
- Created: 2025-07-16T18:12:38.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2025-08-21T11:55:16.000Z (about 2 months ago)
- Last Synced: 2025-08-21T13:35:16.707Z (about 2 months ago)
- Topics: anime-search, anime-website, embeddings, fastapi, mongodb-atlas, python, typescript
- Language: TypeScript
- Homepage: https://nekorec.pages.dev
- Size: 481 KB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ✨ NekoRec: Anime Recommendation System
NekoRec is a full-stack web application designed to provide personalized anime recommendations. Users can browse anime, view details, explore by genre, and receive recommendations based on content similarity.
## 🚀 Features
- 📚 **Browse Anime:** Explore a wide collection of anime.
- 🎬 **Anime Details:** View detailed information about each anime, including synopsis, genres, and more.
- 🏷️ **Genre Exploration:** Filter and discover anime by various genres.
- ❤️ **Personalized Recommendations:** Get anime recommendations based on content similarity (e.g., description, genres).
- 💡 **Suggest Anime:** Functionality for users to suggest new anime
- 💬 **AI Chatbot:** Interact with an AI chatbot for anime recommendations and information.
## 🛠️ Technologies Used
### 🐍 Backend
- **Python:** The core programming language.
- **FastAPI:** A modern, fast (high-performance) web framework for building APIs with Python 3.7+.
- **uv:** A fast Python package installer and resolver.
- **Gemini Embeddings:** Used for generating vector embeddings of anime descriptions for content-based recommendations.
- **Gemini API:** Utilized for the AI chatbot functionality.
- **MongoDB:** NoSQL database used for storing anime data and embeddings.
- **Anilist API:** Data for anime is sourced from the Anilist API.
- **Data Processing:** Custom scripts for fetching anime data, text cleaning, generating embeddings, and calculating similarity for recommendations.
### 🌐 Frontend
- **React:** A JavaScript library for building user interfaces.
- **TypeScript:** A typed superset of JavaScript that compiles to plain JavaScript.
- **Vite:** A fast build tool that provides a lightning-fast development experience.
- **Tanstack Query:** For efficient data fetching, caching, and state management.
- **Tailwind CSS:** A utility-first CSS framework for rapidly building custom designs.
- **ESLint:** For code linting and maintaining code quality.
## 🏁 Getting Started
Follow these instructions to set up and run the project locally.
### 📋 Prerequisites
- **Python 3.9+** (or the version specified in `.python-version` in the `backend` directory)
- **Node.js** (LTS version recommended) or **Bun** (if using `bun.lock`)
- **Git**
### ⚙️ Backend Setup
1. Navigate to the `backend` directory:
```bash
cd backend
```
2. Install `uv` (if you don't have it):
```bash
pip install uv
```
3. Create a virtual environment and install dependencies using `uv`:
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt # Or uv pip install -e . if pyproject.toml is configured for editable install
```
_Note: If `requirements.txt` is not present, `uv.lock` is used. You might need to run `uv pip install` directly or `uv sync`._
4. Run the FastAPI application:
```bash
uvicorn app.main:app --reload
```
The backend API will be available at `http://127.0.0.1:8000` (or similar).
### 🖥️ Frontend Setup
1. Navigate to the `frontend` directory:
```bash
cd frontend
```
2. Install dependencies using npm, yarn, or bun:
```bash
npm install
# or yarn install
# or bun install
```
3. Start the development server:
```bash
npm run dev
# or yarn dev
# or bun dev
```
The frontend application will be available at `http://localhost:5173` (or similar).
## 📂 Project Structure
```
.
├── .gitignore
├── backend/ # FastAPI backend application
│ ├── .python-version # Specifies the exact Python version
│ ├── .venv/ # Python virtual environment
│ ├── uv.lock # Lock file for `uv` dependency management
│ ├── app/ # Main FastAPI application code
│ │ ├── routers/ # API endpoints (e.g., animes, ping)
│ │ ├── schemas/ # Pydantic models for data validation
│ │ └── utils/ # Utility functions (embeddings, similarity, data fetching, text cleaning)
│ ├── fetch_anime.py # Script for fetching and processing anime data
│ ├── Dockerfile # Docker configuration for the backend
│ └── pyproject.toml # Project configuration and dependencies (Poetry/Rye)
├── frontend/ # React/TypeScript frontend application
│ ├── bun.lock # Lock file for Bun package manager
│ ├── eslint.config.js # ESLint configuration for code quality
│ ├── public/ # Static assets
│ ├── src/ # Frontend source code
│ │ ├── components/ # Reusable React components
│ │ ├── hooks/ # Custom React hooks
│ │ ├── pages/ # Main application pages/views
│ │ ├── services/ # API service integrations
│ │ └── types/ # TypeScript type definitions
│ ├── package.json # Frontend dependencies and scripts
│ ├── tailwind.config.js # Tailwind CSS configuration
│ └── vite.config.ts # Vite build configuration
└── README.md # This project README file
```
## 🚀 Deployment
### Backend
The backend is deployed as a Docker image on Docker.
### Frontend
The frontend is deployed on Cloudflare Pages.
## 🤝 Contributing
Contributions are welcome! Please feel free to open issues or submit pull requests.