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.
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.
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.
- 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.tsfile 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 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.
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.
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.
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:
- 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.
- 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.
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.
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.
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 409The 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:
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.
- 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.
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.
| Concern | How it is handled |
|---|---|
| Passwords | Hashed with scrypt. Accounts are stored under a hash of the email. |
| Sessions | A signed cookie holding the account and workspace, valid for 30 days, compared in constant time. |
| Access | Storage paths come from the session, so a user can only address their own workspace. |
| Plans | Limits on people, sources, forms and research are enforced on the server and checked on the client for friendly messages. |
| Billing | Stripe, with the webhook verified by its signature. |
| Abuse | Public endpoints have a per-IP sliding-window limiter plus an edge rule, and failed sign-ins are slowed down slightly. |
| Public endpoints | The 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.
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.
- 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.