CRM Module

Last updatedCRM0.18.7

Source file

docs/modules/crm.md

The CRM module extends the platform with CRM contact data, status tracking, and funnel reporting. It depends on the Organizations module for shared organization, membership, and invitation data.

CRM builds on top of the Core + Admin + Organizations baseline; selecting CRM auto-includes Organizations.

Use Base Contract for the support-tier rules and base-contract.json for the canonical symbol inventory.

What schema it installs

  • Baseline tables: crm_contacts and crm_status_log
  • Organization integration: invitation acceptance linkage and primary-contact membership synchronization after Organizations is installed
  • Multi-organization compatibility: crm_contact_organizations records every contact-to-organization relationship while crm_contacts.organization_id remains the primary organization projection for existing consumers

What package and domain logic it provides

ConcernCurrent behavior
CRM package@brightweblabs/module-crm exports server/data contracts; @brightweblabs/module-crm/ui exports the default CRM screen and its focused surfaces.
Server helpersThe package exports reusable CRM read helpers, profile-to-contact synchronization, the complete getCrmReportData() aggregate, contact create/update/delete operations, SQL-backed single and bulk status transitions, plus the starter getCrmDashboardData() helper.
Route handlersThe package exports package-owned CRM reads and report handlers plus staff-only POST, PATCH, and DELETE handlers for contacts.
Route pages@brightweblabs/module-crm/routes exports authenticated dashboard, organization list/detail, and report server components for thin app routes.
Shared dependenciesThe package depends on @brightweblabs/module-orgs and also reads shared platform tables such as profiles and user_role_assignments.

Whether it adds starter routes and wiring

ConcernCurrent behavior
Scaffold wiringSelecting CRM adds the package dependency and enables CRM-related shell/config wiring in generated platform apps.
Starter routesThe module template contributes ready-to-use /crm and /crm/report routes and mounts /api/crm/contacts (GET, POST, PATCH, DELETE), /api/crm/organizations, /api/crm/stats, /api/crm/owners, /api/crm/timeline, and /api/crm/report.
Shell behaviorThe module registration adds CRM navigation groups and toolbar route definitions.
Dependency behaviorCRM resolves on top of Core + Admin + Organizations; orgs is enabled with hidden shell placement.

The CRM module ships the full dashboard and operational report experience. Product-specific UI can customize or replace either surface without copying package code.

Supported base contract

The current CRM contract is intentionally small:

Stable

  • @brightweblabs/module-crm/registration: crmModuleRegistration
  • @brightweblabs/module-crm: listCrmContacts()
  • @brightweblabs/module-crm: listCrmOrganizations() (deprecated alias of the Organizations module listOrganizations helper)
  • @brightweblabs/module-crm: getCrmContactStatusStats()
  • @brightweblabs/module-crm: listCrmOwnerOptions()
  • @brightweblabs/module-crm: listCrmPrimaryContacts()
  • @brightweblabs/module-crm: listCrmStatusTimeline()
  • @brightweblabs/module-crm: handleCrmContactsGetRequest()
  • @brightweblabs/module-crm: handleCrmOrganizationsGetRequest()
  • @brightweblabs/module-crm: handleCrmStatsGetRequest()
  • @brightweblabs/module-crm: handleCrmOwnersGetRequest()
  • @brightweblabs/module-crm/server: createCrmContact()
  • @brightweblabs/module-crm/server: updateCrmContact()
  • @brightweblabs/module-crm/server: setCrmContactStatus()
  • @brightweblabs/module-crm/server: bulkSetCrmContactStatus()
  • @brightweblabs/module-crm/server: deleteCrmContact()
  • @brightweblabs/module-crm/server: ensureCrmContactForProfile()
  • @brightweblabs/module-crm: handleCrmContactsPostRequest()
  • @brightweblabs/module-crm: handleCrmContactsPatchRequest()
  • @brightweblabs/module-crm: handleCrmOrganizationsPostRequest(), handleCrmOrganizationPatchRequest(), and handleCrmOrganizationInvitationsPostRequest()

Starter

  • @brightweblabs/module-crm: getCrmDashboardData()
  • @brightweblabs/module-crm: getCrmReportData(), handleCrmReportGetRequest(), and handleCrmContactsDeleteRequest()
  • @brightweblabs/module-crm/ui: CrmDashboard, CrmReport, CrmReportPage, organization/timeline browsers, dialogs, Portuguese dictionary, stage metadata, and default client
  • @brightweblabs/module-crm/routes: CrmDashboardRoutePage, CrmOrganizationsRoutePage, CrmOrganizationRoutePage, and CrmReportRoutePage

The dashboard helper and default UI are marked starter: they are supported fast-start surfaces, but their composition may evolve before becoming stable. The smaller server helper and request-handler contracts remain stable.

Default UI

A generated app with --modules crm can mount a complete screen with no app-owned CRM components:

