Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
Plan — Dynamic fields
Fields a workspace defines for itself, on companies, contacts and deals, edited from one sheet that opens from any record.
The visual design is in Paper, file CRM, page crm - lewis, artboards
Dynamic fields — cog placement, /companies?record=company:abcd&manageFields=company,
Dynamic fields — new field & empty and Dynamic fields — on the record. This
document is the half Paper cannot hold: the model, the API and the agent.
This document is the design record — what we decided and why. The build order —
files, procedures, component mapping, phases — is
dynamic-fields-build.md, which points back here
for the schema in §3 rather than copying it.
Read it with AGENTS.md, api.md and
design.md.
1. One sheet, one cog
The cog goes in the DETAILS section header, on all three sheets. That is the
action slot DetailSheetSection already has, so no new primitive and no
per-sheet variation — the same element in the same place whether DETAILS is the
full width of the contact sheet or the 320px rail of the company sheet.
Not the header bar beside Re-enrich and Close: that bar is about this record, and the cog is not. It changes every company at once.
Which is the one thing the sheet has to say out loud. It opens with "This shapes every company in your CRM", because a control reached from Northwind Labs' sheet will otherwise be read as belonging to Northwind Labs.
The sheet stacks over the record sheet at 460px, dimming it, and carries an entity switcher — Companies / Contacts / Deals — so the same sheet reached from a deal can still fix a contact field without closing anything.
State lives in the URL beside record, in record-stack.ts:
/companies?record=company:abcd&manageFields=company
so it is shareable, Escape and Back close it in the right order, and the record underneath survives a refresh.
2. Standard fields are in the list
The sheet shows two groups: Standard (Name, Domain, Website, Phone, Email, City, Country, Owner) and Custom fields. Standard fields are real rows — they can be reordered and hidden, never deleted or retyped. A rep who opens the sheet looking for "Domain" finds it and learns the rule in the same second, which is cheaper than any explanation of why it is missing.
Custom fields then render inline in DETAILS, in the order set here. No "Custom fields" box. A field is a field; the grouping was an implementation detail and does not belong on the record.
3. The model
enum FieldEntity { COMPANY CONTACT DEAL }
enum FieldType {
TEXT LONG_TEXT NUMBER DATE CHECKBOX SELECT URL EMAIL PHONE USER
}
model FieldDefinition {
id String @id @default(cuid())
entity FieldEntity
key String
label String
type FieldType
agentFilled Boolean @default(true)
agentBrief String?
required Boolean @default(false)
showOnSheet Boolean @default(true)
showOnTable Boolean @default(false)
position Int
archivedAt DateTime?
options FieldOption[]
values FieldValue[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@unique([entity, key])
@@index([entity, position])
@@map("fieldDefinition")
}
model FieldOption {
id String @id @default(cuid())
fieldId String
field FieldDefinition @relation(fields: [fieldId], references: [id], onDelete: Cascade)
label String
position Int
archivedAt DateTime?
values FieldValue[]
@@index([fieldId, position])
@@map("fieldOption")
}
model FieldValue {
id String @id @default(cuid())
fieldId String
field FieldDefinition @relation(fields: [fieldId], references: [id], onDelete: Cascade)
companyId String?
company Company? @relation(fields: [companyId], references: [id], onDelete: Cascade)
contactId String?
contact Contact? @relation(fields: [contactId], references: [id], onDelete: Cascade)
dealId String?
deal Deal? @relation(fields: [dealId], references: [id], onDelete: Cascade)
text String?
number Decimal? @db.Decimal(24, 4)
date DateTime?
bool Boolean?
optionId String?
option FieldOption? @relation(fields: [optionId], references: [id], onDelete: SetNull)
userId String?
user User? @relation("FieldValueUser", fields: [userId], references: [id], onDelete: SetNull)
updatedAt DateTime @updatedAt
@@unique([fieldId, companyId])
@@unique([fieldId, contactId])
@@unique([fieldId, dealId])
@@index([fieldId, text])
@@index([fieldId, number])
@@index([fieldId, date])
@@index([companyId])
@@index([contactId])
@@index([dealId])
@@index([optionId])
@@index([userId])
@@map("fieldValue")
}
User carries the other half of that relation:
fieldValues FieldValue[] @relation("FieldValueUser")
Six decisions worth defending:
- Typed columns, not a
Jsonvalue.api.mdsays filter, sort and paginate in Prisma. A JSON blob cannot be indexed or ordered honestly, and the moment someone wants the pipeline sorted by Renewal date the answer would be to pull the table into the browser. One column per storage class keeps that promise; the type on the definition says which one is live. - One value table with three nullable FKs, not three tables. Every FK
cascades, so deleting a company takes its values with it.
AgentTaskcarriescontactId/companyIdwith no FK andapi.mddocuments the chore that creates — "clearAgentTaskandAgentEventyourself". Not repeating it. - Options are rows. Renaming "Google Cloud" must not orphan every record pointing at it, and a JSON array of strings makes rename indistinguishable from delete-plus-create.
keyis immutable,labelis not. The key is what the API and the agents say; the label is what the rep reads. Renaming the label of a field an agent has filled for a month cannot break the brief that taught it.- The record columns are indexed on their own, not only inside the uniques.
A record read is
where: { companyId }with nofieldId—FieldsService.valuesForopens every sheet that way — and a unique startingfieldIdcannot serve it. The composite uniques stay for the one-value-per- field-per-record rule; the standalone indexes are what the reads use. userIdis a foreign key, like every other id on the row. AUSERfield holds a workspace user, so a deleted rep must not leave an id on the record that resolves to nobody.SetNullmatchesCompany.ownerandContact.owner: the value empties, and it never blocks the delete.
Archive, not delete. A record delete is hard in this CRM by design, but a definition delete destroys a column of typed data across every record at once. Archiving keeps the values and hides the field everywhere; a true delete stays available behind a separate destructive confirm that names the count.
No organizationId, on any of the three. Single tenant.
4. The API
A new module, apps/api/src/fields/, one router as the codegen glob expects:
| Procedure | Notes |
|---|---|
fields.list({ entity, includeArchived }) |
Definitions with options, in position order. |
fields.create / fields.update |
Key derived from label on create, rejected on update. |
fields.reorder({ entity, ids }) |
One transaction, positions rewritten from the array. |
fields.archive / fields.restore / fields.delete |
Delete is the loud one. |
Values do not get their own router. They ride the record procedures that
already exist: companies.byId returns fields, companies.update accepts
fields: Record<key, value>. One write per record, one invalidation, and the
inline editors keep using the mutation they already use.
The value validator is derived from the definition at runtime — a shared
crm/fields.ts that both the router's zod schema and the service use, so a
NUMBER field cannot be written a string by either path.
useCrmCache() gains cache.fields(entity). A definition change is a schema
change: it fans out to every list and record query for that entity. Rare enough
that the width does not matter, and { settle: "record" } still covers the
inline value edits.
src/generated/server.ts is regenerated by dev/check-types and committed, or
the app cannot see any of this.
5. Agent-first, and what that costs
This was the open question, and the answer is agent-first: agentFilled
defaults to true. A new field is something your agents keep up to date unless
you say otherwise, and "Manual only" is the exception a rep opts into.
That is a real difference, not a default flipped for effect. It changes three things:
- Order in the editor. The brief — What counts as an answer — sits directly under the label, above the type. The second thing you write is the instruction, not the shape.
- What the list shows. Each row's subtitle is its brief, truncated. Agent upkeep is the unmarked normal case; only the exceptions read "Manual only". Nothing is badged for doing the expected thing.
- What an empty brief means. Not "never touched" — that was the old,
opt-in reading. Agents work from the label and the type alone; the brief
sharpens what would count. Opting out is
agentFilled: false, one switch.
Never "eve" in the product. UI copy says your agents. eve is the runtime
in apps/agent, an implementation detail a rep should never have to learn, and
a self-hoster may well point this at their own. The word appears in this
document and in the code; it does not appear on screen.
Nest still writes rows and fills nothing. Creating or editing a definition with
agentFilled writes one AgentTask (kind: "field-backfill", reason =
the key) — one row per field, not one per record. The agent leases it and decides
the fan-out, batching and priority itself, which is the point of the rule in
api.md and the reason a workspace with 5,000 companies does not get 5,000 rows
from one click.
agentBrief is the whole instruction, in the rep's words:
Which cloud they run production on. Their docs, status page or engineering job ads say it outright — infer nothing from a logo on a customer wall.
The self-hoster's answer is unchanged and still needs no special case: with no agent running, nothing leases the task, nothing proposes, and every field is one you type into. A missing capability removes a capability. It does not throw.
Proposed, not written — and this is what makes agent-first safe to default
on. A value an agent finds arrives the way a ContactFact arrives: PROPOSED,
with a score, a band and evidence, rendered by the Suggestion component that
already exists, accepted or dismissed by a human. A dotted underline
(SOURCED_VALUE) then marks what an agent put there, and hover gives the source.
Nothing a rep typed is ever overwritten.
Turning this on by default would be reckless if agents wrote straight into the field. They do not, so the cost of a wrong default is a suggestion someone dismisses — against a rep never discovering the feature at all, which is the cost of the opt-in version.
That behaviour is already built; the fork is that ContactFact is contact-only
and keys on field String.
Recommendation: generalise ContactFact to RecordFact with the same three
nullable FKs and an optional fieldId, rather than growing a parallel proposal
table for custom fields. It is the larger migration and the smaller system. This
is the one decision in this plan that should be made before any of it is built,
because it is the only one that gets more expensive later — and agent-first makes
it load-bearing rather than optional.
6. What the UI needs that does not exist
Everything in the design is already in packages/ui — Sheet, Input, Select,
Switch, Checkbox, Button, Suggestion, the Inline* editors — with one exception.
There is no drag-and-drop library in the repo. The design shows a drag handle on every row. Either:
- add
@dnd-kit/core+@dnd-kit/sortabletopackages/uiand build aSortableListthere, which is where a shared interaction belongs; or - ship reordering as Move up / Move down in the row's overflow menu, and add dragging later.
Option 2 is a smaller first cut and the ordering it produces is identical. Option 1 is what the artboards show. Worth deciding explicitly rather than by accident.
7. Deliberately out of scope
- Filtering and sorting the tables by a custom field. The columns exist
(
showOnTable), the indexes support it,resolveOrderBywould need to learn about field keys. Phase two. - Quick-add. New fields do not appear in quick-add unless
required. - Per-record fields. A field belongs to an entity, never to one company.
- Formula, rollup and relation types. Not in the first cut.