Relationships in Connect
Connect keeps one canonical human — a Person — and hangs everything else off it: the identities they answer on, the company they belong to, their lifecycle stage, their deals, cases and follow-ups, and one timeline that shows the lot. relationship_console answers a question about one relationship for the Owner and for a customer out of the same body of code; only the words on the screen differ.
Three records, and why they are three#
- Person
- The canonical human. One row per human, no matter how many addresses they write from or ring from.
- Identity
- One address on one channel — an email address, a phone number, a WhatsApp handle — stored as its own row and keyed by
value_key(kind, value). A person may hold many. - Company
- The organisation. Several people attach to one company, and a company carries what belongs to the organisation rather than to any individual.
Collapsing those three into one row is the mistake this model exists to avoid. A human who writes from work, replies from a personal address and then rings from a mobile is one relationship with three identities; a design that keys off the address gives you three strangers and no history. Keeping identities as rows also means adding a channel adds rows rather than columns — see one person across phone, email and WhatsApp.
One body, two doors#
relationship_console is a single module with a thin router in front of it on each side. The Owner reaches it through the operator API; a customer reaches it through /api/customer/ui/… after tenantAdapt rewrites the path. There is no second implementation and no reduced customer view — what changes is vocabulary.
| Owner | Customer | What it answers |
|---|---|---|
relationships | people | The same records, through the same code |
listing | listing | The bounded list, with search and paging done in SQL |
detail | detail | One person with their identities, stage and open work |
story | story | The written summary, with names scrubbed on the way out |
by_handle | by_handle | Resolution from one channel address to the person |
That rename is recorded rather than remembered: ALIASES in the audience parity suite carries it, which is how a capability that exists on one surface and not the other is caught as a defect instead of shipping. Relationships for the Owner and for a customer covers that seam in full.
What each page here answers#
- People — the person record, and how much of it is derived rather than typed.
- Identities — why one address on one channel is a row of its own.
- Companies — what belongs to an organisation rather than to a human.
- Customer 360 and the timeline — the assembled views, and where each part of them comes from.
- Duplicate detection, merging and what a merge preserves — a proposal, a human decision, and the record that survives it.
- Lifecycle stages and stage normalisation — progression, and what happens to a stage nobody recognises.
A list is a query, not a loop#
Relationship screens are lists, and lists here have a measured history. The Owner's customer list once fetched the user, the workspace and the entitlement for every membership one at a time: 1,857 accounts cost 5,574 statements. Three inner joins say the same thing in three. The unit that matters is statements rather than seconds, because a threshold in seconds measures the machine you happened to run it on.
Everything in this section#
16 pages, each with its own status and the date it was last checked against the running system.
| Page | What it covers |
|---|---|
| Companies | The company record, how several people attach to one organisation, what belongs to the company rather than to a human, and when not to create one. |
| Customer 360 | One person's whole history in a single view: what is assembled into it, which service each part comes from, and what it deliberately leaves out. |
| Duplicate detection | How two records come to describe one human, what a duplicate proposal is and is not, and why nothing is ever joined without a person saying so. |
| Finding a person or company | Finding a person or company: what is matched, why counting and paging happen in SQL, and how a per cent sign typed in the box is treated as a character. |
| Identities | One address on one channel is its own row: how identities attach to a person, how they are keyed, and what happens when one is attached to the wrong human. |
| Lifecycle stages | The six stages a relationship moves through, what may move it, why becoming a client needs a person, and where the history of every move is kept. |
| Merging two records | Merging two records is a human decision: who makes it, what happens at the moment it runs, what changes for every channel, and what cannot be undone. |
| Normalising a stage | Why one column holds three vocabularies, how an unfamiliar stage word is read, and the message that went unanswered when a lookup raised instead. |
| One person across phone, email and WhatsApp | How the same human is recognised when they arrive on a second channel, what counts as evidence, and why a likeness is a proposal rather than a match. |
| People | The person record: what you type, what Connect derives, what attaches from other services, and why blocking somebody is not a field on it. |
| Relationships for the Owner and for a customer | The Owner calls them relationships and a customer calls them people: the same records, the same code, and the rewrite that makes one path serve both. |
| The contact brief | The short block about a person that a channel is given before it answers: what is in it, the character budgets, and why every line has to earn its place. |
| The customer timeline | What appears on a person's timeline, where each entry comes from, the ordering rule, and the query cost that once made this screen expensive. |
| The relationship summary | The written relationship summary: what it is assembled from, why it is not a stored document, and the name guard that rewrites it on the way out. |
| What a merge preserves | The itemised guarantee: identities, stages, follow-ups, deals, demos, cases and onboarding all survive a merge, and what happens when both sides hold one. |
| What Connect remembers about a person | The contact tier of memory: what Connect knows about one human, how a fact gets there, how it is read into an answer, and how anyone removes it. |
Questions#
Is a prospect the same thing as a person?
No. A prospect is an organisation or person discovered by research and not yet a relationship; a Person is a human the workspace actually deals with. Prospecting has its own section at /docs/prospects/, and a prospect who starts a conversation becomes a person through the same first-contact path as anybody else.
Does a customer see fewer relationship features than the Owner?
No. Every capability here runs for both audiences over one implementation. The only differences are commercial — a customer's use is bounded by their plan's allowances — and lexical, where the customer surface says people for what the Owner calls relationships.
Where do deals and support cases live?
On the person, but documented in their own sections: support for cases and onboarding, sales for opportunities and demos. A merge carries all of them, which is why merge safety names each one.