{"id":28559859,"url":"https://github.com/george-mountain/full-stack-recommendation-system","last_synced_at":"2026-04-07T21:32:17.507Z","repository":{"id":298219058,"uuid":"986053085","full_name":"george-mountain/full-stack-recommendation-system","owner":"george-mountain","description":"Full stack recommendation system with Machine learning models, FastAPI, ReactJS, Celery, Redis, Postgresql","archived":false,"fork":false,"pushed_at":"2025-06-10T01:25:11.000Z","size":2777,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-10T02:29:20.198Z","etag":null,"topics":["celery","celerybeat","docker","fastapi","gru4rec","mlops","pgadmin4","postgresql","reactjs","redis"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/george-mountain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-19T03:22:37.000Z","updated_at":"2025-06-10T01:25:14.000Z","dependencies_parsed_at":"2025-06-10T02:29:52.987Z","dependency_job_id":"2d15c1f9-b707-4c60-b518-d7e7ccf56a94","html_url":"https://github.com/george-mountain/full-stack-recommendation-system","commit_stats":null,"previous_names":["george-mountain/full-stack-recommendation-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/george-mountain/full-stack-recommendation-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/george-mountain%2Ffull-stack-recommendation-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/george-mountain%2Ffull-stack-recommendation-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/george-mountain%2Ffull-stack-recommendation-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/george-mountain%2Ffull-stack-recommendation-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/george-mountain","download_url":"https://codeload.github.com/george-mountain/full-stack-recommendation-system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/george-mountain%2Ffull-stack-recommendation-system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31530641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["celery","celerybeat","docker","fastapi","gru4rec","mlops","pgadmin4","postgresql","reactjs","redis"],"created_at":"2025-06-10T09:06:14.863Z","updated_at":"2026-04-07T21:32:17.489Z","avatar_url":"https://github.com/george-mountain.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ch3 align=\"center\"\u003eFull Stack Machine Learning Recommendation System\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    A complete ML movie recommendation system with React frontend and FastAPI backend\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/george-mountain/full-stack-recommendation-system\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"http://localhost:5173/\"\u003eView Demo\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/george-mountain/full-stack-recommendation-system/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/george-mountain/full-stack-recommendation-system/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#system-architecture\"\u003eSystem Architecture\u003c/a\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#project-structure\"\u003eProject Structure\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\nThis project is a full-stack Machine Learning movie recommendation system featuring:\n\n- React-based frontend with responsive UI\n- FastAPI backend with GRU4Rec recommendation model\n- User authentication and rating system\n- Admin interface for content management\n- Scheduled model retraining with Celery\n\nThe system provides personalized movie recommendations based on user ratings and behavior with the help of machine learning model.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Built With\n\n* [![FastAPI][FastAPI-shield]][FastAPI-url]\n* [![React][React.js]][React-url]\n* [![Postgres][Postgres-shield]][Postgres-url]\n* [![Docker][Docker-shield]][Docker-url]\n* [![Celery][Celery-shield]][Celery-url]\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- SYSTEM ARCHITECTURE --\u003e\n## System Architecture\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./images/highlevel_system_architecture.png\" alt=\"High-level System Architecture of Recommendation System\" width=\"800\"\u003e\n\u003c/div\u003e\n\nThe architecture diagram above illustrates the main components of the recommendation system:\n1. **Frontend**: React-based user interface\n2. **Backend**: FastAPI server handling requests\n3. **Database**: PostgreSQL for data persistence\n4. **Recommendation Engine**: GRU4Rec model for personalized recommendations\n5. **Celery Worker**: Background tasks for model training\n6. **Redis**: Message broker for task queue\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n[video_demo_rec_system.webm](https://github.com/user-attachments/assets/f0e759f9-a774-4cc6-ac8e-fdf041a82bc9)\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nTo get a local copy up and running follow these simple steps.\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Node.js (for frontend development)\n- Python 3.8+ (for backend development)\n\n### Installation\n\n1. Clone the repo\n   ```sh\n   git clone https://github.com/george-mountain/full-stack-recommendation-system.git\n   ```\n2. Copy environment file\n   ```sh\n   cp .env.example .env\n   ```\n3. Start the backend API container\n   ```sh\n   docker compose up --build\n   ```\n4. Populate the database with movie data\n   ```sh\n   docker compose exec app python /app/scripts/seed_db.py\n   ```\n5. Navigate to frontend and install dependencies\n   ```sh\n   cd recommendation-frontend/\n   npm install\n   npm run dev\n   ```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- PROJECT STRUCTURE --\u003e\n## Project Structure\n\n### Backend API Structure\n```\n.\n├── app/\n│   ├── __init__.py\n│   ├── main.py                 # FastAPI app, routers\n│   ├── core/\n│   │   ├── __init__.py\n│   │   └── config.py           # Settings and configurations\n│   ├── db/\n│   │   ├── __init__.py\n│   │   ├── base_class.py       # Base for SQLAlchemy models\n│   │   ├── models.py           # SQLAlchemy ORM models (User, Movie, Rating)\n│   │   ├── session.py          # Async database session setup\n│   │   └── crud.py             # CRUD operations\n│   ├── schemas/\n│   │   ├── __init__.py\n│   │   ├── movie.py            # Pydantic schemas for movies\n│   │   ├── rating.py           # Pydantic schemas for ratings\n│   │   ├── user.py             # Pydantic schemas for users\n│   │   └── token.py            # Pydantic schemas for JWT tokens\n│   ├── api/\n│   │   ├── __init__.py\n│   │   ├── deps.py             # Dependencies (e.g., get_db, get_current_user)\n│   │   └── v1/\n│   │       ├── __init__.py\n│   │       ├── api.py          # API router aggregation\n│   │       └── endpoints/\n│   │           ├── __init__.py\n│   │           ├── users.py\n│   │           ├── movies.py\n│   │           ├── ratings.py\n│   │           └── recommendations.py\n│   ├── services/\n│   │   ├── __init__.py\n│   │   └── recommender/\n│   │       ├── __init__.py\n│   │       ├── model.py        # GRU4Rec Keras model definition\n│   │       ├── predict.py      # Prediction logic\n│   │       ├── preprocessing.py # Data preprocessing for training/prediction\n│   │       └── train.py        # Training script for the model\n│   ├── worker/\n│   │   ├── __init__.py\n│   │   ├── celery_app.py       # Celery app instance and beat schedule\n│   │   └── tasks.py            # Celery tasks (e.g., model training)\n│   └── security.py             # Password hashing and JWT utilities\n├── data/                         # To store movielens raw data (optional, for initial seeding)\n│   └── ml-1m/                    # Extracted movielens data (if downloaded)\n├── models_store/                 # To save trained Keras models\n│   └── gru4rec_model.keras       # Example saved model\n├── Dockerfile\n├── docker-compose.yml\n├── requirements.txt\n└── .env_example                  # Example environment variables\n```\n\n### Frontend Structure\n```\nrecommendation-frontend/\n├── node_modules/\n├── public/\n└── src/\n    ├── assets/\n    ├── components/\n    │   ├── Admin/\n    │   │   └── AdminPage.jsx\n    │   ├── Auth/\n    │   │   └── AuthForm.jsx\n    │   ├── Common/\n    │   │   ├── DisplayAverageRating.jsx\n    │   │   ├── LoadingSpinner.jsx\n    │   │   ├── MessageBox.jsx\n    │   │   ├── MovieCard.jsx\n    │   │   ├── RatingModal.jsx\n    │   │   └── StarRatingInput.jsx\n    │   └── Icons/\n    │       ├── ArrowLeftIcon.jsx\n    │       ├── FilmIcon.jsx\n    │       ├── FilterIcon.jsx\n    │       ├── HomeIcon.jsx\n    │       ├── LockIcon.jsx\n    │       ├── LogOutIcon.jsx\n    │       ├── MenuIcon.jsx\n    │       ├── SearchIcon.jsx\n    │       ├── SettingsIcon.jsx\n    │       ├── StarIcon.jsx\n    │       ├── ThumbsUpIcon.jsx\n    │       ├── TrashIcon.jsx\n    │       ├── UploadCloudIcon.jsx\n    │       ├── UserIcon.jsx\n    │       └── XIcon.jsx\n    ├── contexts/\n    │   ├── AppContext.jsx\n    │   └── AuthContext.jsx\n    ├── Layout/\n    │   ├── Footer.jsx\n    │   └── Navbar.jsx\n    └── pages/\n    |   ├── HomePage.jsx\n    |   └── MovieDetailPage.jsx\n    └── services/\n    |    ├── ApiService.js\n    |   \n    |\n    └── styles/\n        ├── index.css\n```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- USAGE --\u003e\n## Usage\n\nAfter installation, access the services via:\n\n- Backend API docs: http://127.0.0.1:8000/docs\n- Frontend: http://localhost:5173/\n- PGAdmin: http://localhost:5050/ (credentials: admin@admin.com / admin1234)\n\n**Admin Access:**\n1. Register with email: `admin@example.com`\n2. Login and access the admin page\n3. Manage movies and retrain the recommendation model\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the MIT License. See `LICENSE.txt` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nProject Link: [https://github.com/george-mountain/full-stack-recommendation-system](https://github.com/george-mountain/full-stack-recommendation-system)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n[forks-shield]: https://img.shields.io/github/forks/george-mountain/full-stack-recommendation-system.svg?style=for-the-badge\n[forks-url]: https://github.com/george-mountain/full-stack-recommendation-system/network/members\n[stars-shield]: https://img.shields.io/github/stars/george-mountain/full-stack-recommendation-system.svg?style=for-the-badge\n[stars-url]: https://github.com/george-mountain/full-stack-recommendation-system/stargazers\n[issues-shield]: https://img.shields.io/github/issues/george-mountain/full-stack-recommendation-system.svg?style=for-the-badge\n[issues-url]: https://github.com/george-mountain/full-stack-recommendation-system/issues\n[license-shield]: https://img.shields.io/github/license/george-mountain/full-stack-recommendation-system.svg?style=for-the-badge\n[license-url]: https://github.com/george-mountain/full-stack-recommendation-system/blob/master/LICENSE.txt\n[FastAPI-shield]: https://img.shields.io/badge/FastAPI-005571?style=for-the-badge\u0026logo=fastapi\n[FastAPI-url]: https://fastapi.tiangolo.com/\n[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge\u0026logo=react\u0026logoColor=61DAFB\n[React-url]: https://reactjs.org/\n[Postgres-shield]: https://img.shields.io/badge/PostgreSQL-316192?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white\n[Postgres-url]: https://www.postgresql.org/\n[Docker-shield]: https://img.shields.io/badge/Docker-2CA5E0?style=for-the-badge\u0026logo=docker\u0026logoColor=white\n[Docker-url]: https://www.docker.com/\n[Celery-shield]: https://img.shields.io/badge/Celery-37814A?style=for-the-badge\u0026logo=celery\u0026logoColor=white\n[Celery-url]: https://docs.celeryq.dev/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorge-mountain%2Ffull-stack-recommendation-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorge-mountain%2Ffull-stack-recommendation-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorge-mountain%2Ffull-stack-recommendation-system/lists"}