source: .forge/discovery/research/crm-basics.md · generated — edit the markdown, not this file

What a CRM Is, and What Is Inside One

Orientation note, 2026-08-21. A ground-up explainer for anyone joining the project without CRM background, so that the PRD’s vocabulary — pipeline, stage, deal, activity, lead — reads as domain language rather than jargon. Point-in-time and generic by design: where it touches Empire Teas, project-prd.md and design/architecture.md win.

ℹ The whole thing in six sentences

A CRM is a shared database of everyone your company sells to, plus a record of every interaction with them, plus a board that tracks each in-progress sale from first contact to signature. Its central idea is that the customer relationship belongs to the company, not to whichever salesperson happens to be handling it.

Everything else — email sync, quote generation, reminders, dashboards, automation, AI — exists to make that shared record cheap to keep accurate, because a CRM nobody updates is worse than no CRM at all. The single most important screen is the pipeline: a column per stage of the sales process, a card per live deal, dragged left to right as things progress.

Most of the money in a CRM comes from two things: nothing falls through the cracks, and a manager can see what is going to happen next month before it happens. Most CRM projects that fail, fail on adoption and data quality — not on features.

Part 1 — Foundations

What the thing is, what breaks without it, and who is standing around it.

01 · What a CRM actually is

CRM stands for Customer Relationship Management. Annoyingly, the three letters are used for two different things, and people slide between them mid-sentence:

CRM the practice

The business discipline of deliberately managing relationships with customers and prospects — who you talk to, how often, what you promised, what they need next.

— rarely what people mean

CRM the software

The system that stores all of that and helps you act on it. When someone says “put it in the CRM” or “we’re switching CRMs”, this is what they mean.

— what this document is about

Here is the most useful one-line definition:

Definition

A CRM is a shared, structured memory of every company and person you sell to, every conversation you have had with them, and every sale currently in progress — arranged so that anyone on the team can pick up where anyone else left off.

Three ideas do all the work

Almost every feature in every CRM on the market is a consequence of one of these three ideas.

1 · One record per customer

Every email, call, meeting, quote and note attaches to the same customer record. No hunting across five tools.

2 · A sale is a thing with a state

An in-progress sale is not a vague hope — it is an object with a value, an owner, a stage, and an expected close date.

3 · The relationship is the company’s

If a salesperson resigns tomorrow, the knowledge stays. That is the actual business case, and it is why managers care.

In plain terms: a CRM is a very opinionated address book. The opinion is that a contact is not interesting on its own — what is interesting is the deal attached to it and the next thing you owe that person .

What a CRM is not

Not this Because That job belongs to
An accounting system A CRM tracks the promise of revenue; it usually does not issue the invoice or hold the ledger. Accounting software or an ERP
A project manager It tracks winning the work, not delivering it afterwards. A project or task tool
A customer support desk Support is about tickets from existing customers; a sales CRM is about deals with future ones. The two overlap and are often bought together, but they are different products. A help desk / ticketing system
An email marketing blaster Sending 40,000 newsletters is a different problem from one salesperson writing to one buyer. Marketing automation
A spreadsheet with nicer colours The relationships between records — this person works at this company on this deal — are the point, and a spreadsheet cannot hold them. —

02 · Life without one — the problem being solved

It helps enormously to understand the pain first, because every feature later in this document is an answer to a specific complaint.

Picture a small exporter with four salespeople. There is no CRM. Where does customer information live?

Five scattered information sources versus a single shared customer record WITHOUT A CRM Someone's inbox the last 9 months of email A spreadsheet on one laptop, v7-final-2 Sent quotes a folder of PDFs Chat threads phone-only, unsearchable Somebody's head "I think they wanted…" Nobody can answer "what is happening with this customer?" without asking three people and waiting a day. WITH A CRM Emails Calls & meetings Quotes Notes Next steps One customer record everything in date order, visible to the whole team
Diagram 1 — the core move a CRM makes: five scattered sources collapse into one shared record.

The five classic failures

Things fall through the cracks

A buyer says “come back to me in March”. March arrives; nobody remembers. That deal is silently lost and nobody even records that it existed.

Knowledge walks out the door

A salesperson leaves. Their inbox is deactivated. Nine months of context on twenty accounts vanishes in an afternoon.

Nobody can forecast

“How much will we close this quarter?” is answered by four people guessing, in four different formats, a week late.

Customers get double-handled

Two reps contact the same buyer with different prices. The buyer notices. It is embarrassing and it costs margin.

No learning happens

You cannot answer “why do we lose?” because losses were never written down in a form that can be counted.

Onboarding takes months

A new hire has no way to learn the accounts except by asking colleagues, one question at a time.

⚠ Worth internalising

Notice that none of those six problems are solved by a prettier contact list. They are solved by completeness and shared access. This is why “will people actually use it?” beats “does it have feature X?” in every real CRM decision.

03 · Who uses it — the people around the system

A CRM is not a single-user tool. Different roles want almost opposite things from it, and much of the design tension in a CRM comes from that clash.

Role What they want What they resent
Sales rep To be told what to do today, to write as little as possible, and to find the last conversation in two clicks. Data entry that benefits their manager and not them. This is the single biggest source of CRM failure.
Sales manager An honest forecast, a view of who is busy and who is stuck, and early warning on deals going quiet. Reps who update the CRM the night before the review meeting, making the data fiction.
Specialist / technical staff Their own queue of work requested by sales — samples to prepare, specifications to check, designs to produce. Being interrupted over chat with requests that are not written down anywhere.
Pricing / commercial Control over what price can be offered, and a record of who approved anything below the floor. Reps quoting numbers they were never authorised to quote.
Administrator To add users, adjust the pipeline stages and fields, and fix bad data without calling a developer. Every small change being a support ticket.
Executive / owner Three numbers on one screen: what is in the pipeline, what closed, what is at risk. Being handed a spreadsheet export instead of an answer.

The design tension in one line

Managers want more fields; reps want fewer. Every field you add is a small tax on every deal, paid by the person with the least incentive to pay it. Good CRMs resolve this by capturing data as a by-product of work the rep already does — syncing the email they already sent, rather than asking them to log that they sent it.

Part 2 — The nouns — how a CRM models the world

Before any feature makes sense you need the vocabulary. Five objects carry almost everything; the rest hang off them.

04 · The five core objects

Learn these five words and roughly 80% of any CRM screen becomes readable. Vendors rename them — that is mostly marketing — so both common names are given.

1 · Organisation also: Account, Company

A company you sell to. Acme Foods Ltd, Rotterdam. Holds the things that are true of the business rather than a person: address, country, industry, website, payment terms, who owns the relationship.

  • Example fields — Name · country · industry · annual volume · owner · status (prospect / customer / dormant)
  • Why separate — People change jobs. The company keeps buying. Attaching history to the company survives staff turnover on both sides.

2 · Person also: Contact, Lead contact

A human being. Marta Koval, Procurement Manager at Acme Foods. Email, phone, job title, language, timezone, and — crucially — which organisation they belong to.

  • Example fields — Name · title · email · phone · organisation · preferred channel · marketing consent
  • Watch out — In serious B2B, one person can be involved with two organisations (a consultant, an agent, someone mid-job-change). Assuming one person belongs to exactly one company is a common early modelling mistake.

