Design friend suggestions

Design "people you may know" for the social app from D39: a short list of accounts each user is likely to want to follow, shown on the home screen and after sign-up. The graph has 400 billion edges, so the obvious approach (look at friends of friends) produces trillions of candidates a day. The design is about cutting that down without losing the good ones, keeping suggestions fresh, and never suggesting someone in a way that leaks private information.

1. The prompt

"Design the 'people you may know' feature: suggest accounts a user might want to follow."

What makes it hard:

• The candidate space explodes. Friends of friends for one user can be tens of thousands of people; for a user who follows a celebrity, hundreds of millions.
• Freshness matters most right after an action. Someone who just followed five colleagues expects to see the rest of the team, not yesterday's list.
• A suggestion can reveal a secret. "Why is my therapist suggesting her other patients?" A suggestion must never be explainable only by private data.

2. Frame the problem

3. What it must do

1. Return a ranked list of suggested accounts for a user, quickly, for each placement.
2. Find candidates from several sources: friends of friends, contacts, shared school or workplace, people who interact with the user.
3. React to new actions: a follow, a dismissal or a contact upload changes the next list.
4. Respect limits: never suggest blocked users, people already followed, dismissed suggestions, or anyone who opted out of being found by phone number or email.

Not now: suggested groups or pages, explaining the model's internals, ads ("promoted accounts" go through the ad system, D41).

4. How well it must do it

5. Numbers that change the design

Illustrative numbers. Play with the pruning in the lab in section 13.

6. The nouns

• Candidate: a (user, suggested account) pair with the sources that produced it.
• Features: facts about the pair: mutual follows, shared contacts, same workplace, how active the candidate is, how often they follow back.
• Score: the model's estimate that the user will follow and keep following.
• Suggestion list: the top few hundred scored candidates per user, with the reason to show ("Followed by Chen and 4 others").
• Exclusions: blocked, dismissed, already followed, opted out.

suggestions   user_id → [(candidate_id, score, reason_code, sources)] × 300, computed_at     key-value store
fresh         user_id → [(candidate_id, score, reason_code)] × 50, expires in 24 h            key-value store (near-line)
dismissed     (user_id, candidate_id) → dismissed_at                                         key-value store
contacts      hash(normalised phone or email) → [user_ids who uploaded it]                   only with consent
discoverable  user_id → {by_phone, by_email}                                                 settings

7. The contract

GET  /v1/suggestions?placement=home&limit=20     → [{user, reason: "Followed by Chen and 4 others"}], request_id
POST /v1/suggestions/{candidate}:dismiss                 → 204
POST /v1/contacts:upload  {hashes[]}  (opt-in)           → 202
Events consumed: Followed, Unfollowed, Blocked, ContactsUploaded, ProfileViewed
Events produced: SuggestionShown, SuggestionFollowed, SuggestionDismissed   (training data)

The reason string is chosen from public facts only (mutual follows, a shared workplace the candidate made public). If the only link between two people is private, they aren't suggested at all.

8. First working version

Three paths. A nightly batch computes a long list for every active user. A near-line stream job adds fresh candidates after an action. A small serving service merges both, filters and returns the top of the list.

8.1 The nightly batch

8.2 Serving a request

9. Make it hold up

9.1 Taming the two-hop explosion cost

The candidate generators are separate and each is cheap: two-hop over strong ties, contacts (a join on hashed identifiers), shared workplace or school (an inverted index from workplace to members, sampled), and "people who view your profile or reply to you". Each contributes a few hundred candidates; the ranking model decides between them.

9.2 Fresh after a follow freshness

9.3 A brand-new user cold start

• Contacts, with consent. The app hashes normalised phone numbers and emails on the device and uploads the hashes; we match them to accounts that allow being found that way. This is the single strongest early signal.
• Sign-up context: who invited them (and that person's network), the language and country, interests picked during onboarding.
• Popular and local accounts as a fallback, chosen per country and interest.
• Then the near-line path takes over: the first few follows produce a two-hop neighbourhood within a minute.

9.4 Ranking: what to optimise quality

A gradient-boosted tree over a few hundred features is a solid start (Module 29 covers serving models). The batch scores everything nightly; the serving path re-scores only the top 100 with fresh features.

9.5 Privacy: suggestions that leak trust

• Contacts are one-directional evidence. If only you have my number, that says nothing about whether I want to find you. Respect each person's "let people find me by phone or email" setting, and be careful with matches that would reveal who has whose number (a patient suggested to a doctor).
• Every suggestion needs a public reason. If the only link is private (an uploaded contact, a profile view), either show a vague reason or don't suggest.
• Blocks are absolute, in both directions, and checked at serving time as well as in the batch, because a block made an hour ago isn't in last night's lists.
• Sensitive groups: some product decisions exclude whole signal types (location, health-related groups). The pipeline enforces them centrally, not per model.
• Deletion: a deleted account is removed from every stored list and from the next training data.

9.6 Feedback loops quality

Suggestions create follows, which create more suggestions: popular accounts get more popular, and the model learns mostly from what it already chose to show. Keep a small share of exploration (candidates the model is unsure about), log the position each suggestion was shown in so training can correct for it, and watch the share of follows going to the top 1% of accounts. Spammers also try to get suggested: candidates with sudden follower growth or many dismissals are demoted until reviewed.

9.7 The whole design after the deep dives

10. Interviewer follow-ups

11. When things break

12. Wrap-up and the clock

Trade-offs we made:

• Precompute in batch, refresh near-line, filter and lightly re-rank at serving time.
• Prune the graph walk (strong ties only, no walking through huge accounts), accepting that a few weak candidates are missed.
• Several candidate sources, one ranking model optimising for lasting connections.
• Privacy rules and blocks enforced centrally and again at serving time; fail closed.

What we'd watch: follow rate and follow-back rate from suggestions · dismiss and block rates · list age · near-line lag · share of follows to the top 1% of accounts · batch job duration and cost.

At 10×: the batch grows with active users × ties², so pruning thresholds tighten, or the two-hop computation moves to incremental updates (only users whose neighbourhood changed).

Common mistakes:

• A full two-hop walk on every request.
• Counting paths through celebrities.
• Only a nightly batch, so the list ignores what the user did a minute ago.
• Training on clicks alone.
• Forgetting that a block made after the batch must still apply.
• Ignoring what a suggestion reveals.

13. Try it, check yourself, read more

The two-hop explosion lab. Choose how many ties each user keeps and the largest account allowed in the middle of a path, and see the size of the nightly job.

Illustrative model: follows per user and the share of paths through large accounts come from a made-up but typical skewed distribution; a cluster joins ~2 billion path records a second.