Skip to content
Rajasekar M
Back to Home

Technical write-up

How Rolo works: from messy exports to one list of people

Rolo is a small CRM for people who sell to their own audience. This is a tour of how it works inside, drawn out step by step.

Rajasekar M · 16 October 2026 · about 12 minutes · 17 diagrams

The problem

If you sell to your own audience, the people you know are scattered. Some are LinkedIn connections. Some follow you on Instagram or X. Some are on a newsletter list, some booked a call, some wrote to you in Gmail. The same person is often in four of those places under four different identifiers.

Heavy CRMs expect you to type all of this in. Rolo takes the opposite route: start from the data you already own, and do the merging for you.

Many exports go into Rolo and one list of people comes outYOUR EXPORTSLinkedInInstagramX and TikTokGmail and OutlookNewslettersEvents and bookingsRolomergede-duplicatescoreONE LIST OF PEOPLEOne person per humannot one per platformWarmth scorewho to talk to firstPipeline and follow-upsnotes, tags, stages
Rolo reads 18 platforms plus any CSV, and produces one record per human.

It reads the official data exports from 18 platforms, plus any CSV. The result is one list with one record per human, a score for how warm each relationship is, and a simple CRM on top: inbox, pipeline, follow-ups, notes, lead-capture pages and export.

The decision that shaped everything

Early on I ruled out scraping and browser extensions. Platforms do not like them, they break often, and they ask the user for a lot of trust. Instead, every platform lets you download your own data. Rolo reads that file.

That one choice decided most of the architecture. If the user hands me a file, the natural place to read it is their own browser. The server never needs the export itself. It receives the compiled result: contacts and conversations after parsing, gzipped, and capped at 4 MB.

Two ways to get contact data into a toolTHE USUAL WAYSocial networkholds your dataScraper or extensionacts as youTheir serverstores everythingTHE ROLO WAYYou downloadyour own exportfrom each platformYour browser reads itparses, merges, gzips(up to 4 MB)Your workspacestores the compiledresult, not the file
Rolo reads the file you download. The server receives the compiled result, not your export.

There is a price for this, and it is worth being honest about it:

  • Parsing has to be fast and careful in the browser. Exports can be large. Zip files are streamed instead of loaded whole, and a multi-gigabyte mailbox is scanned for headers only.
  • The browser needs its own cache. The compiled dataset is kept in IndexedDB so the app opens instantly and works from local data.

The benefits are larger: no scraping risk, a clear privacy story, and a server that stays small and cheap to run.

The big picture

Rolo has three zones. The browser does the heavy work, a thin server enforces access, and storage holds each workspace.

High-level architecture of RoloBROWSERReact UIpeople, inbox, pipelineImport web workerdetect, parse, mergeClient storewarmth, follow-upsIndexedDB cacheper workspaceSERVER (VERCEL)proxy.tssession gateRoute handlers/api/state/api/datasetauth, billing, mailNightly croncompany researchreads and writesworkspacesSTORAGE AND SERVICESVercel Blobaccounts, dataset,CRM state, formsStripebilling, webhooksGmail APIsend, repliesWikidatacompany factsCompany websitesdescriptionsHTTPS
Three zones. The browser does the heavy parsing, a thin Next.js server enforces access, and Blob storage holds each workspace.
  • Browser. A React UI, a web worker for imports, a client store that computes scores and follow-ups, and an IndexedDB cache.
  • Server. A Next.js app on Vercel. A proxy.ts file gates pages by session. Route handlers do the real work and check the session again.
  • Storage and services. Vercel Blob holds accounts, the dataset, CRM state and lead-capture submissions. Stripe handles billing, Gmail handles sending and replies, and Wikidata and company websites feed research.

There is no database server. Each workspace is a small set of documents in Blob storage. For one seller that is plenty, and I come back to the limits at the end.

From a file to a person

When you drop a file, it goes through six steps. Each step does one thing.

