# shunta6855/animora-recsys architecture

> Architecture diagram of the GitHub repository shunta6855/animora-recsys, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shunta6855/animora-recsys
- Repository: https://github.com/shunta6855/animora-recsys

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Animora App"]:::client

    %% Online Inference Layer
    subgraph "Timeline API Gateway" 
        direction TB
        TimelineMain["main.py"]:::service
        TimelineMerger["recommender.py"]:::service
        TimelineMain --> TimelineMerger
    end

    subgraph "Heuristic Service (Phase 1)" 
        direction TB
        HS_Main["main.py"]:::service
        HS_Logic["heuristic.py"]:::service
        HS_DB["query_runner.py"]:::service
        HS_Main --> HS_Logic
        HS_Main --> HS_DB
    end

    subgraph "NeuCF Inference Service (Phase 2)" 
        direction TB
        NS_Main["main.py"]:::service
        NS_Data["data.py"]:::service
        NS_Engine["engine.py"]:::service
        NS_MM["mmneucf.py"]:::service
        NS_Metrics["metrics.py"]:::service
        NS_Utils["utils.py"]:::service
        NS_Main --> NS_Data
        NS_Main --> NS_Engine
        NS_Main --> NS_MM
        NS_Main --> NS_Metrics
        NS_Main --> NS_Utils
    end

    %% Offline Training Layer
    subgraph "Offline Trainer (NeuCF)" 
        direction TB
        TrainerMain["main.py"]:::offline
        Trainer_Data["data.py"]:::offline
        Trainer_Engine["engine.py"]:::offline
        Trainer_MM["mmneucf.py"]:::offline
        Trainer_Metrics["metrics.py"]:::offline
        Trainer_Utils["utils.py"]:::offline
        TrainerMain --> Trainer_Data
        TrainerMain --> Trainer_Engine
        TrainerMain --> Trainer_MM
        TrainerMain --> Trainer_Metrics
        TrainerMain --> Trainer_Utils
    end

    %% Data Stores & Infrastructure
    Redis["Redis Cache"]:::cache
    Postgres["PostgreSQL"]:::db
    S3["Model Artifact Store (S3)"]:::cloud
    Monitoring["Monitoring/Logging"]:::monitor

    %% Interactions
    Client -->|calls /timeline| TimelineMain
    TimelineMain -->|check cache| Redis
    Redis -->|cache miss| HS_Main
    Redis -->|cache miss| NS_Main
    HS_Main -->|query| Postgres
    NS_Main -->|query| Postgres
    TimelineMerger -->|merge & store| Redis
    TimelineMerger -->|respond| Client

    TrainerMain -->|pull data| Postgres
    TrainerMain -->|push model| S3
    TrainerMain -.->|seed cache| Redis

    NS_Main -->|load model| S3

    %% Monitoring
    Monitoring -.-> Client
    Monitoring -.-> TimelineMain
    Monitoring -.-> HS_Main
    Monitoring -.-> NS_Main
    Monitoring -.-> TrainerMain

    %% Click Events
    click HS_Main "https://github.com/shunta6855/animora-recsys/blob/main/s01_heuristic/main.py"
    click HS_Logic "https://github.com/shunta6855/animora-recsys/blob/main/s01_heuristic/recommender/heuristic.py"
    click HS_DB "https://github.com/shunta6855/animora-recsys/blob/main/s01_heuristic/database/query_runner.py"
    click TimelineMain "https://github.com/shunta6855/animora-recsys/blob/main/timeline/main.py"
    click TimelineMerger "https://github.com/shunta6855/animora-recsys/blob/main/timeline/recommender/recommender.py"
    click NS_Main "https://github.com/shunta6855/animora-recsys/blob/main/s02_recsys_neucf/main.py"
    click NS_Data "https://github.com/shunta6855/animora-recsys/blob/main/s02_recsys_neucf/neucf/data.py"
    click NS_Engine "https://github.com/shunta6855/animora-recsys/blob/main/s02_recsys_neucf/neucf/engine.py"
    click NS_MM "https://github.com/shunta6855/animora-recsys/blob/main/s02_recsys_neucf/neucf/mmneucf.py"
    click NS_Metrics "https://github.com/shunta6855/animora-recsys/blob/main/s02_recsys_neucf/neucf/metrics.py"
    click NS_Utils "https://github.com/shunta6855/animora-recsys/blob/main/s02_recsys_neucf/neucf/utils.py"
    click TrainerMain "https://github.com/shunta6855/animora-recsys/blob/main/s02_train_neucf/main.py"
    click Trainer_Data "https://github.com/shunta6855/animora-recsys/blob/main/s02_train_neucf/neucf/data.py"
    click Trainer_Engine "https://github.com/shunta6855/animora-recsys/blob/main/s02_train_neucf/neucf/engine.py"
    click Trainer_MM "https://github.com/shunta6855/animora-recsys/blob/main/s02_train_neucf/neucf/mmneucf.py"
    click Trainer_Metrics "https://github.com/shunta6855/animora-recsys/blob/main/s02_train_neucf/neucf/metrics.py"
    click Trainer_Utils "https://github.com/shunta6855/animora-recsys/blob/main/s02_train_neucf/neucf/utils.py"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0366D6,color:#000
    classDef cache fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef db fill:#F0FFF0,stroke:#228B22,color:#000
    classDef offline fill:#FFE8B5,stroke:#FF8C00,color:#000
    classDef client fill:#F5F5F5,stroke:#888,color:#000
    classDef cloud fill:#E8F0FE,stroke:#1E56A0,color:#000
    classDef monitor fill:#F9ECEC,stroke:#D73A49,color:#000
```
