Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
CRM ownership
CRM company and contact screens, settings, filters, saved views, lists, import,
export, and company actions belong here. The dependency rules are enforced by
architecture.test.ts and the feature rules in rules/ast-grep.
crm/
core/ Domain types, permissions, stage resolution, CSV and view validation
context/ Explicit source/action contracts and scoped providers
queries/ CRM query factories, cache updates, transport decoding
primitives/ Reactive workflows: board, filters, stages, views, import, export
components/ Props-driven presentation and column definitions
views/ Screens composed from context, primitives, and components
tests/ Cross-layer CSV integration coverage
crm.tsx Company workspace composition
crm-company.tsx / crm-contact.tsx / crm-settings.tsx
crm-create.tsx / crm-link.tsx
crm-actions.ts / crm-hide-action.ts / crm-action-items.ts / crm-user-action.tsx
crm-search.ts / crm-tool-renderers.tsx
crm-route.ts Route params, record and item trails, and legacy pipeline link decoding
route-views.tsx Authenticated route and shared-view decoding
crm-hosted-content.ts Split content that opens Customers on a pipeline or record
*-adapter.* Production sources, navigation, persistence, download, collection wiring
App code imports explicit entry points at this directory's root. It must not
import views, primitives, queries, components, core, or context
directly. Avoid adding a catch-all barrel that obscures these entry points.
The root adapters construct production dependencies. context defines the
capabilities; it does not import their implementations. Views consume these
capabilities, primitives receive narrow inputs, and components render props.
Core modules remain independent of Solid, service clients, and app state.
features/notifications/mark-row-seen.ts integrates with shared list activation so
opening a company or contact clears its row's unread notifications immediately.
It uses the row's attached notifications before falling back to an entity read;
the shared notification source owns optimistic state and failure rollback.
The REST fallback waits for the notification feed before reading its snapshot.
The discussion's message reader remains visibility-gated and reads a separate
global feed, so it cannot guarantee that opening a record clears its row's dot.
UI rollout gates read useFeatureFlag directly where used; do not pass rollout
booleans through component props or the CRM source contract.
Shared entity representations, transport clients, property editors, and
collection mechanics remain shared. CRM owns its record queries and cache updates.
Pipeline board positions load through the pipeline-authorized endpoint and are
cached by pipeline and view. Move results update the originating view's cache,
even if the viewer switches boards while saving. The adapter supplies the selected
view ID so switching boards also retires unfinished visual moves and sort prompts.
browser-test/board.tsx exercises shared cards, lane composition, and saved ordering with synthetic data.
Successful domain block and unblock mutations evict indexed company rows and contact suggestions from the GraphQL cache before refreshing CRM and Soup queries. Refresh mounted GraphQL lists that can contain CRM records too: the REST mutation returns no changed rows, and hidden records are absent from the search index. Failed mutations leave those cached records intact. Company selection snapshots and deduplicates the company's domains, waits for every domain request, and retains failed domains for retry after the company disappears from suggestions. Keep successful blocks when another domain fails. CRM supplies row/header/empty state slots, filter choices, grouping policy, and its own collection state to the shared collection renderer. Shared collection code must not acquire CRM hooks or CRM-specific state again.
Visible contact and company toolbars put the archive-system icon beside Copy link.
Archived identities group one Archived chip with a flat secondary Restore button;
on phones the group wraps beneath the name. Keep identity actions and metadata at
the compact property scale: 24px visible height, 12px text and 12px icons.
Interactive controls reserve 10px above and below their touch faces for separate
44px targets; transparent extensions receive those taps without enlarging the paint.
Use flat controls here because the glass finish owns its own press pseudo-elements.
Top-toolbar controls retain their separate navigation scale.
The chip owns hover/focus/tap explanation; Restore does not trigger that explanation.
RecordVisibilityAction handles confirmation, pending, cancellation and retry.
Only admins/owners can change visibility. Company archive cascades to all people
and disables email syncing; company restore explicitly confirms restoring every
person, including individually archived people, while email syncing stays off.
A person under an archived company routes to that company before restoration.
Both information panels start with Record details and References; company-only
Properties, Lists and Email sharing follow, with no duplicate visibility toggle.
People, Companies and company Team use an exclusive Visible/Archived filter.
people-visibility keeps the workspace choice local to the account/team/role/view,
preserves search and other display choices, and sanitizes shared/persisted contact
filters. Archived People is current-administered-team scoped, server filtered
before pagination; visible People remains viewer-wide. Team applies the same
exclusive choice to its embedded contact response, including effective parent state.
Successful REST mutations write confirmed flags through the normalized Soup update path and patch paginated suggestions, company search pages, REST Soup and embedded detail snapshots. Confirmed detail snapshots become stale without an immediate refetch; active initial reads that were cancelled are restarted. Pre-write REST reads are cancelled; the normalized exchange fences older responses containing or declaring the affected CRM types before publication, hydration or persistence. Flat and grouped Soup pages retain their initial filter dependencies on continuations, so old empty pages cannot briefly hide a restored record. Imperative and durable revalidations recover these dependencies at dispatch, before urql can share them with a later mounted reader. Unknown opaque continuation scopes conservatively fence both CRM types; known initial scopes retain explicit exclusions. Refreshes target CRM-capable readers, leaving unrelated lists alone. A refresh failure is logged separately and never misreports a committed save as rejected. Session identity is captured before dispatch so a late response cannot populate a replacement session. Ordinary Cmd-K continues to exclude archived companies and people through its existing feeds and normalized projections; it has no recovery UI.
browser-test/archive uses production record headers, toolbar actions, tabs,
SidePanel, Team filtering and confirmations with synthetic storage and isolated
shell services/entity-row metadata. It does not verify authenticated persistence.
browser-test/people additionally exercises the production AST compiler and live
GraphQL page source. Exchange tests cover the normalized-cache race boundary.
Run the fixture's playwright.config.ts from apps/web.
Both hidden mutations emit crm.visibility_change through request and cache
refresh completion, with the opaque record ID, record type, requested hidden
state, and outcome. crm.visibility_change.refresh times cache invalidation and
the dependent query refreshes before the mutation stops being pending.
crm.people_visibility measures the display choice through the next paint;
Soup retains its existing query/loading instrumentation.
task-composer.ts owns the CRM task preset: the records a new task starts
associated with. The Customer / Contact pill belongs to the shared task composer,
not this preset. CRM registers live { task: TaskComposerContext } values with the provider in
command/context/create-context.tsx, scoped to its pane. The app shell owns the
provider and supplies the layout's focus accessor; no global registry or manager
key is involved. The workspace registers the unassociated preset; nested record
getters override it and include already-loaded associations. Teardown restores
the parent getter. Omitted action entries inherit; task: null explicitly
suppresses a parent preset when CRM's rollout is disabled.
The selected-record fallback survives detail query errors until the record closes.
Global task creation snapshots the focused pane's getter before opening, without
fetching details or capturing navigation history. Record contexts isolate drafts.
enable-crm-activity gates workspace activity tabs (labelled Sales Tasks, Sales Email,
Sales Notes and Sales Calls), whether CRM supplies its
composer context, and, with enable-crm, the Customer / Contact pill in the task
composer and Universal Input's task mode. Those two read both flags through
customerContactEnabled. It defaults off everywhere and can be overridden locally with
VITE_ENABLE_CRM_ACTIVITY=true. Off hides activity navigation and skips activity
queries; saved activity links wait for flag loading, then fall back to Companies.
The standard record task action still associates the task with its record.
The registry and launcher never read this flag. With no supplied context, the
standard composer opens immediately. Each opening snapshots its
context; later flag, focus or record changes leave the open draft unchanged.
The Soup and email SQL optimizations are independent of this frontend gate.
The workspace activity feeds are CRM-linked, not unfiltered app shortcuts.
queries/activity.ts sends a constant-size crma: 'activity' association
selector. CRM resolves every visible company and contact on the server before
Soup filters and paginates the result; the browser does not prefetch the full
CRM or enumerate record IDs in filter trees. The scope excludes hidden records,
including for administrators, and keeps distinct contact IDs even when their
email addresses match. Tasks, Notes and Calls match Companies/Contacts property
links; Notes excludes task, snippet and skill Markdown subtypes. Email matches
visible company domains/contact addresses in the viewer's own mailbox, without
team-scope widening or requiring a property link on the email.
Customers has no Databases view or record section. A database that holds work
outside companies and contacts is a generic pipeline: recordType is null, the
primary column starts as an optional Name text column anyone can retype or delete
(the first column then titles rows), and rows are added directly in
the shared editor with no record picker or stage requirements. CSV import needs
a record to resolve, so it is hidden for generic pipelines; export includes Name.
Retired routes keep old links working: middleware sends a record's databases
section to the record, and a database opened under Customers to /database/<id>.
A saved databases workspace tab opens Companies.
CRM collection and record lists use full-height empty states, horizontally
centered and raised toward the toolbar, with
creation guidance, distinct search-empty actions, retryable error states, and
shared list skeletons with compact single-line rows, small icons, varied title
widths, and supporting metadata columns that hide in narrow panes. Keep search
and available header actions visible in every state. A failed continuation retains
rows and retries that page.
Workspace activity uses the shared single-row desktop header with New and an
expandable Search control; record-detail tabs retain their section toolbar.
Company and contact headers keep desktop section tabs; touch uses a labeled
header island that opens the shared bottom drawer with the current section
checked under Switch view. A collapsed host keeps the section icon and
accessible label; embedded phone headers put the switcher below the breadcrumb
and action row. Keep the
workspace's mobile view strip separate. Copy-link islands
are square on touch, with a 24px glyph and the standard 40px icon control.
On touch, record list search has space below the header and fills the row beside
any filter button. Email filters use the shared filter drawer. Each section's
creation action replaces the default floating action above the navigation dock
through FloatRegion; keyboard focus, higher-priority composers, and inactive
panes suppress it. Preserve record context, disabled states, and feature gates.
Keep the disabled New email action mounted when company email sync is off so
the unrelated app-wide action does not replace it.
Desktop creation controls remain in the toolbar.
Activity rows render stored Companies and Contacts reference properties as inline
pills through the shared Soup row. Pills use the shared property preview and open
a record independently of the row; additional values use the shared overflow menu.
Email still matches visible company domains and contact addresses for feed
membership, but the row displays only stored properties, not inferred matches.
No separate CRM association metadata lookup or row footer runs during paging.
Linked Tasks, Email, Notes and Calls open through nested Customers
routes from workspace activity and record sections. Tasks, Emails and Calls
record sections append only <item-id> because their section determines
the renderer; Tasks also omit the redundant md/task suffix. These sections reject
redundant typed item URLs rather than retaining fallback routes. Workspace activity
retains <item-type>/<item-id> and document metadata; record Files and overview
notes use document-metadata routes restricted to those sections. The route stores
the item name and record trail in entry state. Route params retain the record and
section; pane search retains the workspace tab. route-adapter.ts owns item
navigation and close/history restoration. Keep workspace/pipeline item variants
in its shared route-family table and identify history entries through merged route
params instead of enumerating item route IDs.
views/item-detail.tsx renders authorized details in the existing CRM shell
with source, record trail and item breadcrumbs, omitting section labels such as
Tasks and Files. The current record breadcrumb returns to the captured section
and entry state. Preview headers append their own live title and menu after the
source trail without an extra separator; do not duplicate the selected title in
the prefix. Modified clicks keep their existing split behavior.
Standalone record previews retain their normal navigation outside the workspace.
Record-detail lists and activity membership remain unchanged.
Sales Tasks reuse the production Tasks filters, sort, grouping, and list/board/Gantt
layouts (subject to the normal feature flags and touch fallback). They use a separate
CRM persistence scope, and every query, including search and grouped continuation,
retains the mandatory CRM association. Record-detail Tasks stay unchanged.
Sales Email reuses the shared read/done/attachment/calendar/tag facets. Sales Notes expose
creator and tag filters; Sales Calls expose audience and tag filters. These lists have independent
per-entry search, sort direction, and date/none grouping settings. Date headings follow
the selected sort field in viewer-local time. Sales Email defaults to last-update date groups;
Sales Notes and Sales Calls default to no grouping. Local-only filters continue paging through
empty pages; clearing filters never clears the CRM scope.
Activity extends the existing authorized CRM association path rather than splitting the feed into independent client queries. This preserves one sorted cursor and a complete scope without raising GraphQL's filter safety limits. SQL batching remains useful after resolution, but cannot fix oversized ingress filters. Deploy the backend association variant before the updated frontend.
When changing behavior, test the responsible primitive or pure function. When
moving behavior, retain query keys, persistence keys, mutation ordering, loading
boundaries, routes, and markup. Run CRM tests plus affected shared collection and
user-card tests, TypeScript checking, just check, and the real CRM browser flows.
Pipeline stage requirements are CRM policy over the shared database editor.
Remove a required field's rules before deleting its options, since option
deletion clears values even on rows outside the submitted operation batch.
queries/stage-requirements.ts adapts the pipeline-authorized rules; the toolbar
opens the shared-control dialog, and Add deal derives its required fields from
stable option/column IDs. Keep drafts on a refused save. The server is authoritative
for table, board, timeline, agent and import writes. Board and timeline creation
use the host composer so stage and date-range defaults reach Add deal. CSV writes split refused batches,
commit valid entries, and show record-specific failures; option labels enter the
local cache only after their batch commits. The backend-free regression is
bunx playwright test --config src/features/crm/browser-test/playwright.config.ts stage-requirements.browser.e2e.ts.