The six steps of the import pipelineUnzipstream largearchivesDetectwhich platformis this?Parseone parser perplatformFragmentcommon ContactshapeMergeone personper humanScorewarmth0 to 100All of this runs in a web worker, off the main thread
Each step has one job. Merge is the hard one, so it gets its own section below.

The worker handles zips, nested zips, CSVs, vCards, chat exports and mailboxes. Large files are streamed. All of it runs off the main thread so the interface stays responsive during a big import.

Step 1: recognise the file

People upload files without telling Rolo where they came from. So the first job is detection. Each CSV is identified by its header names, and each rule returns a platform with a confidence score.

Detecting a LinkedIn export from its column headersFIRST ROW OF THE FILECSV headersFirst Name, Last NameURL, Email AddressCompany, PositionConnected OnHEADER RULESurl + connectedon + firstnameinviteeemail or inviteenameapiid + approvalstatusemail + utm or referral columnslinkedinconfidence 0.95other rules: calendly, luma, eventbrite, mailchimp, beehiiv, substack, kit
Simplified from the real rules. Each rule looks at header names and returns a platform with a confidence.

A LinkedIn connections file, for example, has url, connectedon and firstname columns together. That combination is specific enough to score 0.95. Weaker hints, like a file named after a newsletter tool, score lower.

Step 2: one shape for every platform

Each platform has its own parser, and each one converts a different format into the same Contact shape: names, emails, phones, handles, company, how you relate, and message counts.

Many parsers produce one Contact shapeONE PARSER PER PLATFORMLinkedIn CSVInstagram, X, TikTok JSONWhatsApp chat textMailbox (mbox)vCard and contact CSVsContactkey and nameemails and phoneshandles per platformcompany, positionrelationsmessage countsMergedoes not care whichplatform a contactcame from
Everything after parsing sees the same shape, so adding a platform means adding a parser and a detection rule.

This is the adapter pattern in plain use. Everything downstream, including merge and scoring, only knows about Contact. To support a new platform I add a parser and a detection rule. Nothing else changes.

Every import becomes a fragment: the contacts and conversations from one source. Importing the same source again replaces its fragment, so re-importing never creates duplicates.

Deciding who is who

This is the hardest part of the product. The same person shows up in several sources with different identifiers, and two different people can share a name. Merge has to decide which records belong together.

Joining records that share an identifier, and refusing one unsafe joinTHE SAME PERSON IN THREE SOURCESLinkedIna.rao@example.comGmaila.rao@example.com+91 98xxxMailing list+91 98xxxsame emailsame phoneOne personstable id, e.g. the LinkedIn slugGUARD RAILLinkedIn profile 1shared@example.comLinkedIn profile 2shared@example.comnot mergedsame email, two different profiles
Shared identifiers chain together. Two different profiles on the same platform are never joined, even with a shared email.

Records that share an identifier are grouped. Because sharing chains together, a LinkedIn record can join a Gmail record by email, and that Gmail record can join a mailing-list entry by phone. All three become one person.

The rules run from the most certain to the least:

The order of identity rules, from most to least certainmost certain1. Exact identifiersemail, platform handle (including handles inside profile URLs), phone2. Guard railnever join two different handles on the same platform3. Careful name matchsame full name and same company, or a name that is unique in both sources; small groups only4. Your overridessplit a contact out, or link two people by handleast certain
Rules run from the most certain to the least. A manual override always has the last word.
  • Exact identifiers first. Normalised email, platform handle (including handles inside profile URLs) and phone.
  • A guard rail. Two different profiles on the same platform are never joined, even if they share an email. This catches shared inboxes and assistants.
  • Names are a last resort. Same full name in different sources counts only if the company matches, or the name is unique in both, and only in groups under 200 records. Common names are ambiguous, so the rule stays strict.
  • You have the last word. You can split a contact out or link two people by hand.

Person ids are stable across re-imports. A LinkedIn slug is used when there is one, then email, then platform handle, then phone, then name. Stable ids are what let your notes survive a re-import.

Keeping your work safe

Imported data changes whenever you import again. What you type should not. So Rolo keeps them in separate layers.