3 · Lead also: Prospect, Inquiry

An unqualified scrap of interest that has arrived but has not yet been judged worth pursuing. A business card from a trade show. A website form. A cold email that said “do you export to Poland?”.

  • The point of it — To keep junk out of your real database. Leads are a holding pen. Once a lead is judged real, it is converted — it becomes an organisation + a person + a deal, and the lead itself is archived.
  • Common confusion — Some CRMs (notably the simpler ones) skip leads entirely and let you create a deal immediately. Neither approach is wrong; the lead stage is a filter, and filters only pay for themselves when volume is high.

4 · Deal also: Opportunity, Pipeline item

One potential sale, with money attached. “Acme Foods — 12 tonnes black tea — €48,000 — expected close 30 November.” This is the object the whole system revolves around.

  • Essential fields — Title · value · currency · linked organisation · linked person · stage · owner · expected close date · probability · status (open / won / lost)
  • Why it exists separately — A customer is not a sale. The same organisation may have three deals running at once and forty closed behind it. Sales performance is measured in deals, not contacts.

5 · Activity also: Interaction, Engagement, Task

Something that happened, or something that must happen. A call made, an email sent, a meeting held, a sample shipped, a follow-up due next Tuesday.

  • Two tenses, one object — Past activities are the history. Future activities are the to-do list. Most CRMs use one underlying record with a date and a done flag, which is why “log a call” and “schedule a call” look so similar.
  • The golden rule — Every open deal should have exactly one next activity scheduled. A deal with no next step is a deal quietly dying. Several CRMs make this their headline discipline.

Sentence that ties them together: a lead becomes a person at an organisation , which gives you a deal , which you push forward with activities .

05 · How the objects connect

The relationships matter more than the fields. This is the shape almost every CRM has underneath, whatever the screens look like.

Entity relationships between lead, organisation, person, deal, activity, quote and product Lead unqualified interest Organisation the company you sell to Person a human contact Deal one potential sale, with a value Activity call · email · meeting · task Quote a priced offer Product / price list what you sell, at what price converts into 1 → many (its people) 1 → many (its deals) many ↔ many (who is involved in this deal) 1 → many (its history) 1 → many line items also attaches to
Diagram 2 — the standard CRM object graph. Solid lines are strict ownership; dashed lines are looser associations.

Reading the cardinalities

Relationship Shape Why it is that shape
Organisation → Person one to many A company has several staff you deal with: the buyer, the quality manager, the finance clerk.
Organisation → Deal one to many The same customer can have this season’s order in negotiation while last season’s sits closed.
Person ↔ Deal many to many A deal often involves several people on the buyer side, and one person appears across several deals. Simple CRMs cheat and store a single “primary contact”; that cheat hurts in complex B2B sales.
Deal → Activity one to many The full conversation history of that sale, in date order. This list is the deal, really.
Deal → Quote one to many You revise offers. Quote v1, v2, v3 — all kept, because “what did we offer them in March?” is a real question.
Lead → everything one-time conversion A lead is a temporary object. On conversion it spawns the real records and stops being edited.

06 · The supporting cast

Beyond the core five, every mature CRM carries roughly this set. You do not need all of them on day one, but you will need most of them eventually.

Note

Free text attached to any record. The dumping ground for everything the structured fields cannot hold. Cheap to add, hard to report on — that trade-off is the whole story of notes.

File / attachment

Specification sheets, signed contracts, photographs, certificates. Attached to a deal or an organisation. Needs virus scanning and storage limits in practice.

Email message

A copy of a real email, pulled in from the mail server and attached to the right record automatically by matching the sender’s address. See §17.

Task / to-do

An activity in the future with an owner and a due date. Overdue tasks are the single most useful list a salesperson has.

Product / catalogue item

Something you sell, with a code, a unit, and one or more prices. Deals reference products so that value is calculated rather than typed.

Price list

The same product at different prices by customer tier, currency, region or date. Deceptively hard — see §32 on effective dating.

Quote / proposal

A priced document sent to the customer, generated from the deal’s products, usually as a branded PDF. Versioned.

Pipeline & stage

The stage list itself is data, not code — administrators rename and reorder stages without a developer. See §08.

User & team

The people inside your company who log in. Distinct from contacts, who are outside it. Beginners conflate these constantly.

Audit / change log

Who changed what, when, from what to what. Invisible until the first argument about a price change, then priceless.

07 · Custom fields — the escape hatch

No two businesses need the same fields. A tea exporter needs grade and garden mark; a software firm needs seat count; a recruiter needs notice period. A CRM vendor cannot ship all of them, so every CRM offers custom fields: an administrator adds a field through a settings screen and it appears on the form.

Field type Use it for Beginner trap
Text Anything short and free-form Using text where a dropdown belongs. “Poland”, “poland”, “PL” and “Polska” are four different values and your report will show four countries.
Dropdown (single select) A fixed, known list — country, grade, lost reason Letting the list grow to 90 options nobody maintains.
Multi-select Tags, certifications held, markets served Hard to query and hard to report; use sparingly.
Number / currency Volumes, values, percentages Forgetting the currency. A number without a unit is not data.
Date Expected shipment, contract expiry Timezones. A “date” the whole world agrees on is harder than it looks.
Relation / lookup Pointing at another record The most powerful and most under-used type.
Checkbox Genuinely binary facts Booleans that later need a third state (“unknown”).

⚠ The custom-field trap

Custom fields feel free and are not. Every field is asked of a rep on every record, forever. A widespread pattern: a company adds 40 custom fields in year one, 30 of them are blank on 90% of records by year two, and the forms are now so long that people avoid the system. Rule of thumb: if you cannot name the report a field will appear in, do not create the field.

Two ways to build it

If you are building a CRM rather than buying one, this is one of the first real architecture forks:

Schema-less custom fields

Store admin-defined fields in one flexible blob column per record. Adding a field is a settings change, no database migration, no deployment.

Good for: genuinely unpredictable, per-customer extras.
Costs: weaker validation, clumsier queries, no foreign keys.

Real typed columns

Fields your domain genuinely always has get proper columns with proper types and constraints.

Good for: anything you sort, filter, price or report on constantly.
Costs: a migration and a release for each change.

Serious systems use both, deliberately: typed columns for the domain’s real vocabulary, the flexible blob for the long tail. Deciding which is which is a design conversation, not a technical one.

Part 3 — The verbs — the pipeline

The objects sit still. The pipeline is what moves. This part is the beating heart of the whole subject.

08 · The pipeline and its stages

A pipeline is your sales process, written down as an ordered list of stages. Every open deal sits in exactly one stage. Selling is the act of moving deals rightwards.

