Skip to content

armgit / crm

Public Imported from GitHub
0

Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.

TypeScript
23.3 KB
Raw Blame

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_BUY is 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 like CLOSED_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.email is unique. Matches HubSpot's own constraint and makes the CSV import idempotent. The cost: two people behind one info@ address need separate records with one email each.
  • Company.domain is 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.md does not exist but AGENTS.md says "Always review" it. Either write it or drop the reference — right now every agent starts by failing to read a required file.
  • docs/api.md describes 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.ts is 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:

  1. apps/app/app/api/[...path]/route.ts — a catch-all proxy (ported from mvp) so the browser calls /api/trpc same-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.
  2. apps/api exports its router type: "exports": { "./app-router": "./src/generated/server.ts" }, generated by nestjs-trpc generate. The app imports type { 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 = occurredAt set, or completedAt set, or a NOTE/STAGE_CHANGE/ENRICHMENT row (use createdAt).
  • Upcoming = dueAt > now() and completedAt IS NULL.
  • Overdue = dueAt < now() and completedAt IS NULL.
  • A company's timeline is WHERE companyId = ?, which picks up deal and contact activity for free because we stamp companyId on 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 stamps closedAt and prompts for closedReason on 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 → description
  • logos[] → pick by mode/type, never logos[0]: logoUrl = light+logo, logoDarkUrl = dark+logo, iconUrl = icon
  • colors[0].hex → brandColor (key off hex; the name is generated)
  • industries.eic[0] → industry / subIndustry
  • address → city, stateCode, country, countryCode
  • socials[] → linkedinUrl / twitterUrl / githubUrl by type
  • links → pricingUrl, careersUrl
  • email, 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, not FAILED (and not billed).
  • 422 on email lookup (free/disposable) → SKIPPED, no company created.
  • 403 FORBIDDEN on prefetch → log once, fall through to direct retrieve.
  • 408/429 → one backoff retry, then FAILED with enrichmentError.
  • 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

  • NuqsAdapter from nuqs/adapters/next/app wraps the root layout, alongside TRPCReactProvider.
  • Shared parsers live in a *-search-params.ts per module, importing from nuqs/server so 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.
  • clearOnDefault everywhere, 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 full DataTable; 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 generate script + exports["./app-router"]; add the watch task to dev.
  • apps/app/app/api/[...path]/route.ts proxy; lib/trpc/{server.ts,client.tsx,query-client.ts}.
  • NuqsAdapter + TRPCReactProvider in the root layout.
  • Port the data table into packages/ui.
  • Housekeeping: resolve docs/review.md, trim the org sections from docs/api.md, delete make-session.tmp.ts.
  • Verify: dashboard renders users.me through tRPC, server-prefetched.

Phase 1 — Schema and seed

  • The models in §3, one migration, User back-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

  • companies router + 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

  • contacts router; list DataTable (name, title, email, company, owner, last activity); detail page; company link; "make primary contact" action.
  • Replace the existing contacts/page.tsx placeholder.

Phase 4 — Deals

  • deals router; 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; activities router; 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 ENRICHMENT activity.
  • 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/prefetch warming before the retrieve pass, dry-run report first.
  • Deal board view (?view=board, stage columns, drag to change stage).
  • cmdk quick 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.