Imported data and your edits live in separate layersFragmentsone per importnever editedmergeDatasetderived,can be rebuiltCRM statenotes, tags, stages,edits you madeWhat you seeimported data withyour edits on top
Re-importing rebuilds the dataset but never touches what you typed. Your edits win wherever they overlap.
  • Fragments are inputs. They are never edited after import.
  • The dataset is derived from fragments by the merge, so it can be rebuilt at any time.
  • CRM state holds only what you added: notes, tags, stages, edited details. It is keyed by the stable person id.

What you see is the dataset with your edits on top. Where they overlap, your edit wins. That rule is simple on purpose, because it means a re-import can never destroy your work.

Who is warm

A list of people is not enough. The useful question is who to talk to first. Rolo gives each person a warmth score from 0 to 100, built from a few signals, with two-way conversation counting most.

Maximum points each signal can add to the warmth scoreConversation50Recency30Endorsements and recommendations20Follow and tenure8025 points50
Audience signals from other sources (subscriptions, bookings, event check-ins) add more on top. The total is capped at 100.

The conversation part rewards replies in both directions, with diminishing returns so one long thread does not dominate:

conversation = min(45, 10 * log2(1 + sent) + 8 * log2(1 + received))
             + (both directions ? 5 : 0)
recency      = 30 * exp(-daysSinceLastMessage / 240)
score        = round(min(100, conversation + recency + endorsements
                             + follows + audienceSignals))

Recency fades smoothly instead of falling off a cliff. A contact you spoke to a month ago keeps most of the points, and a year of silence leaves only a few.

Recency points decay with days since the last message010203009018036054072030 days: 26.590 days: 20.6240 days: 11.0480 days: 4.1days since you last spokerecency points
Drawn from the actual formula, 30 × e^(−days ÷ 240). A contact you spoke to a month ago keeps most of the points. A year of silence leaves a few.

The score is built from named parts, so the interface can show why someone is warm instead of only showing a number.

Saving without losing work

You might use Rolo on a phone and a laptop, and a billing webhook can touch your account at any moment. With documents in Blob storage and no database transactions, two writers can easily overwrite each other.

Rolo uses optimistic concurrency. Every stored document has a version (an ETag). A write says: save this, but only if the version is still the one I read. If someone else saved first, the write is rejected, and the writer reads the new version, merges its own change on top, and tries again.

Two devices save at the same time and nothing is lostPhoneLaptopBlob state1. read: version A2. read: version A3. write if still Asaved, now version B4. write if still Arejected: it is B now5. read B, merge, write if Bsaved, now version C
The second writer is told its copy is stale, reads the newer version, merges its change on top, and writes again.
for (let attempt = 0; attempt < 4; attempt++) {
  const { state, etag } = await loadState(path);   // current state and its version
  const merged = mergeState(state, changes);        // apply only what changed
  try {
    await put(path, JSON.stringify(merged), { ifMatch: etag });
    return { etag };
  } catch (err) {
    if (!isConflict(err)) throw err;                // lost the race: read again
  }
}
return null;                                        // the route answers 409

The client also sends only the records that changed, which keeps requests small and reduces the chance of conflicts. If four attempts are not enough, the server answers 409 and the client retries shortly.

The same discipline applies to every request. Each write passes a fixed set of gates, and each gate has its own status code:

Every write passes the same gates, and each gate has its own status codeRequestPOST/api/stateproxy.tsvalid sessioncookie?401 or loginRoute handlerchecks sessionagain401Validateis the bodywell formed?400Plan limitpeople andsource limits402SaveETagcheck409When every gate passes, the server answers 200 with the new version
Pages and APIs are checked twice on purpose. A missed check in one place cannot expose data.

The status codes carry meaning. 400 means the body is malformed, 401 means not signed in, 402 means the plan limit is reached, and 409 means a conflict. The client can react to each without parsing error text.

Research that never guesses

Company details are useful when you decide who to reach out to. A nightly job fills in website, industry, headcount, headquarters, founding year and a short description from public sources.

