alla-allaos-fullstack/docs/adr/0011-lead-enquiry-ownership-model.md

ADR 0011: Lead and Enquiry Ownership Model

Status

Accepted

Context

The CRM module originally used a mixed terminology model where:

• Lead meant an unassigned enquiry
• Opportunity meant an assigned enquiry

That model no longer matched the business process. The business now distinguishes ownership by function:

• Lead is marketing-owned
• Enquiry is sales-owned

The system must preserve the single-source-of-truth table crm_enquiries while refining lifecycle, permissions, monitoring visibility, and KPI semantics.

Decision

1. Single record model

• crm_enquiries remains the single source of truth
• no crm_leads table is introduced
• no split lead form or split enquiry API is introduced

2. Pipeline stage model

crm_enquiries.pipeline_stage is the lifecycle discriminator with allowed values:

• lead
• enquiry
• closed_won
• closed_lost

3. Ownership model

• lead is marketing-owned
• enquiry is sales-owned
• assignment converts a lead into an enquiry

4. Assignment behavior

On assign:

• assignedToUserId is set
• assignedAt is set
• assignedBy is set
• pipelineStage becomes enquiry

On reassign:

• assignee metadata is updated
• pipelineStage remains enquiry

5. Create behavior

• marketing-created records default to pipelineStage = lead
• sales-created records default to pipelineStage = enquiry

6. Closure behavior

• lost or cancelled enquiry status resolves to pipelineStage = closed_lost
• accepted or lost/rejected quotation outcomes may synchronize the linked enquiry to:
  • closed_won
  • closed_lost

7. Visibility policy

Marketing can monitor:

• leads
• enquiries
• follow-ups
• status
• pipeline stage
• enquiry owner
• won/lost result

Marketing cannot access:

• quotation pricing
• quotation items
• cost, discount, or margin views
• approval analytics or approval workflow data

Sales scope remains ownership-based:

• sales and sales_support are limited server-side to enquiries they created or are assigned to
• managers and admins retain wider organization visibility

8. KPI terminology

User-facing dashboard terminology replaces Opportunity with Enquiry.

Count definitions:

• Lead Count = pipelineStage = lead
• Enquiry Count = pipelineStage = enquiry
• Won Count = pipelineStage = closed_won
• Lost Count = pipelineStage = closed_lost

9. Navigation Separation

• Lead and Enquiry are separate UX workspaces
• Lead and Enquiry are not separate domain entities
• both workspaces continue to use the same crm_enquiries records
• pipelineStage determines whether a record appears in the Leads or Enquiries workspace
• the navigation split reduces user confusion without duplicating schema, API, or service layers

Consequences

Positive

• matches the real business handoff from marketing to sales
• keeps backward-compatible storage in crm_enquiries
• removes ambiguous opportunity wording from user-facing CRM surfaces
• gives marketing monitoring visibility without exposing commercial data
• enforces own-or-assigned visibility server-side for sales roles

Tradeoffs

• lifecycle still depends partly on status mapping and quotation outcome synchronization
• the model does not yet include dedicated timestamps such as closedWonAt or closedLostAt
• reporting still relies on current-state lifecycle fields rather than effective-dated snapshots

Supersedes

This ADR supersedes the opportunity terminology frozen in docs/implementation/task-j0-kpi-definition-freeze.md for user-facing CRM ownership and KPI language.