A kanban pipeline board with five stages and deal cards Qualified Meeting held Proposal sent Negotiation Contract 6 deals · $400k 4 deals · $300k 3 deals · $200k 2 deals · $120k 1 deal · $60k Acme Foods$90k · 12 days idle Nordbryg AS$70k · 2 days idle Chai Bros$55k · 4 days idle Kowalski Sp.$120k · 1 day idle Green Leaf Co$80k · 9 days idle Marlow & Sons$100k · 3 days idle Bergen Import$60k · 21 days idle Acme Foods (2)$75k · 1 day idle Tulip Traders$60k · today deals move this way — every move is a dated event the system remembers Won closed, revenue Lost closed, with a reason Any stage can also exit straight to Lost — deals die at every point, not just at the end.
Diagram 3 — the pipeline board, the screen a salesperson lives in. Cards show value and days-since-last-activity.

What makes a good stage

The single most common mistake is naming stages after what you are doing. Good stages are named after a verifiable change in the buyer’s state.

Weak stage Stronger stage Why
“Following up” “Meeting scheduled” “Following up” describes your intention. A scheduled meeting is a fact you can check.
“Interested” “Requirements confirmed” Interest is a feeling. Confirmed requirements are a document.
“Working on quote” “Quote sent” Anchor the stage on the moment the buyer receives something.
“Almost there” “Verbal agreement, contract issued” Optimism is not a stage.

How many stages?

Five to seven. Fewer than four and the board tells you nothing; more than eight and reps stop moving cards accurately because the distinctions blur.

More than one pipeline

Real companies sell in more than one way. A “new business” pipeline and a “repeat order” pipeline have genuinely different stages. Most CRMs support multiple pipelines; use them rather than bending one to fit both.

ℹ A subtlety worth knowing early

A stage has two identities: a display name an administrator can rename freely (“Proposal sent” → “Offer issued”), and a stable internal meaning the software keys its logic on. If automation is written against the display name, renaming a stage silently breaks it. Keeping the two separate is a well-known piece of CRM engineering hygiene.

09 · The lead lifecycle, end to end

Now put the objects and the pipeline together. This is the journey from “somebody we have never heard of” to “customer”.

Lead lifecycle flow from source through qualification to won or lost website form · trade show · referral · cold outreach Source where it came from Lead captured, unjudged Qualify worth our time? Convert org + person + deal Pipeline stage by stage Won Lost Disqualified archived, with a reason Nurture / paused "come back in March"
Diagram 4 — the full lifecycle. Note the two side exits: most records leave the flow sideways, not at the end.

The stages of the journey, in words

  1. Capture. A lead arrives from a source — a website form, a scanned business card, a forwarded email, a list you bought. The source is recorded here and never overwritten, because “which channel actually produces customers?” is one of the highest-value questions a business can answer.
  2. Assign. The lead is routed to a person. Round-robin, by territory, by product, or by whoever is on duty. Unassigned leads rot; that is why assignment is usually automated.
  3. Respond. Speed matters more than polish. Response time is one of the few sales metrics with a clean, well-established relationship to outcomes.
  4. Qualify. Decide whether this is real. See §10. Two outcomes: convert, or disqualify with a reason.
  5. Convert. The lead becomes an organisation, a person, and a deal. The lead record is archived, not deleted — you want to trace any customer back to where they came from.
  6. Progress. The deal moves through stages, accumulating activities, quotes and files.
  7. Close. Won or lost. Both are closures and both must be recorded; see §11.
  8. Retain. A won deal usually spawns the next one. In repeat-order businesses this loop is the whole business, and the CRM’s job shifts from hunting to not losing.

10 · Qualification — deciding who is worth your time

Salespeople have finite hours. Qualification is the deliberate act of deciding which prospects get them. A CRM supports this by making the criteria explicit fields rather than a private judgement.

The two frameworks you will hear named:

BANT — the simple one

  • Budget — Can they afford it?
  • Authority — Is this person able to decide, or will they need someone else?
  • Need — Do they have a real problem we solve?
  • Timing — Are they buying this quarter or “sometime”?

good default Four dropdowns on the lead form and you have a usable score.

MEDDIC — the heavyweight one

Metrics, Economic buyer, Decision criteria, Decision process, Identify pain, Champion. Used for large, slow, multi-stakeholder deals where losing one costs a quarter.

heavy Overkill for transactional sales; the effort of filling it in must be smaller than the deal it protects.

Lead scoring

Rather than a yes/no judgement, many CRMs compute a score — a number that ranks leads so reps work the best ones first. Points come from two sources:

Signal type Examples Meaning
Fit (who they are) Right country, right size, right industry, buys the volumes we handle Would they be a good customer if they bought?
Intent (what they did) Opened three emails, requested a sample, asked for a price, visited the pricing page twice How likely are they to buy soon?

⚠ Honest caveat

Lead scores are frequently arbitrary — someone picks “+10 for opening an email” out of the air and the number is then treated as fact. A score is only worth having if you periodically check it against what actually closed. Otherwise it is astrology with arithmetic.

11 · Won, lost, and why lost reasons are gold

Every deal must end. A CRM that lets deals sit open forever is lying to you — the pipeline inflates, the forecast becomes meaningless, and the board looks busy while nothing moves.

Won

The customer committed. Record the final value (usually different from the initial estimate) and the close date. This is the number the business is measured on.

Lost

They said no, or went silent long enough to count as no. Record a lost reason from a short fixed list, plus a free-text note.

Why the lost-reason dropdown is the most valuable field in the system

Because it converts a year of individual disappointments into a countable pattern. Suppose the year’s losses break down like this:

Price too high ......... 41 deals · $1.9m
    Chose a competitor ..... 22 deals · $0.8m
    No budget this year .... 18 deals · $0.6m
    We were too slow ....... 14 deals · $0.5m
    Cannot meet the spec .... 9 deals · $0.4m
    → "too slow" is 14 deals of pure self-inflicted loss, and it is the only one you can fix this month without changing your price or your product.

You cannot produce that table unless the reason was captured as a dropdown. Free text will not aggregate: “price”, “too expensive”, “cost”, “budget — price” and “they said we were dear” are five different strings.

Practical detail

Keep the list to 5–8 options and make the field mandatory when marking a deal lost. Add “Other” plus a required note, then review what people write in “Other” every few months — that is how the list evolves honestly.

The third ending: rotten

Some deals never get a decision; the buyer simply stops replying. Good practice is a rot rule: any deal with no activity for N days is flagged, and after a further period is auto-closed as lost with reason “went quiet”. Harsh, but a pipeline of zombies makes every forecast wrong.

12 · Forecasting — turning a pipeline into a number

The manager’s question is: “how much will we actually close?” The pipeline holds the raw material for an answer.

Method 1 — weighted pipeline

Assign each stage a probability, multiply every deal’s value by its stage probability, and add it all up.

Weighted pipeline forecast by stage STAGE PIPELINE VALUE WIN % WEIGHTED Qualified 10% $40k Meeting held 25% $75k Proposal sent 50% $100k Negotiation 75% $90k Contract 90% $54k Total $1,080,000 in the pipeline → $359,000 forecast Pale bar = total value in that stage · gold bar = the weighted portion that actually enters the forecast
Diagram 5 — weighted pipeline. A million dollars "in the pipeline" is a third of a million in expectation.
$400k × 10% = $40k
    $300k × 25% = $75k
    $200k × 50% = $100k
    $120k × 75% = $90k
      $60k × 90% = $54k
    ─────────────────────
    Pipeline $1,080k → forecast $359k

