Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
crm
What it is
Part of CRM (Sales): a hexagonal crate for companies, contacts, and pipelines (including the legacy-CRM → Sales migration), plus the AI tools/HTTP/GraphQL surfaces over them.
Start here
src/domain/service.rs,src/domain/pipelines.rs: core use cases.src/domain/pipelines/requirements.rs: stage-entry rules keyed by column and option IDs.apply_opsvalidates every pipeline write under the pipeline write guard; agent/CSV workflows use the same service. Deletions cascade rules.src/domain/pipeline_workflows/: pipeline entry/field/record ops built on the shareddatabasesengine (Sales pipelines are adatabasesconsumer).src/domain/crm_csv.rs,src/domain/crm_transfer.rs: CSV import/export for agents (companies, pipeline entries, pipeline exports). Writes go through the pipeline workflows andCrmService; CSV files reach documents through theCsvFilesport, implemented inai_tools::crm_csv_files.src/inbound/axum_router.rs(+axum_router/*.rs): HTTP handlers.src/inbound/toolset.rs(+toolset/*.rs): AI tool definitions.src/outbound/companies_repo.rs: the Postgres adapter for companies/contacts.SALES_BACKFILL.md: how the legacy-CRM-to-Sales migration behaves.
Scope
- Owns: CRM company/contact records, pipelines, and their HTTP/AI-tool/search surfaces for a team.
- Not here: the contact graph (who a user knows) →
crates/contacts; shared database storage/positions →crates/databases.
Boundaries
- Cargo features gate what's pulled in:
lookupandsearchare read-only, sqlx-only slices for other domains to depend on without pulling inunfurl/axum; pick the narrowest feature for a new caller. - Depends on:
entity_access(ports-and-adapters base),databases(ports),filter_ast,item_filters,macro_authorization,properties. - Used by:
email,memory,ai_tools,soup/models_soup,graphql_crm,search_service,complete_graph; composition roots includedocument_storage_service,agent_harness_service,mcp_service,email_service,agent_trigger_service,scheduled_action.
Recipes
- Add an HTTP route:
src/domain/service.rs(or a domain submodule) →src/inbound/axum_router/<name>.rs→src/inbound/axum_router.rs(mount it). - Add an AI tool:
src/inbound/toolset/<name>.rs→src/inbound/toolset.rs(register it) → itstest.rs. - Change pipeline behavior:
src/domain/pipelines.rsorsrc/domain/pipeline_workflows/*.rs→src/outbound/pipelines.rs→ matching test undersrc/domain/pipeline_workflows/*/test.rs.
Checks
cargo test -p crm(SQLX_OFFLINEunset; needs a local MacroDB — see.agents/rules/rust/guardrails.md). After query/migration changes, runnix develop --command just prepare_dbfrom the repository root.- After tool input or description changes, regenerate frontend tool types and public MCP reference pages using the entity creation guide; CI checks both outputs.
Gotchas
A generic pipeline has
record_type: Noneand an unprotected primary column, which can change type or be deleted, leavingprimary_column_idnaming no column. Don't pass one toreferencing_rows: its SQL reads primary cells as reference arrays. Don't addON DELETEactions touching the pipeline row: they wait on the row lock the write guard holds, and the request hangs.Pipeline board-position reads require a pipeline View receipt, hold its live lifecycle guard, and scope the view to its backing table/database through
DatabaseStorage::storage_view_positions.src/domain/generic_email_domains.rsfilters both manual company creation and email-driven contact population. Cover legitimate company-domain exceptions with regression tests when correcting the blocklist.resolve_associationalso acceptsCrmAssociation::Activity: all records in CRM-enabled teams within the viewer/verified-bot scope, excluding hidden rows even for admins. Preserve distinct contact IDs that share an email; returned domains and addresses constrain the viewer's mailbox, not team email access.Manual companies require a name and accept an optional domain; explicit contact creation accepts any valid email, including personal providers. Email population still infers companies by domain. Do not apply manual creation rules to capture/consent; see
docs/design/crm-contact-creation.md.Keep CRM write locks ordered: domain advisory locks, parent team
KEY SHARE, settingsSHARE, then company/contact rows. Hold them through commit so disable/purge and team deletion cannot race creation.Bound pipeline read- and write-guard waits with a transaction-local five-second timeout so waiters release pool connections needed by the holder's storage work.
When depopulating an email, prefer its domain-linked contact over a manual unfiled record so mailbox-source teardown reaches the synced contact.
Serialize domain visibility updates on the owning company row before reading all its blocked domains; take no further domain locks after that row lock.
Keep ambiguous CSV contact lookups unresolved without creating records for them; continue valid rows, but propagate lookup storage and authorization failures.
Company names/logos live in the global
crm_domain_directory. Only the email pubsub workers carry a realCompanyMetadataResolver, using public homepage metadata throughunfurl; every other binary usesNoOpCompanyMetadataResolver, which leaves a pending entry (NULLenriched_at) thatCrmServiceImpl::enrich_pending_domainsresolves later with bounded retries. Never store an empty entry for a domain no resolver answered for: resolved entries are permanent.Apollo enrichment has been removed. Historical provider fields in the directory remain readable; do not clear existing metadata or drop columns as part of provider removal.
Contacts carry their own
team_id;company_idandemailare optional. Scope contact reads byct.team_idand LEFT JOIN the company for itshiddenflag and name. Email sync files personal-provider addresses (is_personal_email_domain) as company-less contacts only when the team turnsexclude_personal_emailsoff;crm_blocked_domainsstops sync per domain. CRM-scoped previews still require a company contact. Company-less contacts add no thread-access grant, but hidden ones suppress their team's CRM-derived grant for members; independent access grants still apply.The Sales migration (
SALES_BACKFILL.md) is forward-only and additive — its down migration refuses to erase completion or user edits; never revert it to undo a bad migration, only the application code that reads it.
Related
- Rules:
.agents/rules/rust/architecture.md,.agents/rules/rust/db.md· Skill:database-core