The nightly company research run1. Cron firesnightly, with a secretthe server checks2. Pick companies3+ people you know,or any conversation,not done in 180 days3. Ask Wikidata4 companies at a timematch needs companyfacts, not just a name4. Try the websiteonly if a descriptionor site is missing5. Fill empty fieldsor fields researchfilled before; neverones you edited6. SaveETag check, retryon conflict
A run stops at a deadline, works through about 200 companies a night, and never overwrites what you typed.
  • Who gets researched. Companies where you know at least three people or have talked to someone, largest first, skipping any done in the last 180 days. About 200 a night.
  • How it stays polite. Four requests at a time, a descriptive User-Agent with contact details, and a deadline so a run stops cleanly.
  • Source first. Wikidata is tried first and must show company facts, not just a matching name. The company website fills gaps.

The rule I care most about is that research never guesses. Every value carries a link to its source, and every company ends in one of four outcomes.

How a company name becomes one of four outcomesCompanynamePlaceholder?Self-employed…yesskippednoWikidata matchwith company facts?yesfound (high)noWebsitenames it?one sitefoundmediumambiguousyou choosenothingnone
Skipped, ambiguous and none are real results. Saying nothing is better than saying something wrong.

Research only fills fields that are empty or that research filled earlier. The moment you edit a field, it is yours, and later runs leave it alone.

Accounts, plans and safety

It is a real multi-user product, so the basics matter.

ConcernHow it is handled
PasswordsHashed with scrypt. Accounts are stored under a hash of the email.
SessionsA signed cookie holding the account and workspace, valid for 30 days, compared in constant time.
AccessStorage paths come from the session, so a user can only address their own workspace.
PlansLimits on people, sources, forms and research are enforced on the server and checked on the client for friendly messages.
BillingStripe, with the webhook verified by its signature.
AbusePublic endpoints have a per-IP sliding-window limiter plus an edge rule, and failed sign-ins are slowed down slightly.
Public endpointsThe cron job, Stripe webhook, lead-capture and waitlist routes each authenticate themselves in their own way.

Pages and APIs are checked twice on purpose. The proxy gates pages, and each route handler checks the session again. If one check is ever missed, the other still holds.

Where the code lives

Each responsibility has its own home, which keeps changes small.

Where each responsibility lives in the codebaseBrowserimport.worker.tsstore.tsmodel.tsidb.tsresearch.tsSourcesdetect.tsparsers/*parse.tsmerge.tsbundle.tsServer logicstate-store.tsauth.tsaccounts.tsplans.tsstripe.tsRoutesapi/stateapi/datasetapi/authapi/billing/*api/cron/research
Parsing, merging, scoring, persistence, auth and billing sit in separate modules.

What I would change at scale

Rolo today is built for one seller with a few thousand contacts. That is why per-workspace documents work. If it grew into a product for teams, these are the limits I would hit first, and how I would fix them.

What changes if Rolo grows from one seller to many teamsTODAYAT SCALEJSON per workspace in BlobdataPostgres with a tenant id on every tableNightly cron, about 200 companiesbackground workQueue, workers and a dead-letter queueIn-memory limiter plus an edge rulerate limitsShared counters in RedisETag retry on whole documentsconflictsRow versions and transactions
Each change fixes a limit that does not matter at today's size but would at 100 times the load.
  • Data. Whole-document reads and writes do not allow ad hoc queries or multi-record transactions. Postgres with a tenant id on every table would, and it would make isolation between customers enforceable in the database.
  • Background work. A nightly cron is simple but has no retries per item. A queue with workers, backoff and a dead-letter queue would handle failures properly and scale with load.
  • Rate limits. The in-memory limiter is best-effort per instance. Shared counters in Redis make the limit real across instances.
  • Observability. Metrics for import time, queue age, failure rate and conflict retries would show problems before users do.

If you want to see the result, Rolo is on its product page. If you are building something similar, or want an integration-heavy product designed carefully, I am happy to talk.