Method 2 — commit / best-case / pipeline

Rather than arithmetic, the rep classifies each deal by hand into three buckets. Managers usually trust this more than the weighted maths, because it forces a human judgement about this specific deal.

Bucket Means Manager treats it as
Commit “I am putting my name on this closing.” Bankable. Chase hard if it slips.
Best case “It could land if things go well.” Upside. Not in the plan.
Pipeline “Real, but not this period.” Next period’s raw material.

Pipeline coverage — the sanity check

A rule of thumb that catches trouble a month early:

coverage = total open pipeline ÷ the target for the period
    target $400k · pipeline $1,080k → coverage 2.7×
    Typical healthy range is 3× to 4× — so this team is thin and needs
    new opportunities now, not better closing later.

⚠ The honest limitation

All of this is only as good as the stage data. If reps park deals in “Negotiation” because it looks better in the review meeting, the forecast is confidently wrong. Forecast quality is a data-discipline problem wearing a mathematics costume.

Part 4 — What is in the box — the functional domains

“Domain” here means a coherent area of functionality — a chunk of the product that hangs together and could almost be its own small application. A tour of the twelve.

13 · The domain map

Map of the twelve functional domains inside a CRM THE CRM APPLICATION Contacts & accounts who we sell to Deals & pipeline what we are selling Activities & calendar what happens next Email & comms the conversation Quotes & documents the priced offer Automation rules, alerts, reminders Reports & dashboards what is going on Search & filters finding anything Users & permissions who may see what Data management import, duplicates, quality Admin & configuration stages, fields, teams AI assistance draft, extract, summarise Integrations mailbox · calendar · website forms · accounting / ERP · e-signature · telephony · the public API One shared database every domain above reads and writes the same records — that shared store is what makes it a CRM rather than twelve tools
Diagram 6 — the functional map. Sections 14 to 24 walk the boxes.

14 · Contact & account management

The address book, done properly. Its real job is not storage but retrieval and completeness.

What it must do

  • A single page per customer showing identity, the people in it, open deals, and a reverse-chronological feed of everything that has ever happened. This “record page” is the most-visited screen in any CRM.
  • Ownership — exactly one named person accountable for the relationship, so nothing is orphaned and nobody is double-handled.
  • Hierarchies — parent and subsidiary companies, or head office and branch. Real customers are not flat.
  • Segmentation — filter and save lists (“all dormant customers in Northern Europe who bought last year”) that update themselves as data changes.
  • Merge — because duplicates will happen, and merging two records without losing either one’s history is a surprisingly deep feature.

The test of a good implementation: a rep who has never met this customer should be able to open the record and be ready for a phone call in ninety seconds.

15 · Deal & pipeline management

Covered conceptually in §08; here is what it means as software.

Two views of the same data

Board view — columns of cards, drag to move stage. Great for working the day.
List view — sortable, filterable table. Great for bulk work and analysis. Every CRM offers both, and reps split fairly evenly on which they prefer.

Stage-entry requirements

Optionally block a deal from entering a stage until certain conditions hold — no “Proposal sent” without an attached quote. Powerful and easy to overdo; each gate is friction a rep must overcome.

Rotting and idle warnings

Cards visually flag when nothing has happened for N days. This one small feature reliably changes behaviour more than most dashboards do.

History of stage movement

Every stage change is stored with its timestamp. That log is what lets you compute how long deals sit in each stage, and where they die — the most actionable analysis in the whole system.

16 · Activities, tasks and the calendar

The tense-shifting object from §04, in practice.

  • Types — call, email, meeting, task, plus whatever your business does (a sample shipment, a factory visit, a document review). Type is a dropdown, and it is worth curating.
  • Two-way calendar sync — a meeting booked in the CRM appears in the rep’s real calendar, and a meeting booked in the calendar with a known contact appears on the CRM record. Getting this right, including cancellations and reschedules, is much harder than it sounds.
  • The “today” screen — overdue, then due today, then upcoming. For many reps this is the only screen they need before lunch.
  • Activity-based selling — the discipline that a deal without a scheduled next activity is incomplete. Some CRMs nag until you schedule one.

ℹ Why this domain earns its keep

Deals are outcomes and outcomes lag. Activities are inputs and they are visible today. If a rep’s calls drop this week, the revenue miss is eight weeks away and still preventable. Activity tracking is the earliest early-warning system a sales manager has.

17 · Communication — email and templates

The most-used and most-underestimated domain. If email does not work well, reps live in their mail client and the CRM starves.

Email sync — the two directions

Inbound capture

The CRM connects to the mail server, reads the rep’s mailbox, and matches each message’s sender or recipient to a known contact. Matched messages appear on the customer’s timeline automatically — the rep does nothing. That “does nothing” is the whole design goal.

Outbound send

The rep writes from inside the CRM. The message goes out through their real mail account so the customer sees a normal email from a normal person, and the copy lands on the record automatically.

⚠ The privacy question you must answer up front

If you sync a whole mailbox, personal mail comes with it. Standard answers: sync only messages matching known contacts; let the user mark threads private; or sync only messages the user explicitly links. Decide this before you build it, because retrofitting it means deleting data you should not have collected.

The rest of the domain

Templates

Reusable message bodies with merge fields — {{first_name}}, {{deal_value}}. Saves time and keeps wording consistent.

Sequences

A scheduled series of follow-ups that stops automatically when the person replies. Handy; easy to abuse into spam.

Shared inbox

A team address such as sales@ where anyone can pick up and everyone can see the reply.

Open / click tracking

Knowing a proposal was opened four times. Useful signal, and increasingly unreliable as mail clients pre-fetch images.

CC / BCC capture

A special address you copy on any email to file it against the right record without full mailbox sync.

Other channels

Phone-call logging and messaging apps. Valuable where customers actually live — which in much of the world is a messaging app, not email.

18 · Quotes, documents and approvals

The point where a conversation becomes a commitment, and therefore the point where controls matter.

  1. Line items. Add products to the deal with quantity, unit price and discount. Value is computed, not typed — which prevents an entire class of arithmetic embarrassment.
  2. Pricing rules. Prices come from a price list, which may vary by customer tier, currency, region or date. Reps may be allowed to discount within a band and no further.
  3. Generate the document. A branded PDF built from a template, merging in the customer’s details and the line items.
  4. Approval, when required. If the discount crosses a threshold, the quote routes to a manager before it can be sent. Below the floor margin it may route higher still. The approval record itself is the audit artifact — who approved what, when, and why.
  5. Send and version. The sent copy is frozen and attached to the deal. Revisions create v2, v3 — you never overwrite what the customer already has.
  6. Acceptance. Electronic signature or a plain email confirmation. The deal moves to Won and, in integrated setups, the details hand off to whatever system fulfils the order.

Why approvals live in the CRM and not in email: because “who authorised that price?” is asked six months later, by someone who was not on the thread, in a meeting about margin.

19 · Automation and workflow

Everything here is one sentence with three slots: when something happens, if some condition holds, then do something.

