Truecaller Caller ID and Spam Detection, the whole design.

%% title: A one-ring read path, fed by a streaming spam pipeline
flowchart TD
  AND@{ icon: "tech:android", label: "Android app<br/>contacts · device spam list" } ==> GW@{ icon: "sd:gateway", label: "Regional edge<br/>auth · rate limits" }
  IOS@{ icon: "tech:apple", label: "iPhone<br/>Live Caller ID" } ==> RELAY@{ icon: "sd:tunnel", label: "Oblivious HTTP relay<br/>run by Apple" }
  GW ==> LOOK["Lookup service<br/>one read · 800 ms deadline"]:::hot
  RELAY ==> PIR["PIR service<br/>encrypted shards in memory"]:::core
  LOOK ==> CACHE@{ icon: "tech:redis", label: "Redis<br/>hot records · 8 copies" }
  CACHE -.->|"miss"| STORE@{ icon: "tech:cassandra", label: "Cassandra<br/>serving records · per region" }
  GW --> INGEST["Intake<br/>call proof · token buckets"]:::service
  INGEST ==> BUS@{ icon: "tech:kafka", label: "Kafka-API log<br/>reports · call outcomes" }
  BUS ==> SCORE["Scorer<br/>stream plus daily batch"]:::core
  SCORE ==>|"new version"| STORE
  SCORE --> LISTS@{ icon: "sd:cdn", label: "CDN<br/>daily list · hourly deltas" }
  LISTS -.-> AND
  STORE -.->|"rebuild shards"| PIR
  class AND,IOS client
  class GW,RELAY,LISTS edge
  class CACHE cache
  class STORE store
  class BUS queue

%% title: From a report or a declined call to a new verdict in minutes
flowchart TD
  APP@{ icon: "sd:phone", label: "Phone<br/>report · decline · block · answer" }
  IN["Intake<br/>call-log proof · per-user caps"]:::service
  LOG@{ icon: "tech:kafka", label: "Kafka-API log<br/>partitioned by number" }
  WIN["Stream windows<br/>1 h and 24 h per number"]:::core
  SCORE["Scorer<br/>trust-weighted evidence · bands"]:::hot
  BQ@{ icon: "tech:bigquery", label: "BigQuery<br/>reporter trust · daily retraining" }
  OUT@{ icon: "sd:database", label: "Serving records<br/>new version per change" }
  APP ==> IN ==> LOG ==> WIN ==> SCORE
  LOG --> BQ
  BQ -.->|"weights, daily"| SCORE
  SCORE ==> OUT
  class APP client
  class LOG queue
  class BQ service
  class OUT store

%% title: Sunita's call on one bar of signal
sequenceDiagram
  autonumber
  participant P as Sunita's phone
  participant L as Device list
  participant S as Lookup service
  participant C as Redis
  P->>L: Number in the region list?
  L-->>P: No, it started calling this morning
  P->>S: Look up the E.164 number, deadline 800 ms
  S->>C: Serving record, random hot copy
  alt answer inside the deadline
    C-->>S: Likely fraud · 1,814 reports
    S-->>P: About 140 bytes
    P->>P: Red screen before the second ring
  else network too slow
    P->>P: Show Unknown number at 800 ms
    S-->>P: Late answer
    P->>P: Repaint while still ringing
  end

%% title: Rohit's iPhone asks without revealing who or which number
sequenceDiagram
  autonumber
  participant A as Truecaller app
  participant I as iPhone
  participant R as Apple's relay
  participant T as PIR service
  A->>T: Signed in, fetch single-use tokens
  Note over I: a call from an unknown number
  I->>I: Number maps to shard 3, bucket 11
  I->>R: Block query and identity query, one token each
  R->>T: Both, without the IP or device
  T->>T: Tokens unspent · encrypted dot product over shard 3
  T-->>R: Encrypted results
  R-->>I: Relayed back
  I->>I: Decrypt, block or show the name
  Note over T: learns only that a user queried shard 3

%% title: A report becomes evidence, or is dropped
sequenceDiagram
  autonumber
  participant P as Reporter's phone
  participant N as Intake
  participant G as Log
  participant W as Stream scorer
  participant D as Store and deltas
  P->>N: Report spam, with the call event it refers to
  alt call proof matches the device's outcome stream
    N->>G: Report event, keyed by number
    G->>W: Windows update · distinct reporters · trust weights
    W->>D: Band crossed · new record version
    D->>D: Overwrite cache copies · add to next hourly delta
  else no matching call, or over the daily cap
    N->>N: Drop before the log
    Note over N: a burst of these is a brigading signal
  end

%% title: Core entities
classDiagram
  class ServingRecord {
    +numberHash : 8 bytes of E.164
    +displayName : string
    +category : person · business · spam type
    +spamBand : NONE to LIKELY_FRAUD
    +reportCount : int
    +verified : bool
    +version : int
  }
  class NameCandidate {
    +name : string
    +source : owner · business · community
    +basis : collection basis
    +region : jurisdiction
    +collectedAt : date
  }
  class Report {
    +reporter : user id
    +callEvent : proof of the call
    +category : spam · fraud
    +label : free text
  }
  class Reporter {
    +trust : 0 to 1 · daily batch
    +dailyCap : int
  }
  class Listing {
    +state : UNKNOWN to UNLISTED
    +ownerSince : date
  }
  class SpamList {
    +region : telecom circle
    +version : int
    +keys : sorted 8-byte hashes
  }
  ServingRecord "1" --> "many" NameCandidate : best name from
  ServingRecord "1" --> "many" Report : scored from
  Reporter "1" --> "many" Report : files
  ServingRecord "1" --> "1" Listing : governed by
  SpamList "1" --> "many" ServingRecord : built from

%% title: A number's listing, from first call to unlisted
stateDiagram-v2
  [*] --> UNKNOWN: first seen in a call
  UNKNOWN --> COMMUNITY_NAMED: trusted suggestions agree
  UNKNOWN --> REGISTERED: owner signs up and verifies
  COMMUNITY_NAMED --> REGISTERED: owner signs up
  UNKNOWN --> SPAM_FLAGGED: score crosses a band
  COMMUNITY_NAMED --> SPAM_FLAGGED: score crosses a band
  SPAM_FLAGGED --> UNKNOWN: verdict cleared or disputed
  SPAM_FLAGGED --> SPAM_FLAGGED: unlist refused
  COMMUNITY_NAMED --> UNLISTED: owner unlists
  REGISTERED --> UNLISTED: owner deletes and unlists
  REGISTERED --> UNKNOWN: number recycled
  UNLISTED --> [*]
  class REGISTERED ok
  class UNLISTED ok
  class SPAM_FLAGGED bad
  class COMMUNITY_NAMED queue