TSX
import { CrmDashboard } from "@brightweblabs/module-crm/ui";

export default function CrmPage() {
  return <CrmDashboard />;
}

The scaffold imports @brightweblabs/theme/css globally and @brightweblabs/module-crm/tokens.css from the CRM route layout. The default createCrmUiClient() calls the scaffolded routes under /api/crm; pass a different base path or fetch implementation when needed.

Customization points

  1. Locale dictionary. Every CRM-owned string comes from CrmUiDictionary. Portuguese (pt-PT) is the shipped default; copy the dictionary and replace values for another locale:

    TSX
    import { CrmDashboard, defaultCrmUiDictionary } from "@brightweblabs/module-crm/ui";
    
    const dictionary = {
      ...defaultCrmUiDictionary,
      dashboard: { ...defaultCrmUiDictionary.dashboard, title: "Pipeline" },
    };
    
    <CrmDashboard dictionary={dictionary} />;
    
  2. Column config. Reorder, hide, relabel, or render a built-in column through CrmTableColumnConfig[]:

    TSX
    <CrmDashboard columns={[
      { key: "name", label: "Contacto" },
      { key: "status" },
      { key: "owner", hidden: true },
      { key: "organization", render: (contact) => contact.organizations?.name ?? "–" },
    ]} />
    
  3. Slots. Add content around stats/table/sidebar, override the report banner, render row actions, or insert content between report sections without forking either page:

    TSX
    <CrmDashboard slots={{
      aboveTable: <CampaignFilter />,
      besideStats: <RevenueForecast />,
      sidebarTop: <TerritorySummary />,
      rowActions: (contact) => <ContactMenu contactId={contact.id} />,
    }} />
    
    <CrmReport data={data} slots={{
      afterHero: <ForecastNotice />,
      beforeDistributions: <RevenueBreakdown />,
    }} />
    
  4. Status metadata. Pass CrmStageConfig[] to control stage order, labels, and token names. The default is the canonical lead, qualified, proposal, won, and lost sequence.

    TSX
    <CrmDashboard stages={[
      { value: "lead", label: "Entrada", token: "--crm-stage-lead" },
      { value: "won", label: "Cliente", token: "--crm-stage-won" },
    ]} />
    
  5. Theming. Change --crm-stage-* and --crm-stage-*-strong aliases in a theme file. Components expose no color props; the shipped aliases map only to BrightWeb --semantic-* tokens.

  6. Organization fields. Configure industry, size, budget, website, address, and the optional tax identifier through organizationFields. Tax identifier display is off by default.

  7. Optional navigation. Override reportHref through navigation; provide marketingHref only when the host app has a marketing route. Marketing is absent by default.

The individual table, stats, dialogs, organization browser, timeline browser, timeline, and report exports accept data and callbacks, so they can be composed independently and rendered in tests without a network.

The generic controller layer is also exported: useCrmDashboardController, useCrmDataSync, useCrmDerivedState, useCrmContactActions, useCrmOrganizationActions, useCrmBulkActions, useCrmMutations, and useCrmWindowEvents. Use these when replacing a whole surface while retaining the package's state, selection, mutation, and host-event conventions.

How to use it in an app

The current CRM package is primarily a server/data helper plus shell registration package.

Load CRM data in a server page

TSX
export const dynamic = "force-dynamic";

export default async function CrmPage() {
  const { getCrmDashboardData } = await import("@brightweblabs/module-crm");
  const data = await getCrmDashboardData();

  return <pre>{JSON.stringify(data.stats, null, 2)}</pre>;
}

Use getCrmDashboardData() when you want the package to load and normalize the starter CRM dataset for a page or dashboard.

Treat this helper as starter page glue. It is the fastest way to prove the CRM module is wired, not the long-term reusable CRM contract.

Build on the stable CRM helpers

TS
import {
  getCrmContactStatusStats,
  listCrmContacts,
  listCrmOrganizations,
  listCrmStatusTimeline,
} from "@brightweblabs/module-crm";

const [contacts, organizations, stats, timeline] = await Promise.all([
  listCrmContacts(supabase, { page: 1, pageSize: 50 }),
  listCrmOrganizations(supabase, { page: 1, pageSize: 20 }),
  getCrmContactStatusStats(supabase),
  listCrmStatusTimeline(supabase),
]);

Use these helpers when you want reusable CRM primitives that an app or AI agent can compose into its own tables, dashboards, filters, and ownership flows.

Keep authentication at the page or route boundary, then pass the authenticated server Supabase client into the helpers you need. This lets larger apps progressively load sections and avoid dashboard-only overfetch. For example, an initial contacts page can load listCrmContacts(), listCrmOrganizations(), getCrmContactStatusStats(), and listCrmStatusTimeline() without also loading listCrmOwnerOptions() or listCrmPrimaryContacts(). Apps with custom ownership or role rules can replace listCrmOwnerOptions() with app-owned logic while still using the other CRM helpers.

