Truecaller system design: how unsaved numbers get a name

An unsaved number calls, and the app shows a name. The interview question is how. The short version is that you don't look the name up at call time by asking anyone. You build the answer ahead of time and keep it in a store you can read by key.

This is the standard interview design for a caller ID app. It isn't Truecaller's own system.

Why not ask every phone

The obvious idea is to ask other phones who this number is. It fails fast. There are millions of phones, some are offline, and contacts are private. And the name has to show up in milliseconds, not after a round of questions.

So the answer has to exist before the call. That changes the problem from "find the name" to "collect names and keep the best one per number".

The pipeline

Phones that have given permission send number and name pairs, like "Sharmaji Plumber". They can also send spam reports. Here is the path, in order.

API server. It's the gatekeeper. It validates the pairs and the reports before anything else touches them.

Queue. A buffer between the server and the database. Think of a Mumbai local at rush hour, where the crowd moves through in a line. The database writes at its own speed instead of absorbing the whole rush.

Worker. A background program. For each number, the name that shows up most often wins. It also keeps the counts.

Key-value database. Basically a dictionary. The key is the number and the value is the name. When a call comes in, the app asks the API server, and the lookup goes straight from number to name.

Why you sometimes see a nickname

The name on screen isn't verified truth. It's a crowd vote. If more people saved a number as "Pappu", then "Pappu" is what shows up.

That's a direct result of the worker design. It counts saved names and picks the most common one, so whatever most people typed is what everyone sees.

The hot number problem

Now picture a spam number that gets a flood of reports. All of them land on one key, and that key becomes the hot spot in the database.

The fix sits in the worker. It counts reports over a short window, then makes a single write. Once the count crosses a limit, the number is treated as spam. One write per window replaces a write per report.

What to try

Next time you practise this question, say the flow out loud in order. Pairs come in, the server validates, the queue buffers, the worker votes, and the key-value store answers. Then be ready for the two follow-ups, why a nickname wins and how you'd protect a hot key. The reel asks it too. Would you use a queue, or write straight to the database?