alla-allaos-fullstack/docs/adr/0018-lead-enquiry-domain-separation.md

ADR 0018: Lead / Enquiry Domain Separation

Status

Proposed

Context

ADR-0011 froze the current CRM lifecycle around a single persisted entity:

• crm_enquiries stores both marketing-owned leads and sales-owned enquiries
• pipeline_stage acts as the discriminator
• navigation separation exists, but domain separation does not

That model was an intentional stabilization step for Tasks D.3 and D.3.1. It reduced UX ambiguity without forcing a schema split during the first production rollout.

Task D.5 introduces a stronger business requirement:

• Marketing owns Lead as a dedicated entity
• Sales owns Enquiry as a dedicated entity
• one lead may create many enquiries
• sales may also create enquiries directly without a lead
• marketing outcome must be derived from sales execution, not manually controlled

The current single-record model now creates structural ambiguity in at least these areas:

1. Assignment currently mutates one record from lead -> enquiry, which destroys the original lead as a stable marketing record.
2. A true 1 Lead -> N Enquiries relationship cannot be represented cleanly while the lead itself is also the enquiry record.
3. Dashboard and report logic still infer lead analytics from crm_enquiries.pipeline_stage, which couples marketing and sales datasets.
4. Outcome synchronization for marketing is harder to reason about because the source marketing entity does not exist independently.

Decision

We will replace the single-record lead/enquiry persistence model with a split domain model:

• crm_leads becomes the dedicated marketing-owned lead table
• crm_enquiries remains the dedicated sales-owned enquiry table
• crm_enquiries.lead_id becomes nullable to support:
  • lead-origin enquiries
  • direct sales enquiries with lead_id = null

Lifecycle

The target business flow is:

Lead
-> Enquiry
-> Quotation
-> Won / Lost

Relationship rules

• crm_leads 1 -> N crm_enquiries
• crm_enquiries 1 -> N crm_quotations
• crm_quotations remains the owning record for quotation revisions and child resources

Ownership rules

• marketing owns lead creation and lead follow-up
• sales owns enquiry creation, enquiry follow-up, quotation generation, and won/lost execution
• managers and admins retain cross-workspace monitoring based on resolved CRM access

Outcome rules

• lead outcome is derived, never manually updated
• when any linked enquiry becomes won, the lead outcome becomes won
• when all linked enquiries are lost, the lead outcome becomes lost
• otherwise the lead outcome remains open

Sequence rules

• lead codes use a dedicated lead document sequence
• enquiry codes keep a separate enquiry document sequence

Reporting and dashboard rules

• lead KPI and lead reports read from crm_leads
• enquiry KPI and enquiry reports read from crm_enquiries
• no report should continue to treat pipeline_stage as the marketing/sales entity boundary after migration

Consequences

Positive

• aligns persistence with the real marketing-to-sales handoff
• supports true 1 Lead -> N Enquiries
• preserves lead identity after assignment
• simplifies marketing analytics and awareness-source reporting
• makes direct sales enquiries first-class without overloading lead semantics

Tradeoffs

• supersedes a previously accepted ADR and requires broad migration across services, reports, dashboard, and permissions
• requires data migration from existing crm_enquiries.pipeline_stage
• increases temporary compatibility complexity during rollout

Migration Strategy

The migration should be delivered in explicit phases:

1. Introduce ADR and governance freeze for split-domain direction.
2. Add schema and seed support for crm_leads, lead_id, and lead master options.
3. Introduce lead services and lead APIs without deleting enquiry flows.
4. Migrate dashboard and reports to separated datasets.
5. Remove old single-record assumptions from shared enquiry services and UI.

Supersedes

This ADR is intended to supersede the following sections of ADR-0011 once implemented:

• Single record model
• Pipeline stage model as the lead/enquiry persistence boundary
• Navigation Separation as the primary separation mechanism

Until implementation is complete, ADR-0011 remains the description of current production behavior, while this ADR defines the approved target direction for Task D.5.