Recommendation Machine

A personalised recommendation engine that scores manga suggestions by tag-vector similarity across a 5,000-title corpus built from the AniList API.

  • Node.js
  • PostgreSQL
  • Express
  • Hono
  • Cloudflare Workers
  • AniList GraphQL API

The problem

Recommendation engines typically rely on collaborative filtering, i.e, learning from what thousands of users read together. That only works at scale. I wanted to build a system that gives meaningful, explainable recommendations from a single user's reading list alone, with no behaviour data from anyone else. The non-obvious challenge was that genre labels are far too coarse to be useful: two epic fantasy titles can have almost nothing in common as reading experiences, and naively matching on genre produces results that feel random.

Architecture

The pipeline runs in four offline stages before the server ever starts.

Crawl — the AniList GraphQL API returns the top 5,000 manga by popularity, 50 per request, with full tag, genre, relation, and community recommendation data per title. Each page is written as a gzipped JSON archive before parsing, so a schema change never requires re-crawling.

Parse — the archive is read into Postgres: nine normalised tables covering titles, tags (with per-tag rank and spoiler flags), genres, franchise relations, and the community recommendation edges used as evaluation ground truth.

Normalise — franchise groups are built via Union-Find over the relation graph, so a sequel is never recommended to someone who just finished the original. IDF weights are then computed across the tag vocabulary: a tag like Shounen appears on hundreds of titles and carries almost no signal; a tag like Time Loop or Villainess is discriminative and gets a high weight. Adult tags and format tags are zeroed out regardless, so cards never surface labels like “Full Color” or “Long Strip” that describe presentation rather than content.

Similarity — each title is represented as a weighted tag vector (rank × IDF) plus a genre bitmask. Cosine similarity over tags (75%) is blended with genre Jaccard (25%). The top 100 neighbours per title are precomputed and stored in a flat neighbours table — 500,000 pairs, ~40 MB, indexed by source. No vector math happens at request time.

Recommendation scoring

When a user submits their AniList username, their list is fetched directly from AniList in the browser (bypassing the server entirely to avoid IP restrictions), then sent to the Worker which handles only Postgres queries. Scores are normalised across AniList’s five scoring formats (100-point, 10-point, 5-star, 3-point, smiley). Each candidate title is scored against its nearest liked title in the user’s library — not the average — which preserves distinct taste clusters rather than collapsing them into a meaningless centroid. A per-source cap of five results per attribution title prevents any single entry from dominating the output.

Raw similarity scores are then percentile-normalised within each result set and mapped to a 40–97% display range, so the best match looks meaningfully different from the weakest.

Each recommendation card shows the top 5 content tags ranked by IDF weight — the tags most discriminative for that specific title, not just the most common ones across the corpus. This gives readers an immediate sense of tone and subject matter alongside the match percentage.

Evaluation

Evaluated against 29,324 community-sourced recommendation pairs from AniList — pairs the community voted as genuinely good matches.

Metric MangaMatch Genre-only baseline Lift
MRR 0.0597 0.0293 +104%
Recall@10 12.70% 5.79% +119%
Recall@20 19.37% 9.17% +111%
Recall@50 31.94% 15.78% +103%

Tag similarity with IDF weighting surfaces correct recommendations at more than double the rate of genre matching across every evaluated cutoff. The failure cases — where genre overlap beats tag similarity — are titles that share a rare genre combination but diverge on specific tags, typically cross-genre work that doesn’t fit cleanly into AniList’s tag vocabulary.

What’s next

Review sentiment is the planned next layer: sourcing long-form reviews from MangaUpdates (a public REST API with 20+ years of reader-written reviews), then using an LLM to extract 5–8 descriptive tone terms per title — words like “atmospheric”, “slow-burn”, or “morally complex” that tag vectors can’t capture. A second pass will profile a user’s own comment history to infer preferences beyond numeric scores.

What I learned

Measuring your system against a real baseline is what separates this project from a demo. Running recall and MRR against 29,000 community-sourced ground-truth pairs — and comparing against a genre-only baseline — gave me concrete numbers to defend and a clear story about where the approach works and where it doesn't. I also learned that precomputing similarity at ingest time (rather than at request time) is the single biggest architectural decision in a content-based system: it keeps the API fast regardless of corpus size and decouples the expensive math from user-facing latency entirely.

← All projects