When (trigger) If (condition) Then (action)
A lead is created Country is in Europe Assign to the Europe rep and create a “call within 24h” task
A deal enters “Proposal sent” — Schedule a follow-up task for 5 days later
A deal has no activity for 14 days Flag the card and email the owner
A deal is marked Won Value over $50,000 Notify the manager and create the handover checklist
A quote is created Discount over 15% Route for approval; block sending until approved
Every Monday 08:00 — Email each rep their overdue list

Where it pays

Removing the clerical work reps hate — creating follow-up tasks, assigning owners, chasing silence. Automation that saves the rep effort gets adopted instantly.

Where it hurts

Automation that emails customers without a human looking. One bad rule sends the wrong price to two hundred buyers, and the CRM gets blamed for the rest of its life. Keep a human in the loop on anything outbound.

ℹ Building note

Two engineering details bite everyone eventually. First, if your application runs on more than one server, a naive scheduled job runs once per server — so the customer gets three copies of the same reminder. Second, message queues generally guarantee “at least once” delivery, so a job can legitimately run twice. Both are solved the same way: make every job safe to run repeatedly, and give it a key so a repeat is recognised and skipped.

20 · Reporting and dashboards

Three distinct things get lumped together under “reporting”, and they have different consumers.

Lists

“Show me these records matching this filter.” Operational. Used constantly, by everyone.

Reports

Aggregated: count, sum, average, grouped by something. “Won value by rep by month.”

Dashboards

A screen of reports, refreshed automatically. Consumed by managers and executives who will not run a query.

The reports every sales team ends up with

  • Pipeline by stage — count and value in each column. The health check.
  • Forecast — weighted or commit-based, per rep and per team (§12).
  • Won / lost over time — with lost reasons broken out.
  • Conversion funnel — what fraction survives each stage, which exposes exactly where deals die.
  • Sales-cycle length — average days from creation to close, and days spent per stage.
  • Activity report — calls, meetings and emails per rep. Handle with care: it measures effort, not results, and rewarding it directly produces theatre.
  • Source performance — which lead channels actually produce revenue, not just volume.

⚠ A number is only as honest as its definition

“Win rate” can mean won ÷ (won + lost), or won ÷ all closed including no-decisions, or won ÷ every deal ever created. The three give very different answers from identical data. Write the definition next to the number on the dashboard — this single habit prevents a remarkable amount of argument.

21 · Users, roles and permissions

Who may see and do what. Underestimated in every first-time CRM build, and one of the hardest things to retrofit.

The four questions permissions answer

Dimension Question Typical answer
Feature access May this person use quoting at all? By role: reps yes, read-only executives no.
Record visibility Which deals may they see? Own only · own team’s · everyone’s. Managers see down their reporting line.
Permission level May they read, edit, or execute? Read · edit · approve/execute. Not a single on-off switch.
Field level May they see the cost price? Some fields are hidden or read-only for some roles even on records they can otherwise open.

The modelling insight

A flat list of permission flags (“can_edit_deals”) collapses as soon as the business says “the taster may use the AI drafting but not send, and may see quotes but not prices”. The shape that survives is a triple — (role, resource, level) — where level is an ordered scale rather than a boolean. Start there; it costs little on day one and saves a rewrite later.

Other things that live in this domain

  • Authentication — how people log in. Often two paths: sign in with a corporate Google or Microsoft account, or an email-and-password fallback for those without one. Both must land on the same user record.
  • Deactivation, not deletion — when someone leaves, disable the login but keep the user record, because their name is attached to years of history.
  • Reassignment — moving a departed rep’s accounts and open deals in bulk, without losing who owned them at the time.
  • Audit trail — who changed what and when. See §32.

22 · Data management — import, duplicates and quality

Unglamorous and decisive. A CRM’s usefulness decays in direct proportion to how much of its data people distrust.

Import

Day one is a spreadsheet with 4,000 rows and inconsistent columns. You need field mapping, a dry-run preview, a per-row error report, and the ability to undo the whole batch. “It imported 3,860 of 4,000 rows and here is a file of the other 140” is a good import tool.

Duplicate detection

Two records for the same company, spelled differently. Detect on creation (“3 similar organisations exist — did you mean one of these?”), and offer a merge that keeps both records’ history and lets you choose field by field.

Validation

Required fields, format checks, sensible ranges. Every rule is a small tax; charge it only where the data is genuinely load-bearing.

Enrichment

Filling gaps from an external source — company size, industry, registration details. Convenient, but verify: enrichment data is frequently stale or simply wrong, and it arrives looking authoritative.

Export & portability

Users must be able to get their data out. Also a legal requirement in many jurisdictions, and the thing a customer checks before trusting you.

Retention & privacy

Contact records are personal data. Consent, the right to be forgotten, and deletion rules are real obligations wherever you operate, and they interact awkwardly with the audit trail.

⚠ The migration reality

Moving from an old CRM to a new one is usually the largest single risk in the project — bigger than any feature. Old systems contain years of accumulated mess, and the mapping between two data models is never one-to-one. Budget serious time, migrate in rehearsals rather than one big night, and agree in advance what will not be brought across.

23 · Integrations, the API and mobile

A CRM that cannot talk to anything else becomes a data island, and islands get abandoned.

Integration What it does Difficulty
Mailbox Pulls email onto records, sends on the user’s behalf Medium — authentication and permission scopes are the fiddly part
Calendar Two-way meeting sync Medium-hard — reschedules, cancellations and recurring events
Website forms Creates leads from enquiries Easy — and the highest value per hour of work
Accounting / ERP Won deals become orders and invoices; payment status flows back Hard — two systems disagree about what a “customer” is
E-signature Sends the contract, records the signature Easy — well-documented, well-trodden
Telephony Click to call, log the call, record it Medium — plus consent rules on recording

The three integration patterns

Polling

Ask the other system every few minutes “anything new?” Simple, slightly stale, wasteful at scale.

Webhooks

The other system calls you the instant something happens. Efficient and near-real-time; you must handle retries and duplicates.

Batch / file

A nightly file exchange. Unfashionable, entirely appropriate for systems that only need to agree once a day.

Mobile

Field sales need three things on a phone and rarely more: look up a customer before walking in, log what happened while it is fresh, and see today’s list. Full-fat CRM on a small screen is a well-known way to build something nobody opens twice. Trade-show and site-visit capture is the one place a purpose-built mobile app genuinely beats the web app, because the camera and offline capture matter.

24 · The AI layer

The newest domain, and the one with the widest gap between marketing and value. Stripped of hype, current AI is good at a specific set of CRM chores.

Job What it does Why it fits
Extraction Reads an incoming enquiry email and fills in product, quantity, destination, requested date Turns unstructured text into structured fields — reliably the highest-value use
Summarisation “Forty emails on this account since March, in five bullet points” Compresses history a human would never re-read
Drafting Writes a first-pass reply or follow-up for the rep to edit Blank-page problem solved; the human still owns the send
Triage & scoring Ranks incoming leads, flags the ones that look serious Judgement at volume no human wants to apply
Data cleanup Spots likely duplicates and inconsistent values Fuzzy matching is exactly this kind of task
Ask-your-data “Which German customers have not ordered since January?” in plain language Removes the report-building barrier for non-technical users
Human-in-the-loop AI pattern: data to model to draft to human review to action CRM data + incoming message AI model extract · draft · score A suggestion never an action yet Human reviews edit · approve · reject Action taken sent · saved · assigned Rejected nothing leaves the building The gate at "Human reviews" is the entire safety design. Do not remove it.
Diagram 7 — the human-in-the-loop pattern. AI proposes; a person disposes.

