alla-allaos-fullstack/docs/adr/0015-customer-ownership-contact-sharing.md

ADR 0015: Customer Ownership and Contact Sharing

Status

Accepted

Context

The CRM customer domain already supported customer masters, contacts, leads/enquiries, and quotations, but it still lacked two production behaviors:

• a first-class primary owner for each customer
• a persistent sharing model for customer contacts

That gap caused two operational problems:

• Marketing could not reliably suggest the right sales owner when creating a lead.
• Contact visibility depended on creator/admin fallbacks instead of explicit business governance.

Decision

We introduce two persistent governance models.

1. Customer owner

crm_customers now stores:

• owner_user_id
• owner_assigned_at
• owner_assigned_by

Ownership changes are recorded in crm_customer_owner_history.

Rules:

• one primary owner at a time
• owner is organization-scoped
• owner changes are auditable
• customer owner gains visibility to the customer and related CRM work, subject to CRM scope rules

2. Contact sharing

crm_contact_shares becomes the production source of truth for persistent contact sharing.

Rules:

• creator keeps access
• explicitly shared users gain access
• customer owner gains access
• CRM admin and broader organization/team scopes keep access
• removing a share revokes access by deactivating the share row

3. Lead assignment suggestion

Lead/enquiry creation now accepts an optional assignee suggestion.

When a selected customer has an owner:

• the form pre-selects that owner as the suggested sales owner
• users may override before submit
• the create route records whether the suggestion was used or overridden

Consequences

Positive:

• customer responsibility is now explicit and historical
• contact access is governed by durable business state instead of demo-only behavior
• lead routing is more accurate at creation time

Tradeoffs:

• visibility logic across customer/contact/enquiry flows becomes more stateful
• team-scope remains approximate until a first-class team graph exists

Notes

• This ADR does not introduce multiple primary owners, temporary shares, or territory management.
• Customer owner does not imply approval authority.