How shunta6855/animora-recsys works
Project type and purpose
• This repository implements the backend recommendation pipeline for the Animora pet-photo SNS.
• It is a distributed recommendation system comprised of:
• Phase 1: a rule‐based heuristic for fast, bootstrap recommendations
• Phase 2: a Neural Collaborative Filtering (NeuCF) service for personalized ranking
• An offline training pipeline for NeuCF
• A “timeline” microservice that exposes the recommendation API to the frontend
• Technologies: Python, FastAPI, PyTorch, PostgreSQL, Redis, Docker, AWS.
File structure
Top-level modules each represent a component in the pipeline:
• s01_heuristic – the rule‐based recommender service
– main.py (FastAPI entrypoint)
– recommender/heuristic.py (scoring logic)
– database/… (PostgreSQL queries via query_runner.py)
– Dockerfile, requirements.txt
• s02_recsys_neucf – the online NeuCF inference service
– main.py (FastAPI entrypoint)
– neucf/… (model loading, scoring, metrics)
– recommender/neucf_rec.py (wraps heuristic + NeuCF)
– utils/settings & model config
• s02_train_neucf – the offline training pipeline
– main.py (training orchestration)
– neucf/… (data prep, engine, mmneucf implementation)
– database/… (loads historical interactions from PostgreSQL)
• timeline – the API gateway for the user’s feed
– main.py (FastAPI to serve /timeline endpoint)
– recommender/recommender.py (calls s01 & s02 services, merges results)
– Dockerfile, requirements.txt
README insights
• Animora App → Timeline Service → Redis Cache → Heuristic & NeuCF services → PostgreSQL
• Offline trainer writing model artifacts and seeding Redis
• The NeuCF architecture (images/neucf_architecture.png) details the latent‐factor model.