⚠ Three rules that keep AI in a CRM useful

  1. A human approves anything a customer will see. The cost of a confidently wrong price or promise is not recoverable by an apology.
  2. The system must work with AI switched off. Treat it as an accelerator on a manual path, never as the only path — providers have outages and features get disabled.
  3. Be explicit about where customer data goes. “Which company processes our buyers’ emails, and under what terms?” is a question you will be asked, and the answer needs to already exist.

Part 5 — Kinds of CRM

Not all CRMs are the same shape. Three axes of difference explain most of the market.

25 · Three flavours: operational, analytical, collaborative

A classic taxonomy. Real products mix all three; the labels tell you where a product’s centre of gravity sits.

Operational

Runs the day. Pipelines, activities, automation, quotes. Optimised for doing the work.

— most sales CRMs

Analytical

Understands the past. Segmentation, cohort analysis, churn and propensity modelling. Optimised for learning.

— needs volume to pay off

Collaborative

Shares across departments so sales, support and delivery see one customer. Optimised for handover.

— matters at scale

If you are building or buying for a team of ten to thirty, aim squarely at operational and add analysis later. Analytics on a thin data set produces confident nonsense.

26 · B2B vs B2C, and generic vs vertical

Business-to-business versus business-to-consumer

Dimension B2B — selling to companies B2C — selling to individuals
Who buys A committee: user, budget holder, technical checker One person
Deal count Hundreds, each large Millions, each small
Cycle length Weeks to years Minutes to days
Price Negotiated per customer Published, fixed
Core object The organisation; people hang off it The person; there is no organisation
What the software optimises Depth — everything known about one account Scale — segmenting and messaging millions

This is the single biggest fork in CRM design. A B2C tool used for B2B feels shallow — no room for the buying committee, the sample round, the negotiation. A B2B tool used for B2C collapses under volume. Choose the side you are on before comparing features.

Horizontal versus vertical

Horizontal (generic)

Works for any industry: contacts, deals, activities. Configure it with custom fields to fit your world.

Upside: cheap, proven, huge ecosystem, someone else maintains it.
Downside: your industry’s actual process — multi-round sampling, certification checks, weekly price publication — has to be faked with generic fields, or lived without.

Vertical (industry-specific)

Built for one industry. The industry’s real nouns are first-class objects with their own screens and rules.

Upside: the process is modelled properly, so the software enforces what actually matters.
Downside: smaller vendor, higher cost, or you build it yourself.

The decision rule: if the thing that differentiates your business is exactly the thing a generic CRM cannot model, that is the argument for a vertical or custom system. If your process is genuinely ordinary, paying to rebuild it is a poor trade.

27 · The neighbours — adjacent systems and where the borders run

Vendors blur these deliberately because every category wants to sell you the next one. The distinctions are real.

System Its job The border with CRM
Marketing automation Attract and warm up strangers at volume — campaigns, newsletters, landing pages, nurture flows Marketing hands over a qualified lead; the CRM takes it from there. The handover point is the argument.
Help desk / service Handle problems from existing customers — tickets, SLAs, knowledge base Same customer, different lifecycle stage. Both should see the same account record.
ERP Run the business after the sale — inventory, production, shipping, invoicing, accounts The CRM owns the promise; the ERP owns the fulfilment. A won deal crosses this line, and that crossing is the most common integration in existence.
CDP Unify behavioural data about individuals from every channel Mostly a B2C concern; overkill for a few thousand business accounts.
Spreadsheets Everything, badly, but instantly The real incumbent competitor. Never dismiss it: it wins whenever the CRM is slower than typing a row.

ℹ Names you will hear

At the large-enterprise end: Salesforce and Microsoft Dynamics — enormously capable, enormously configurable, and requiring dedicated administrators. Mid-market: HubSpot (strong marketing heritage) and Zoho (broad and inexpensive). Deliberately simple and sales-focused: Pipedrive and Freshsales — built around the pipeline board and easy for a small team to actually adopt. Generic work platforms such as Monday and Airtable are also pressed into CRM service. The categories matter more than the brands: enterprise platform, mid-market suite, simple sales tool, configurable work platform.

Part 6 — In practice

Concepts assembled into a real week, a real deal, and the real reasons projects go wrong.

28 · One deal, end to end

A single worked example that touches nearly every domain in this document. A tea exporter; a buyer in Poland; fifty-two days.

Timeline of a single deal over fifty-two days Day 0 Web form lead created Day 3 Qualified → deal created, $48k stage: Qualified Day 10 Samples shipped stage: Sampling Day 24 Quote v1 sent · discount 12% approved stage: Proposal sent Day 38 Quote v2 · terms agreed stage: Negotiation Day 52 WON · $44,600 handed to fulfilment Between the marked events sit 31 logged activities — emails, two calls, one video meeting — all captured automatically or in one click.
Diagram 8 — one deal's life. The dots are stage changes; the value between them is the activity history.
  1. Day 0 — capture. A buyer fills in the website enquiry form. A lead is created automatically, source recorded as “website”. A rule sees the country is Poland and assigns the Europe rep, creating a task: call within 24 hours.
  2. Day 1 — first contact. The rep calls, logs the call in fifteen seconds from their phone, and learns the buyer wants 12 tonnes of black tea for a private-label product, needed in Q1.
  3. Day 3 — qualify and convert. Budget plausible, authority confirmed, need real, timing this quarter. The lead converts into an organisation (Kowalski Sp. z o.o.), a person (the procurement manager), and a deal valued at $48,000. Stage: Qualified.
  4. Day 4–9 — the conversation. Eleven emails, captured onto the record automatically because the sender matches a known contact. Nobody types “logged an email” once.
  5. Day 10 — samples. The buyer asks for samples. A task goes to the technical team; three blends ship. Stage: Sampling. This is where a generic CRM starts to strain — “sample round two, rejected, reformulate” is a real process that a plain Notes field models badly.
  6. Day 22 — sample approved. Blend two is accepted. A second person on the buyer’s side joins the thread — the quality manager — and is added to the deal.
  7. Day 24 — quote. The rep builds the quote from the price list. The 12% discount exceeds the 10% self-service band, so it routes to the manager, who approves it with a note. A PDF goes out; the sent version is frozen on the record. Stage: Proposal sent.
  8. Day 29 — silence. Five days of nothing. The card turns amber; an automated reminder reaches the rep, who follows up. Without that nudge this is exactly where deals quietly die.
  9. Day 38 — negotiation. The buyer wants different payment terms and a slightly smaller volume. Quote v2 is issued; v1 stays on the record. Stage: Negotiation.
  10. Day 52 — won. Signed at $44,600 — not the original $48,000, and the CRM records the real number. The deal flips to Won, the organisation’s status changes from prospect to customer, and the order details hand over to whatever fulfils it.
  11. Afterwards. The account now has a documented history. Next season’s enquiry starts from knowledge, not from zero — and that is the compounding return that justifies the whole system.

