Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
Plan — Agentic CRM (HubSpot replacement)
A lightweight, opinionated CRM for our sales team. Companies are the top-level object; Contacts and Deals hang off them; everything that happens is an Activity on a timeline. Company knowledge (logo, description, industry, socials, address) is filled in by an agent using Context.dev rather than typed by a human.
This document is the build plan: decisions, data model, contracts, and phased
delivery. Read it with AGENTS.md, design.md
and api.md.
1. Decisions up front
| Decision | Choice | Why |
|---|---|---|
| Tenancy | Single tenant, no organizations | The repo is already built this way (20260731160000_remove_organizations). It's an internal tool; Google sign-in is the only door. |
| Data fetching | tRPC (nestjs-trpc) end to end | Type-safe from Prisma to the table cell, and the pattern is proven in /Users/lewiscarhart/mvp. |
| Table state | nuqs, server-side pagination/sort/filter | URLs are shareable and survive reload; the API does the work so 10k rows stay fast. |
| Data table | Port mvp's DataTable into packages/ui |
design.md makes /packages/ui the single source of truth; simple-table and card-table already live there. Same code as mvp, different address. |
| Enrichment | Context.dev, fire-and-forget on write, cached in Postgres | 10 credits per company; we never pay twice for the same domain. |
| Activity model | One Activity table, denormalised companyId |
A company timeline must show its deals' and contacts' events. One indexed query beats three joins. |
| Deal owner | Deal.ownerId → User, required |
Every deal has a name against it. Companies and contacts have optional owners. |
Judgment calls worth your veto
UNQUALIFIED_TO_BUYis terminal, not linear. You listed it between "qualified to buy" and "decision maker bought-in", but it's a disqualification, not a step forward. Plan treats it likeCLOSED_LOST: excluded from pipeline value and forecast, shown in a "Closed" tab rather than the open pipeline. Say the word if you want it mid-funnel instead.Contact.emailis unique. Matches HubSpot's own constraint and makes the CSV import idempotent. The cost: two people behind oneinfo@address need separate records with one email each.Company.domainis the enrichment key and is unique. Two records for the same domain is the #1 way a CRM rots, so we block it at the database.
Repo inconsistencies found while surveying
docs/review.mddoes not exist butAGENTS.mdsays "Always review" it. Either write it or drop the reference — right now every agent starts by failing to read a required file.docs/api.mddescribes a multi-tenant world this repo doesn't have. The org-context (x-organization-slug,OrgContextInterceptor) and per-org cache generation sections were carried over from the MVP; there are no organizations here. The logging rules apply verbatim and should stay. Recommend trimming api.md to logging + a short "no orgs, no org cache keys" note in Phase 0.apps/app/make-session.tmp.tsis a stray scratch file, safe to delete.
2. Architecture
browser
│ same-origin /api/trpc (cookies just work)
▼
apps/app (Next.js 16, RSC)
├─ app/api/[...path]/route.ts ──proxy──▶ apps/api:3001
├─ server components: prefetch via getServerTrpc() → HydrationBoundary
└─ client components: useTRPC() + TanStack Query, nuqs for table state
│
apps/api (NestJS on Bun, port 3001) ▼
├─ /api/trpc nestjs-trpc routers (companies, contacts, deals, activities, users)
├─ /api/auth/* Better Auth (Google only)
├─ services Prisma queries, timeline writes
└─ enrichment Context.dev client + queue ──▶ api.context.dev
│
packages/db (Prisma) ◀────────────────────────┘
Two things the CRM adds to the existing skeleton:
apps/app/app/api/[...path]/route.ts— a catch-all proxy (ported frommvp) so the browser calls/api/trpcsame-origin. Today the app sends the browser straight to:3001; that works for auth redirects but makes every tRPC call a cross-origin, credentialed request. The proxy removes that whole class of problem and streams SSE through untouched.apps/apiexports its router type:"exports": { "./app-router": "./src/generated/server.ts" }, generated bynestjs-trpc generate. The app importstype { AppRouter } from "api/app-router".
Dependencies to add
| Package | Where | Version (matching mvp) |
|---|---|---|
@trpc/server, zod |
apps/api |
^11.18.0, ^4.4.3 |
@trpc/client, @trpc/server, @trpc/tanstack-react-query |
apps/app |
^11.18.0 |
@tanstack/react-query, @tanstack/react-query-devtools |
apps/app |
^5.101.2 |
nuqs |
apps/app + packages/ui |
^2.8.9 |
zod |
apps/app |
^4.4.3 |
context.dev |
apps/api |
latest |
nestjs-trpc (^2.13.0) and @keyv/redis/cache-manager are already in
apps/api. Note nestjs-trpc ships a binary that may need the
postinstall chmod shim mvp uses — check on first install.
3. Data model
New models in packages/db/prisma/schema.prisma. Auth models are untouched.
enum DealStage {
DEMO_BOOKED
QUALIFIED_TO_BUY
UNQUALIFIED_TO_BUY // terminal — disqualified
DECISION_MAKER_BOUGHT_IN
CONTRACT_SENT
CLOSED_WON
CLOSED_LOST
}
enum ActivityType {
NOTE
CALL
EMAIL
MEETING
TASK
STAGE_CHANGE // written by the system on Deal.stage change
ENRICHMENT // written by the agent
}
enum EnrichmentStatus { PENDING RUNNING COMPLETE FAILED SKIPPED }
model Company {
id String @id @default(cuid())
name String
domain String? @unique // bare, normalised: "stripe.com"
website String?
description String?
// brand (Context.dev)
logoUrl String?
logoDarkUrl String?
iconUrl String? // square — used in table rows
brandColor String? // hex
// firmographics
industry String?
subIndustry String?
city String?
stateCode String?
country String?
countryCode String?
// contact + socials
phone String?
email String?
linkedinUrl String?
twitterUrl String?
githubUrl String?
pricingUrl String?
careersUrl String?
// ownership
ownerId String?
owner User? @relation("CompanyOwner", fields: [ownerId], references: [id], onDelete: SetNull)
primaryContactId String? @unique
primaryContact Contact? @relation("PrimaryContact", fields: [primaryContactId], references: [id], onDelete: SetNull)
// enrichment bookkeeping
enrichmentStatus EnrichmentStatus @default(PENDING)
enrichedAt DateTime?
enrichmentError String?
enrichment CompanyEnrichment?
contacts Contact[] @relation("CompanyContacts")
deals Deal[]
activities Activity[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([ownerId])
@@index([name])
@@map("company")
}
/// Raw Context.dev payload, kept so re-deriving fields costs nothing.
model CompanyEnrichment {
companyId String @id
company Company @relation(fields: [companyId], references: [id], onDelete: Cascade)
source String @default("context.dev")
raw Json
fetchedAt DateTime @default(now())
@@map("companyEnrichment")
}
model Contact {
id String @id @default(cuid())
firstName String
lastName String?
email String? @unique
phone String?
title String?
linkedinUrl String?
companyId String?
company Company? @relation("CompanyContacts", fields: [companyId], references: [id], onDelete: SetNull)
ownerId String?
owner User? @relation("ContactOwner", fields: [ownerId], references: [id], onDelete: SetNull)
primaryOf Company? @relation("PrimaryContact")
deals DealContact[]
activities Activity[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([companyId])
@@index([ownerId])
@@map("contact")
}
model Deal {
id String @id @default(cuid())
name String
companyId String
company Company @relation(fields: [companyId], references: [id], onDelete: Cascade)
ownerId String
owner User @relation("DealOwner", fields: [ownerId], references: [id])
stage DealStage @default(DEMO_BOOKED)
stageChangedAt DateTime @default(now())
amount Decimal? @db.Decimal(14, 2)
currency String @default("USD")
expectedCloseDate DateTime?
closedAt DateTime?
closedReason String?
contacts DealContact[]
activities Activity[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([companyId])
@@index([ownerId])
@@index([stage])
@@index([expectedCloseDate])
@@map("deal")
}
model DealContact {
dealId String
deal Deal @relation(fields: [dealId], references: [id], onDelete: Cascade)
contactId String
contact Contact @relation(fields: [contactId], references: [id], onDelete: Cascade)
role String?
@@id([dealId, contactId])
@@map("dealContact")
}
model Activity {
id String @id @default(cuid())
type ActivityType
subject String?
body String?
occurredAt DateTime? // logged in the past
dueAt DateTime? // scheduled for the future
completedAt DateTime?
/// Always stamped when resolvable, even for deal/contact activity, so a
/// company timeline is one indexed range scan.
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)
createdById String
createdBy User @relation("ActivityAuthor", fields: [createdById], references: [id])
meta Json? // { from, to } for STAGE_CHANGE, credit cost for ENRICHMENT
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([companyId, createdAt])
@@index([dealId, createdAt])
@@index([contactId, createdAt])
@@index([dueAt])
@@map("activity")
}
User gains the back-relations (CompanyOwner, ContactOwner, DealOwner,
ActivityAuthor). It is otherwise untouched — Better Auth owns that model and
bun run auth:generate regenerates it.
Timeline semantics
- Past =
occurredAtset, orcompletedAtset, or aNOTE/STAGE_CHANGE/ENRICHMENTrow (usecreatedAt). - Upcoming =
dueAt > now()andcompletedAt IS NULL. - Overdue =
dueAt < now()andcompletedAt IS NULL. - A company's timeline is
WHERE companyId = ?, which picks up deal and contact activity for free because we stampcompanyIdon write.
Pipeline math
- Open stages:
DEMO_BOOKED,QUALIFIED_TO_BUY,DECISION_MAKER_BOUGHT_IN,CONTRACT_SENT. - Closed stages:
CLOSED_WON,CLOSED_LOST,UNQUALIFIED_TO_BUY. - Pipeline value =
SUM(amount)over open stages. Setting a closed stage stampsclosedAtand prompts forclosedReasonon the two losing outcomes.
4. The agentic layer (Context.dev)
apps/api/src/enrichment/ — a ContextDevClient (thin typed wrapper over
https://api.context.dev/v1) plus an EnrichmentService that owns a small
in-process queue (concurrency 2, one retry with backoff, per-domain dedupe).
Trigger points
| Event | Call | Cost |
|---|---|---|
Company created/updated with a new domain |
POST /brand/retrieve {type:"by_domain"} |
10 credits |
| Manual "Re-enrich" button | same, maxAgeMs: 0 |
10 credits |
| Contact created with a work email and no company | POST /brand/retrieve {type:"by_email"} → find-or-create Company |
10 credits |
| CSV import (bulk) | POST /utility/prefetch per row, then retrieve |
prefetch free (paid plan) |
| "Research this company" action | POST /web/extract with our schema → ENRICHMENT activity |
10 credits |
Field mapping from the brand object:
title→name(only when the record was created domain-first and unnamed)description,slogan→descriptionlogos[]→ pick bymode/type, neverlogos[0]:logoUrl= light+logo,logoDarkUrl= dark+logo,iconUrl=iconcolors[0].hex→brandColor(key offhex; thenameis generated)industries.eic[0]→industry/subIndustryaddress→city,stateCode,country,countryCodesocials[]→linkedinUrl/twitterUrl/githubUrlbytypelinks→pricingUrl,careersUrlemail,phone→ same fields- Whole payload →
CompanyEnrichment.raw
Handling, per the Context.dev skill:
- Every field is nullable — never overwrite a human-entered value with
null. 400 NOT_FOUND/WEBSITE_ACCESS_ERROR→SKIPPED, notFAILED(and not billed).422on email lookup (free/disposable) →SKIPPED, no company created.403 FORBIDDENon prefetch → log once, fall through to direct retrieve.408/429→ one backoff retry, thenFAILEDwithenrichmentError.- Cold lookups are p50 ≈ 7s, p90 ≈ 18s. Always background; never block the
create mutation. Set
timeoutMS: 60000.
Research brief (POST /web/extract) uses a fixed JSON Schema —
{ positioning, pricingModel, targetCustomer, notableCustomers[], recentNews[] }
— and posts the result as an ENRICHMENT activity on the company timeline so a
rep sees it in context instead of in a side panel.
Config: CONTEXT_DEV_API_KEY in apps/api/.env, declared @IsOptional()
in env.validation.ts. Absent key ⇒ enrichment disabled, logged once at boot,
companies stay PENDING. The key never reaches the browser; all calls are
server-side.
Caching note: docs/api.md's org-scoped generation keys don't apply (no
orgs). tRPC responses aren't served by the HTTP response cache; freshness comes
from TanStack Query invalidation on mutation. Enrichment finishing is a
background write the client can't see, so the company detail page polls
(refetchInterval while enrichmentStatus is PENDING/RUNNING) and stops
when it settles.
5. tRPC contract
Every list endpoint speaks the same shape so one DataTable drives all three
modules.
// apps/api/src/trpc/list-input.ts
export const listInput = z.object({
q: z.string().default(""),
sort: z.string().default(""),
dir: z.enum(["asc", "desc"]).default("asc"),
page: z.number().int().min(1).default(1),
pageSize: z.number().int().min(1).max(100).default(25),
});
// → { rows: T[]; total: number; facetCounts: Record<string, Record<string, number>> }
| Router | Procedures |
|---|---|
users |
me, list (owner pickers) |
companies |
list (+ facets owner, industry, enrichment), byId, create, update, remove, setPrimaryContact, enrich |
contacts |
list (+ facets owner, company), byId, create, update, remove |
deals |
list (+ tab stage, facets owner, closing), board, byId, create, update, setStage, setContacts, remove |
activities |
timeline ({ companyId? contactId? dealId?, filter, cursor }), create, update, complete, remove, myTasks |
dashboard |
summary (pipeline by stage, closing this month, overdue tasks, recent activity) |
All routers carry @UseMiddlewares(AuthMiddleware) — ported from mvp minus the
org and permissions middleware, which have no meaning here. deals.setStage
writes the STAGE_CHANGE activity and stamps stageChangedAt/closedAt in the
same transaction.
Filtering, sorting and pagination happen in Prisma, not in the browser.
q searches name/domain/email with a case-insensitive contains; add a
pg_trgm index if the tables ever get big enough to notice.
6. Frontend
Routes
apps/app/app/(app)/
page.tsx dashboard
companies/page.tsx DataTable
companies/[companyId]/page.tsx detail + timeline
contacts/page.tsx DataTable (placeholder exists today)
contacts/[contactId]/page.tsx detail + timeline
deals/page.tsx DataTable (+ ?view=board)
deals/[dealId]/page.tsx detail + timeline
AppIconRail gains Companies and Deals entries alongside the existing Overview
(Dashboard) and Contacts (UserMultiple) — Carbon glyphs imported one at a
time through the Icon wrapper, per the README. Pick the glyph names off the
Carbon icon library and
confirm the file exists in @carbon/icons-react/es/ before importing; the
package isn't installed in this checkout yet, so the names are unverified.
The data table
Port these from /Users/lewiscarhart/mvp/apps/app/components/data-table/,
rewriting @trycompai/ui → @crm/ui:
| Source | Destination |
|---|---|
data-table.tsx (631 lines) |
packages/ui/src/components/data-table.tsx |
table-pagination.tsx, numbered-pagination.tsx |
packages/ui/src/components/ |
use-table-query.ts, build-search.ts |
apps/app/components/data-table/ |
Everything it depends on already exists in @crm/ui: table, dropdown-menu,
input-group, button, spinner, and lib/row-accent. The hook stays in the
app because it's routing state, not UI. nuqs becomes a dependency of
packages/ui (the table owns the expand and hide params).
Behaviour we're keeping verbatim: sticky header, table-fixed with truncating
cells, sort/columns/facet dropdowns, mobile filter collapse, expandable rows,
useDeferredValue so typing stays smooth, and the pagination footer.
nuqs conventions
NuqsAdapterfromnuqs/adapters/next/appwraps the root layout, alongsideTRPCReactProvider.- Shared parsers live in a
*-search-params.tsper module, importing fromnuqs/serverso the page and the client component agree. - Server components read them with
createLoader, and pass the parsed values into the tRPC prefetch so the first paint is already filtered. - The search box uses
limitUrlUpdates(nuqs' built-in debounce) rather than a hand-rolled timer. clearOnDefaulteverywhere, so a default view has a clean URL.- Table state stays shallow (default): TanStack Query refetches; we don't
round-trip the RSC on every keystroke. Detail sheets (
?company=,?deal=) are shallow too.
Server rendering
Each list page prefetches through getServerTrpc() + getServerQueryClient()
and wraps the client panel in <HydrationBoundary state={dehydrate(queryClient)}>
— the exact mvp pattern, minus the org slug.
Company detail page
The page that has to be good, because it's where reps live:
- Header — logo (
iconUrl, falling back to initials), name, domain link, industry badge, owner avatar, and an enrichment state chip that shows a spinner while the agent works. - Left column — properties card (inline-editable: name, domain, website, phone, address, owner), primary contact card, socials row.
- Right column — the timeline: composer at the top (Note · Call · Email ·
Meeting · Task), then Upcoming/Overdue pinned, then history grouped by day.
Filter tabs via nuqs (
?tab=all|notes|upcoming|done). - Below — Contacts table and Deals table, both
SimpleTable(not the fullDataTable; these are short embedded lists).
Per design.md: shared components only, no bespoke radii/spacing/colours, no
rounded corners. brandColor is used as a small accent swatch, never as a
surface — brand colours would fight the design tokens.
7. Phases
Each phase ends green on bun run check-types and bun run lint.
Phase 0 — Plumbing (no product surface)
- Add the dependencies in §2; wire
apps/api/src/trpc/(module, context,AuthMiddleware, error handler, logging middleware) from the mvp reference. nestjs-trpc generatescript +exports["./app-router"]; add the watch task todev.apps/app/app/api/[...path]/route.tsproxy;lib/trpc/{server.ts,client.tsx,query-client.ts}.NuqsAdapter+TRPCReactProviderin the root layout.- Port the data table into
packages/ui. - Housekeeping: resolve
docs/review.md, trim the org sections fromdocs/api.md, deletemake-session.tmp.ts. - Verify: dashboard renders
users.methrough tRPC, server-prefetched.
Phase 1 — Schema and seed
- The models in §3, one migration,
Userback-relations. - Extend
packages/db/prisma/seed.ts: ~15 companies (real domains so enrichment has something to chew on), ~40 contacts, ~25 deals spread across stages, ~150 activities including overdue and upcoming tasks. - Verify:
bun run db:migrate && bun run db:seed, inspect in Studio.
Phase 2 — Companies
companiesrouter + service; list page with DataTable — columns: logo+name, domain, industry, owner, contacts, open deals, last activity; facets owner / industry / enrichment status; search on name+domain.- Company detail page per §6, minus the timeline (Phase 5 stub).
- Create sheet: name + domain + owner, nothing else. The agent fills the rest.
- Verify: filter + sort + page, copy the URL into a new tab, same view.
Phase 3 — Contacts
contactsrouter; list DataTable (name, title, email, company, owner, last activity); detail page; company link; "make primary contact" action.- Replace the existing
contacts/page.tsxplaceholder.
Phase 4 — Deals
dealsrouter; list DataTable (name, company, stage badge, amount, owner, expected close, last activity); tab = open/closed/all, facets owner + stage.- Inline stage change from the row (dropdown) writing
STAGE_CHANGE. - Deal detail: stage stepper, amount/currency/close date, associated contacts, timeline slot.
- Verify: stage change appears on the deal and the company timeline.
Phase 5 — Activity, tasks and dashboard
- Timeline component + composer;
activitiesrouter; complete/snooze on tasks. - Dashboard: pipeline value by stage, deals closing this month, my overdue tasks, recent activity feed.
- Verify: a note on a deal shows on the company timeline; an overdue task shows on the dashboard.
Phase 6 — The agent
ContextDevClient,EnrichmentService, queue, field mapping, status polling.- Auto-enrich on company create; manual re-enrich; contact-email → company.
- Research brief action writing an
ENRICHMENTactivity. - Verify: create a company with domain
stripe.com→ logo, description, industry, socials and address populate within ~20s without a reload.
Phase 7 — Migration and polish
- HubSpot CSV import for companies/contacts/deals, dedupe on
domain/email,utility/prefetchwarming before the retrieve pass, dry-run report first. - Deal board view (
?view=board, stage columns, drag to change stage). cmdkquick switcher over companies/contacts/deals.
8. What this plan deliberately leaves out
Email sync, calendar sync, sequences/cadences, quotes, custom properties, multiple pipelines, reporting builder, and permissions/roles. Every one of them is a HubSpot feature we're choosing not to rebuild. If the sales team asks for one, it's a new plan, not a phase.