> ## Documentation Index
> Fetch the complete documentation index at: https://internal.softcrum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# crm

> crm is the human layer over everything the suite already knows. It holds what a person wrote about a customer, what someone has to do next, and the one screen that shows a customer's whole history — purchases, points, messages and notes.

> `crm` is the human layer over everything the suite already knows. It holds what a person wrote
> about a customer, what someone has to do next, and the one screen that shows a customer's whole
> history — purchases, points, messages and notes — in a single chain.

## Who this is for

| Persona                      | Hires this module to                                                                                |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| **Support agent** (tenant)   | Open one screen and understand a customer without asking them to explain, or checking four systems. |
| **Account manager** (tenant) | Remember what was agreed, and not forget the follow-up.                                             |
| **Marketing lead** (tenant)  | Keep a static list — event attendees, a pilot group — that a dynamic segment cannot express.        |

## The problem today

A company running a loyalty program ends up with the customer's history split across the point of
sale, the loyalty tool and the email platform. When that customer calls to complain that they never
got their points, the agent checks three systems, none of which agree, and the customer explains
themselves twice.

The suite already holds all three. What is missing is a place to put the human part and one view
that joins it.

The honest second half: **we are not trying to replace HubSpot or Salesforce**. A tenant with a
sales organization already has one and will keep it. We are the CRM for the customer relationships
the loyalty program creates, which those tools do not see at all.

## What it does *(normative)*

* **Notes** on a contact, attributed and audit-logged.
* **Activities**: something to do, assignable, with a due date, over a tenant-extensible type
  vocabulary (DEC-B4).
* **Lists**: static membership and saved filter views, distinct from `core`'s dynamic segments.
* **Timeline 360**: a merge-sorted view over behaviour, points, messages, notes and activities,
  filtered by the reader's permissions and chained by `correlation_id`.
* A **reserved object model** so deals and pipelines can arrive later without a data migration.

## Non-goals *(normative)*

* **No pipeline, deals or forecasting in v1.** Explicitly deferred, not forgotten: FS-CRM-0005
  reserves the model. Building them now means competing with tools our customers already pay for.
* **Not a ticketing system.** An activity is a reminder, not a support case with SLAs and queues.
* **No email inbox or two-way sync.** Messages appear in the timeline as sends; replies go to the
  tenant's own address.
* **No duplicate contact management.** Identity resolution and merging are `core`.
* **Not a reporting tool.** The timeline is per contact. Cross-contact analytics is a later concern
  and reads from the same data.

## Success

| Measure                                                                              | Target                                          | By                    |
| ------------------------------------------------------------------------------------ | ----------------------------------------------- | --------------------- |
| Timeline load for a contact with 5 000 events                                        | p95 \<1 s, first page                           | certification, pre-G1 |
| A support agent answering "why did this customer get this message"                   | from the timeline alone, without another system | G1-Engage             |
| Correlation chain visible end to end — purchase → points → email → open → redemption | one screen                                      | G1-Engage             |
| Notes and activities used weekly by the design partner                               | in use, not just present                        | first month after G1  |

## Commercial shape

`crm` is not separately metered. It is included, and it is one of the reasons the suite is worth
more than a loyalty engine on its own.

Two things become plan-gated later rather than priced now: **activity assignment across a team**,
which only matters at a size that correlates with a higher plan, and the **object model** when deals
arrive.

## Phases

| Phase   | Contents                                                                               | Target                |
| ------- | -------------------------------------------------------------------------------------- | --------------------- |
| **F1a** | Notes · activities · lists and saved views · timeline 360 · reserved object model      | G1-Engage, 2026-11-01 |
| **F1b** | Attachments on notes · activity reminders through `messaging` · bulk actions on a list | post-G1               |
| **F2**  | Deals and pipeline over the reserved model · cross-contact reporting                   | 2027                  |

## Compliance and risk

Notes are **free text written by humans about identified people**, which makes them the least
predictable personal data in the platform. Two consequences:

* Notes are **deleted on erasure**, with no anonymized remnant. Unlike a ledger row, a note has no
  accounting value that survives the person.
* The timeline is **filtered by the reader's permissions**. An agent without
  `core.contacts.read_national_id` sees a masked one there too — a joined view is exactly where a
  permission gets forgotten.

The product risk is scope creep: a CRM invites "just add a pipeline" until it becomes a second
product built by nobody. The non-goals exist to be enforced, and FS-CRM-0005 is how we say no
without saying never.

## Dependencies

`core` for contacts and events. Read-only projections of `loyalty` and `messaging` data for the
timeline, **through their public read paths, never their tables** — the module boundary holds even
for a read.

## Open questions

| # | Question                                                               | Decides | By                          |
| - | ---------------------------------------------------------------------- | ------- | --------------------------- |
| 1 | Can a note be edited after creation, or only appended to?              | Daniel  | before FS-CRM-0001 approval |
| 2 | Are activities assignable to any user, or only to the account's owner? | Daniel  | before FS-CRM-0002 approval |

## Changelog

| Version | Date       | Change        | Why | Author                 |
| ------- | ---------- | ------------- | --- | ---------------------- |
| 0.1.0   | 2026-08-17 | Initial draft | —   | daniel + claude-opus-5 |