29 · The metrics that matter

Nine numbers cover most of what a sales team needs. Each is shown with worked arithmetic so the definition is unambiguous.

Metric How it is calculated What it tells you
Win rate won ÷ (won + lost)

38 ÷ (38 + 62) = 38% | Whether you are choosing and closing the right deals. Say which denominator you used. |

| Average deal value | total won value ÷ deals won

$1.7m ÷ 38 = $44,700 | Whether you are moving up- or down-market over time. |

| Sales-cycle length | mean days from creation to close

52 days | How far ahead you must fill the pipeline to hit a target. |

| Stage conversion | entered stage N+1 ÷ entered stage N

34 ÷ 61 = 56% | Exactly which stage leaks. The most actionable number here. |

| Pipeline coverage | open pipeline ÷ target

$1.08m ÷ $400k = 2.7× | Whether there is enough raw material. Under 3× is usually a warning. |

| Response time | median minutes from lead arrival to first contact

3h 40m | Speed to first touch, one of the most reliably outcome-linked numbers in sales. |

| Activities per deal | logged activities ÷ deals closed

31 | The effort a win actually costs. Useful for capacity planning. |

| Deal slippage | deals whose close date moved out

9 of 24 = 38% | Whether forecasts are optimistic. Chronic slippage means the stage definitions are soft. |

| Loss reasons | count and value grouped by reason | The cheapest strategy input available (§11). |

Reading them together

Individually these numbers mislead; in pairs they diagnose. A high win rate with thin pipeline coverage means the team is being too picky about which deals to chase. A long cycle with high activity-per-deal means effort is going into deals that were never qualified properly. Falling average deal value with a rising win rate means you are winning easy small business and avoiding hard large business.

30 · Why CRM projects fail

Very few CRM failures are technical. These are the recurring causes, in rough order of frequency.

1 · Reps do not use it

The system asks for effort and gives back nothing the rep values, so it becomes a reporting chore done badly at month end. Fix: make it faster than the spreadsheet, capture data as a by-product of real work, and give reps something back on day one — usually the “what do I owe today” list.

2 · The data is not trusted

Duplicates, stale owners, blank fields. Once a manager finds one wrong number, the whole system is treated as unreliable and everyone reverts to their own spreadsheet. Fix: invest in the import and dedupe path early, not late.

3 · Over-customisation

Forty custom fields, eleven pipeline stages, mandatory everything. The system now describes an idealised process nobody follows. Fix: start minimal; add a field only when a named report needs it.

4 · Modelling the process you wish you had

The stages describe the sales methodology from a training course, not what actually happens. Reps cannot map reality onto it, so they guess. Fix: watch three real deals before naming a stage.

5 · No owner after launch

The project team disbands; nobody maintains stages, fields or users; the system drifts for two years. Fix: a named administrator, permanently.

6 · A migration that lost history

The old data came across half-mapped, so the answer to “what did we agree last year?” is now “check the old system”. Confidence never recovers. Fix: rehearse the migration, and agree the exclusions explicitly.

7 · Reporting-first design

Built for the manager’s dashboard rather than the rep’s day. The dashboard is only as good as the data, and the data comes from the person nobody designed for. Fix: design for the rep; the dashboard follows.

8 · Big bang rollout

Everyone, everything, one Monday. Every problem arrives simultaneously and the system’s reputation is set in week one. Fix: a small pilot team, real deals, fix the friction, then widen.

✔ The one-sentence version

A CRM succeeds when a salesperson would be annoyed if you took it away. Every other measure of success is downstream of that.

Part 7 — Building one

If you are on the engineering side of a CRM rather than the buying side, this is the part that matters.

31 · Reference architecture

Stripped to essentials, nearly every CRM has this shape. The technologies vary; the layers do not.

Layered reference architecture of a CRM application CLIENTS Web app in the browser Mobile / capture app Other systems calling the API EDGE API layer authentication · permission checks · validation · rate limiting — every request passes through here, no exceptions LOGIC Domain services deals · contacts · quotes · pricing the business rules live here Background workers mail sync · reminders · imports fed by a queue, safe to retry AI service extract · draft · summarise · score behind one swappable interface STATE Relational database the system of record — one shared truth File storage quotes, photos, specs Search index fast find-anything OUTSIDE The outside world mail server · calendar · website forms · accounting / ERP · e-signature · the AI provider
Diagram 9 — the layers. The one rule worth defending: permission checks live at the API layer, so no client can be trusted to enforce them.

Why background workers are not optional

Mail sync, imports, PDF generation and AI calls are slow and failure-prone. Running them inside a web request means users staring at spinners and losing work when something times out. Push them onto a queue and let a worker retry.

Why the AI sits behind an interface

Model providers change, prices change, and some customers will insist their data never leaves a particular boundary. If every AI call goes through one seam, swapping the implementation is a contained job rather than a rewrite.

32 · Data-model gotchas

Eight decisions that are cheap on day one and expensive in year two. Each one has bitten many teams.

1 · Never hard-delete anything a human touched

Use a “deleted” marker and hide the record. Someone will delete a customer with three years of history by accident, and “restore from last night’s backup” means losing everyone else’s day.

2 · Prices are effective-dated rows, not editable values

If you overwrite last week’s price, you can no longer answer “what did we quote them in March, and was it right at the time?” Store price as a row with a validity period and never update in place. Retrofitting this touches every read path in the system — it is close to unfixable later.

3 · Stage identity is separate from stage name

Administrators rename stages. Automation, reports and AI logic key on stage meaning. Give each stage an immutable internal type alongside its editable label, or a harmless rename will silently break the rules that keep the pipeline honest.

4 · Money needs a currency and a rate date

A bare number is not an amount. Store the currency with the value, and — if you report in a base currency — the exchange rate as at the moment of the transaction, not today’s.

5 · People-to-organisations is many-to-many in the real world

Agents, consultants, and people changing jobs all break the “one person, one company” assumption. Even if you launch with a single link, model it so the second one is an insert rather than a migration.

6 · Audit the changes, not just the current state

Who changed the value from $48k to $44.6k, and when? Append-only change records, written by the same code path that does the update so nothing can slip past.

7 · Ownership is a field with history

Accounts get reassigned. “Whose deal was this in Q1?” is a commission question, and the answer is not “whoever owns it now”.

8 · Decide the activity shape early

Activities attach to deals, people, organisations, and sometimes to nothing. That “attaches to several kinds of thing” relationship has several implementations with quite different query and integrity properties. Pick deliberately — it is one of the most-read tables in the system.

33 · Buy versus build

The honest version, without the vendor gloss or the engineer’s optimism.