getCrmDashboardData() remains backward-compatible and now composes these helpers internally. Treat it as starter page glue for generated apps, not as the only supported CRM loading shape.

Link profiles and organizations to CRM contacts

ensureCrmContactForProfile() is the server-only bridge used by organization access flows. It finds or creates the CRM contact for a profile, refuses to take over a contact already linked to another profile, and optionally links an additional organization through the service-role-only link_crm_contact_organization database function.

The crm_contact_organizations table is additive. crm_contacts.organization_id remains the primary relationship and existing contact reads continue to join it explicitly through crm_contacts_organization_id_fkey. Additional organization memberships do not silently replace that primary organization.

TS
import { ensureCrmContactForProfile } from "@brightweblabs/module-crm/server";

const result = await ensureCrmContactForProfile(profileId, {
  source: "organization_invitation",
  organizationId,
  serviceClient,
});

Treat a success: false result as an incomplete access workflow. Organization invitation handlers use this outcome to report or roll back the associated membership operation where possible.

Mount package-owned CRM pages

Thin app routes can re-export authenticated package pages:

TSX
export { CrmDashboardRoutePage as default } from "@brightweblabs/module-crm/routes";

The route components enforce admin or staff access and render the package-owned dashboard, organization list/detail, or report surface.

Write contacts and funnel status

Import write operations from the server-only subpath and pass the authenticated Supabase client obtained at the route or page boundary:

TS
import {
  bulkSetCrmContactStatus,
  createCrmContact,
  setCrmContactStatus,
  updateCrmContact,
} from "@brightweblabs/module-crm/server";

const contact = await createCrmContact(supabase, {
  firstName: "Ada",
  lastName: "Lovelace",
  email: "ada@example.com",
  organizationId: organizationId,
  ownerId: profileId,
});

await updateCrmContact(supabase, contact.id, { phone: "+351910000000" });
await setCrmContactStatus(supabase, contact.id, "qualified", "Discovery completed");
await bulkSetCrmContactStatus(supabase, selectedIds, "proposal");

setCrmContactStatus() and bulkSetCrmContactStatus() always call the set_crm_status database function. That function owns the contact update and crm_status_log insert, including unchanged-status no-op behavior. deleteCrmContact() is also available because deletion is part of the reference CRM write path.

The module manifest declares the crm.contact.status_changed payload contract at schemas/events/contact-status-changed.v1.json. Version 0.5 guarantees SQL status-history writes and the contract only; runtime event dispatch is intentionally deferred.

Mount the CRM request handlers

TS
export const dynamic = "force-dynamic";

export async function GET(request: Request) {
  const { handleCrmContactsGetRequest } = await import("@brightweblabs/module-crm");
  return handleCrmContactsGetRequest(request);
}

export async function POST(request: Request) {
  const { handleCrmContactsPostRequest } = await import("@brightweblabs/module-crm");
  return handleCrmContactsPostRequest(request);
}

export async function PATCH(request: Request) {
  const { handleCrmContactsPatchRequest } = await import("@brightweblabs/module-crm");
  return handleCrmContactsPatchRequest(request);
}

The current starter mounts the contacts write handlers and the read endpoints:

  • /api/crm/contacts
  • /api/crm/organizations
  • /api/crm/stats
  • /api/crm/owners
  • /api/crm/timeline
  • /api/crm/report

Register CRM in the app shell

TS
import { crmModuleRegistration } from "@brightweblabs/module-crm/registration";

Wire that registration into your app shell when you want CRM navigation groups and CRM toolbar route behavior.

Build beyond the default UI

Use the package-owned screen until a product needs a materially different workflow. At that point, compose a new package-owned surface on the stable data and write helpers while retaining the default route handlers.

How To Build On This

  • Start with CrmDashboard and CrmReportPage for the complete CRM experience, then use their customization points before forking UI.
  • Build on the stable CRM read and write helpers for contacts, stats, funnel transitions, and owner options; use @brightweblabs/module-orgs for organization data.
  • Build on the stable CRM shell registration when you want shared CRM navigation and toolbar wiring.
  • Use getCrmDashboardData() when you want the current scaffolded CRM page payload quickly.
  • Replace or wrap the starter helper once the client app needs different CRM slices, workflows, or page composition.
  • Do not treat the current starter dashboard payload as the final CRM contract for every project.

For a broader integration overview, see Using BrightWeb Modules.

Related docs

Implementation references

  • supabase/modules/crm/migrations
  • packages/module-crm/src/index.ts
  • packages/module-crm/src/data.ts
  • packages/module-crm/src/handlers.ts
  • packages/module-crm/src/server.ts
  • packages/module-crm/src/registration.ts
  • packages/create-bw-app/template/modules/crm
  • supabase/module-registry.json