Section 4 · Nutshell — Turn 30,000 Records Into an Asset
4.1Two-way Nutshell connection
Built in the POC- No.
- 4.1
- DMA's reference
- Decision Book p.14
- Phase
- Phase 1
- Autonomy
- L3 · Act within rules
- DMA's decision
- Yes
★ Marked "non-negotiable, build first" in the book.
What DMA asked for · Decision Book p.14
New conversations update Nutshell, and Nutshell's history informs the AI about returning prospects.
Why it matters to DMA: Without it nothing else works: it is the foundation.
In our words, from DMA's Product Decision Book v3, page 14.
How we do it
- Reading: after DMA connects Nutshell (an email and an API key on the dashboard), a full backfill copies accounts, people, leads, notes, activities and tasks into the bridge database. From then on, changes come in through Nutshell's webhooks and its change feed (every 15 seconds in the prototype), and a nightly check compares a sample against Nutshell and repairs any drift.
- Writing: every change for Nutshell goes through the write gate as the "DMA AI" user: leads from the chat, notes, tasks, AI fields. Each is approved where DMA's rules say so, written once, and journaled with the value it replaced.
- The two directions don't echo: a change the system wrote itself is recognised when it comes back, so it doesn't trigger another round of work.
- In the prototype the connection points at a Nutshell simulator with synthetic data and the same API; connecting DMA's real Nutshell is a change of address and key.
The flow
It plays on its own while it's on screen; hover or use the controls to pause or step through.
Nutshell to the bridge
The backfill, then every change, reaches the mirror within seconds.
- Nutshell
- Rule in code
- Stored data
- AI
- Routing
Where the data goes
The same six stages on every page. Nothing reaches Nutshell except through the write gate.
- 1Nutshell
Source
Accounts, people, leads, notes, activities, tasks.
- 2Sync
Copies Nutshell changes into the bridge database
Backfill, webhooks, the change feed and a nightly drift check.
- 3Bridge database
A copy of the CRM data, plus what the AI works out
The mirror, and the journal of every write.
- 4AI
Claude models, only through DMA's own gateway
Reads the mirror; never calls Nutshell.
- 5Write gate
The only way back into Nutshell: checked, approved when needed, sent once
The only writer, as the "DMA AI" user.
- 6Nutshell
The system of record
Updated through its API; its own AI stays off.
The tables behind it
Drawn from the POC's database catalogue: structure only, no data.
PK primary keyFK reference the database enforces (solid line)ID reference kept by id (dashed line)
| Table | What it holds | Columns |
|---|---|---|
| ops.sync_runs | Every backfill, change poll and nightly check, with counts and any drift found. | 9 |
| crm.accounts | The mirrored companies, with their Nutshell id and when they were fetched. | 17 |
| ctrl.write_journal | Every field the system wrote, before and after. | 12 |
Worked example
Synthetic demo data: every name, business and number is made up.
The same account, in Nutshell and in DMA AI
What you see
1.The record in Nutshell
The CRM simulator (standing in for Nutshell) shows what DMA AI wrote: the AI fields and a timeline entry.
What happens in the system
- Write gate
write gateAI fields and the note were written by the "DMA AI" user, each journaled.
- Nutshell
Written through Nutshell's API, as any integration would.
The prototype's connection to the Nutshell simulator (synthetic data).
Sync activity
| Kind | What it does | When |
|---|---|---|
| Backfill | Copies everything once, on connecting | Once |
| Change feed | Picks up changes since the last check | Every 15 seconds in the prototype |
| Webhooks | Nutshell tells the system something changed; ten quick edits cause one refetch | As it happens |
| Nightly check | Compares a sample with Nutshell and repairs drift; a full sweep weekly | 01:00 daily |
In the running POC
1 / 3A record in the CRM simulator, with what DMA AI wrote.
- 1The AI fields.
- 2The DMA AI timeline entry.
CRM simulator (stands in for Nutshell) · one company record. Captured from the running POC on September 25, 2026; synthetic data.
See it live
Opens the exact screen in the running POC, in a new tab.
| Open | Where | What to try |
|---|---|---|
| The CRM simulator | CRM simulator (stands in for Nutshell) | The Nutshell side. |
| Accounts | DMA AI dashboard | The DMA AI side of the same records. |
Status
Built in the POC. This capability runs in the POC today, on synthetic data, end to end.