Dimension Buy an off-the-shelf CRM Build a custom one
Time to first use Days Months
Cost shape Per user per month, forever, rising as you grow Large up front, then hosting and maintenance
Fit to your process Good for ordinary processes; increasingly awkward for unusual ones Exact, because you decided it
Features you get free Mobile apps, integrations, import tools, audit, permissions — thousands of person-years Every one of those is yours to build
Who fixes it at 2am The vendor You
Data ownership Yours, in their system, subject to their terms Entirely yours
Risk Vendor changes pricing, is acquired, or drops a feature you depend on You underestimate the work — the near-universal outcome

Build when…

  • Your sales process is your competitive advantage and no product models it.
  • You have tried a generic CRM and the gap is specific and articulable.
  • You need deep integration with systems no vendor supports.
  • You will keep a team able to maintain it for years.

Buy when…

  • Your process is ordinary, even if it feels special.
  • You need it working this quarter.
  • Nobody will own the software after launch.
  • You cannot yet name the three things a product fails to do.

⚠ The trap in the middle

“We’ll build something simple” is where most custom CRM projects begin, and simple is a moving target. The core — contacts, deals, stages — genuinely is a few weeks. The remaining 80% is permissions, email sync, import, duplicates, audit, mobile, exports and the hundred small behaviours users expect because every other tool has them. If you build, be clear-eyed that those are the project, not the deal board.

Part 8 — Closing

Where the general picture meets the system in this folder, and the vocabulary in one place.

34 · Mapping this onto the Empire Teas CRM

This document is deliberately generic. Since it sits alongside the Empire Teas project documents, here is how the general concepts line up with the specific system being built — a bridge, not a substitute for the project’s own PRD and architecture documents.

Generic concept How it shows up in the Empire Teas system
Vertical vs horizontal (§26) The whole premise. Pipedrive is the horizontal incumbent being replaced; the tea-export process — multi-round sample development, certification checks, export documentation, quote-readiness gating — is exactly the “process a generic CRM cannot model” case from §26.
The five core objects (§04) All present, plus tea-specific first-class objects rather than custom fields bolted onto generic ones. The project’s core/domain split keeps the generic CRM and the tea domain separable by design.
Custom fields vs typed columns (§07) Decided deliberately both ways: admin-defined extras use the flexible route; the tea domain’s real vocabulary gets proper typed extension tables, because those fields are sorted, priced and reported on.
Stage identity vs stage name (§08, §32) An explicit locked decision — every stage carries a stable internal type separate from its editable display name, precisely so administrator renames cannot break automation.
Effective-dated pricing (§32) Central rather than incidental: weekly bulk prices are published by a pricing team, and both price history and as-of quoting are requirements. Prices are dated rows, never updated in place.
Approvals (§18) Two tiers rather than one — a manager approves ordinary discounting, and quotes below the floor margin escalate further. The approval record is the audit artifact.
Permission triples (§21) Six roles resolved as (role, resource, level) with read-only / edit / AI-use / execute levels, exactly the shape §21 argues for over flat flags.
Human-in-the-loop AI (§24) The stated design: AI handles lead triage, inquiry extraction, account briefings and drafting; a human approves every AI action, and all pricing stays human-set. AI outages degrade to the manual path.
Mobile capture (§23) The trade-show capture app — camera and QR capture of business cards feeding lead intake — is the §23 case where a purpose-built mobile app genuinely beats the web app.
Background workers (§31) All timed work runs through a scheduler and a queue rather than inside the application process, for the exact multi-instance duplicate-send reason described in §19; every queued job carries an idempotency key.
ERP border (§27) Drawn explicitly: the CRM owns the promise, and the handover to fulfilment ships as a manual document behind a seam until the ERP interface is confirmed.

ℹ Where to go next

For the specifics, the project’s own documents are authoritative over anything in this primer: the product requirements, the system architecture, and the plain-language client PRD. This page is background reading, not a source of record.

35 · Glossary

Every term used in this document, plus the ones you will meet in a CRM sales demo.

Term Meaning
Account Another word for organisation — a company you sell to.
Activity Something that happened or must happen: a call, email, meeting or task.
Audit trail An append-only log of who changed what, when.
BANT Budget, Authority, Need, Timing — a simple qualification checklist.
B2B / B2C Selling to businesses / to individual consumers.
Churn Customers who stop buying. A retention metric, more common in subscriptions.
Close date The date a deal is expected to be decided. Drives forecasting.
Commit A deal the rep is personally confident will close this period.
Contact A person you deal with. Sometimes used loosely for the company too.
Conversion rate The fraction of records that get from one point to the next.
Custom field An admin-defined field added without a developer.
Deal One potential sale with a value, stage and owner. Also called an opportunity.
Deduplication Finding and merging records that describe the same thing.
Enrichment Filling in missing details from an external data source.
ERP The system that runs operations after the sale — inventory, production, invoicing.
Forecast An estimate of what will close in a period.
Funnel The shrinking shape of the pipeline as records drop out at each stage.
Idempotency The property that doing something twice has the same effect as doing it once — essential for background jobs.
Kanban The column-and-card board layout used for pipelines.
Lead Unqualified interest that has not yet been judged worth pursuing.
Lead scoring Ranking leads by a computed number combining fit and intent.
Lost reason A structured code recorded when a deal is lost. Disproportionately valuable.
MEDDIC A heavyweight qualification framework for large, complex deals.
Merge fields Placeholders in a template filled from record data.
Opportunity Another word for deal.
Pipeline The ordered set of stages a deal passes through, and the deals currently in them.
Pipeline coverage Open pipeline divided by the target. Typically wants to be 3× or more.
Price list A set of prices, often varying by customer tier, currency, region or date.
Prospect A potential customer who has not bought yet.
Qualification Deciding whether a lead is worth pursuing.
Quote A priced offer sent to a customer. Versioned.
Record Any single stored item — one contact, one deal, one activity.
Rot / idle A deal with no activity for too long. Usually flagged automatically.
Sales cycle How long a deal takes from creation to close.
Sequence An automated series of follow-up messages that stops when the person replies.
SLA An agreed response or resolution time.
Soft delete Marking a record deleted and hiding it, rather than removing it.
Source Where a lead came from. Recorded once and never overwritten.
Stage One step in a pipeline. Has a display name and, in well-built systems, a stable internal identity.
System of record The one place a fact officially lives; everywhere else holds a copy.
Territory A slice of the market — geographic or otherwise — assigned to a rep.
Timeline The reverse-chronological feed of everything that happened on a record.
Weighted pipeline Deal values multiplied by stage probability and summed.
Win rate Deals won as a fraction of deals decided. Define the denominator.
Workflow An automated when / if / then rule.

✔ If you remember only five things

  1. A CRM is a shared memory of customers, conversations and in-progress sales — the relationship belongs to the company, not the salesperson.
  2. Five objects carry it: organisation, person, lead, deal, activity.
  3. The pipeline is the product. Stages should name verifiable buyer states, not your own intentions.
  4. Data captured as a by-product of real work survives; data that must be typed in for someone else’s benefit does not.
  5. CRM projects fail on adoption, data quality and over-customisation — almost never on missing features.

Generated from .forge/discovery/research/crm-basics.md by .claude/lib/render-docs-html.js. Markdown is canonical.