alla-allaos-fullstack/docs/business/relationship-sales-workspace-blueprint-v1.md

# Relationship & Sales Workspace Blueprint v1

Status: Draft Freeze Candidate
Last Updated: 2026-07-07
Owner: Business Architecture / CRM Governance

## Purpose

This document freezes the target long-term business architecture for ALLA OS as a Relationship-Driven Sales Workspace. It is the business source of truth for future capability audits, schema refactoring, API design, workflow design, dashboard design, and workspace navigation.

This blueprint has higher priority than legacy implementation wording when conflicts exist. Existing accepted ADRs and implementation notes remain historical references until they are reconciled in later phases.

## Review Baseline

This blueprint was aligned against:

- `AGENTS.md`
- `docs/standards/project-foundations.md`
- `docs/standards/architecture-rules.md`
- `docs/standards/ui-ux-rules.md`
- `docs/standards/task-review-checklist.md`
- `docs/business/crm-terminology.md`
- `docs/security/crm-authorization-boundaries.md`
- `docs/adr/0011-lead-enquiry-ownership-model.md`
- `docs/adr/0015-customer-ownership-contact-sharing.md`
- `docs/adr/0016-won-lost-lifecycle-governance.md`
- `docs/adr/0018-lead-enquiry-domain-separation.md`
- `plans/task-d.5.md`
- `plans/task-d.6.2.md`
- current CRM schema and opportunity / quotation timeline fields in `src/db/schema.ts`

## 1. Product Vision Freeze

### Product Vision

ALLA OS is a Relationship-Driven Sales Workspace for B2B commercial teams that need one operational system for customer relationships, opportunity execution, quotation control, follow-up discipline, forecasting, and management visibility.

### Product Mission

Help teams move from fragmented CRM records into a governed daily operating workspace where relationship context, next actions, sales execution, document progress, and management signals stay connected.

### Design Philosophy

- Relationship first, transaction second
- Activities are the operating heartbeat
- Opportunities own commercial project execution
- Quotations own document and approval execution
- Calendar and timeline are working views, not isolated modules
- Dashboard metrics must come from governed lifecycle state, not ad hoc UI interpretation

### Core Principles

1. One business concept should have one primary owner.
2. Relationship context must survive handoffs across marketing, sales, and management.
3. Activities should be reusable across leads, opportunities, quotations, and customers.
4. Forecast and priority signals must be explicit business fields, not derived from loose notes.
5. Timeline should be generated from business events instead of becoming a second source of truth.
6. Calendar should aggregate actionable work, not act as a standalone isolated domain.

## 2. Business Terminology Dictionary

| Term | Official Definition | Primary Owner |
| --- | --- | --- |
| Customer | A business account already known to the organization and managed as a reusable commercial relationship record. | Shared relationship master |
| Prospect | A customer account type representing a relationship not yet established as an active buying customer. | Customer classification |
| Contact | A person connected to a customer account and governed by ownership and sharing rules. | Customer relationship layer |
| Lead | A marketing-origin or early-stage commercial signal that may later create one or more opportunities. | Marketing |
| Opportunity | The sales-owned project lifecycle record for qualifying demand, follow-up, forecasting, and business outcome. | Sales |
| Quotation | The sales document lifecycle record for pricing, revision, approval, preview, and approved output. | Sales / Commercial operations |
| PO | The external purchase order confirmation that finalizes a won commercial outcome. | Customer-side commercial confirmation |
| Activity | A single reusable work record representing planned or completed business interaction or internal execution. | Shared operational foundation |
| Follow-up | A sales or marketing activity intended to move a lead, opportunity, or quotation forward. | Activity subtype |
| Task | An internal action item assigned to a user with due-date accountability. | Activity subtype |
| Reminder | A time-based prompt for upcoming work or business commitments. | Activity / notification layer |
| Visit | A physical or remote customer-facing interaction recorded as an activity. | Activity subtype |
| Meeting | A scheduled business discussion recorded as an activity. | Activity subtype |
| Site Survey | A project qualification or technical assessment activity for an opportunity or quotation. | Activity subtype |
| Presentation | A commercial presentation or proposal discussion activity. | Activity subtype |
| Timeline | A generated chronological business view assembled from events and activities across related records. | Generated view |
| Workspace | A role-oriented working surface that prioritizes decisions, tasks, and context for a specific user group. | Product navigation layer |
| Pipeline | The governed set of active leads or opportunities moving toward an outcome. | Lead / opportunity analytics |
| Forecast | A forward-looking commercial projection built from active opportunity signals. | Opportunity analytics |
| Expected Award Date | The best current estimate of when an opportunity may be commercially awarded or confirmed. | Opportunity |
| Expected Delivery Date | The best current estimate of operational delivery timing after commercial confirmation. | Opportunity / quotation execution |
| Hot Project | A managed priority signal for opportunities or quotations that need elevated attention because of timing, value, risk, or strategic importance. | Opportunity-led priority model |
| Status | A high-level business state shown to users. | Entity-specific |
| Process Status | A lifecycle-progress state describing where execution currently stands. | Entity-specific |
| Outcome | A business result state such as open, won, or lost. | Entity-specific |

## 3. Customer Relationship Model Freeze

The relationship model is:

```text
Customer
-> Contact
-> Lead
-> Opportunity
-> Quotation
-> PO / Won-Lost Outcome
```

Rules:

- Customer is the reusable relationship anchor.
- Customer ownership remains a first-class governance rule.
- Contact visibility remains governed by sharing plus customer access.
- Lead represents marketing discovery and early qualification.
- Opportunity represents sales execution and owns the project lifecycle.
- Quotation represents document execution and owns pricing, approval, and revision history.

## 4. Activity Model Freeze

Activity becomes the shared operational model across customer, lead, opportunity, and quotation work.

Supported activity families:

- Follow-up
- Visit
- Meeting
- Reminder
- Task
- Email
- Phone Call
- Presentation
- Site Survey
- Internal Task

Rules:

- Activity is the single business activity model.
- Activities may reference one primary entity and optional related entities.
- Timeline entries are generated from activities plus business events.
- Calendar surfaces scheduled activities and reminders, not freeform historical notes alone.
- Notifications and future automation should subscribe to activity state changes instead of duplicating activity data.

## 5. Project Lifecycle Freeze

The official project lifecycle is:

```text
Lead
-> Opportunity
-> Quotation
-> PO Received
-> Won
```

Alternative close path:

```text
Lead
-> Opportunity
-> Lost
```

Ownership by stage:

- Lead is marketing-owned.
- Opportunity is sales-owned.
- Quotation is sales-owned and document-controlled.
- Won/Lost is decided from opportunity outcome governance.

## 6. Status Strategy Freeze

### Ownership Boundaries

- Lead owns early discovery and marketing follow-up state.
- Opportunity owns project process state and commercial forecast state.
- Quotation owns document process state, approval state, and revision state.

### Status Model

- Process Status answers "where are we in execution?"
- Operational Status answers "what is the current working condition?"
- Outcome answers "what business result has been reached?"

### Frozen Rule

Opportunity owns project process. Quotation owns document status. Quotation status alone must not decide business win/loss.

## 7. Hot Project Strategy Freeze

Hot Project is a governed attention flag, not a substitute for lifecycle status.

Purpose:

- highlight time-sensitive opportunities
- expose management attention needs
- support dashboard prioritization
- support follow-up discipline and forecast review

Rules:

- Hot Project is opportunity-led.
- Quotation may inherit or display the same signal for document execution context.
- Auto-suggestion is allowed from timeline rules such as near-term award/close windows.
- Manual override is allowed and must be preserved.
- Hot Project does not automatically mean high probability, won, or urgent delivery.

## 8. Forecast Strategy Freeze

### Expected Award Date

Definition:
The current best estimate of when the customer may decide, award, or confirm the opportunity commercially.

Usage:

- forecast views
- pipeline aging and expected-award monitoring
- management dashboard
- calendar awareness when follow-up should intensify
- reminder generation

### Expected Delivery Date

Definition:
The current best estimate of when fulfillment or delivery is expected after the opportunity progresses toward execution.

Usage:

- delivery coordination awareness
- opportunity-to-quotation context
- manager workload planning
- post-award readiness monitoring

Rules:

- Expected Award Date belongs primarily to opportunity forecasting.
- Expected Delivery Date belongs to downstream execution planning and may appear on both opportunity and quotation surfaces.

## 9. Workspace Architecture Freeze

### Workspace Set

- Marketing Workspace
- Sales Workspace
- Manager Workspace
- Executive Workspace
- Calendar Workspace

### Role of Each Workspace

- Marketing Workspace manages lead creation, lead follow-up, awareness analytics, and handoff quality.
- Sales Workspace manages opportunities, quotations, project progress, and customer-facing execution.
- Manager Workspace focuses on team follow-up, forecast confidence, hot projects, and workload balance.
- Executive Workspace focuses on pipeline health, revenue outlook, strategic accounts, and business outcomes.
- Calendar Workspace is the time-based operational lens across roles.

### Philosophy

- Workspaces are role-oriented views over shared governed data.
- Calendar is a workspace, not a disconnected module.
- My Day is a personalized subset of calendar, tasks, reminders, and urgent follow-ups.
- Timeline is a contextual history view, not a separate entity users maintain directly.

## 10. Timeline Strategy Freeze

Timeline is generated dynamically from business events and activities.

Rules:

- Timeline owner is the platform, not a user-maintained table of manual history items.
- Sources include activities, assignments, status transitions, quotation revisions, approvals, attachments, and outcome events.
- Ordering is chronological by event time with deterministic tie-breaking.
- Visibility follows the permission of the originating records and related pricing/security boundaries.
- Timeline is read-oriented and should not become a second workflow engine.

## 11. Calendar Strategy Freeze

Calendar is the scheduled execution workspace.

Sources:

- activities with date/time
- reminders
- follow-up due dates
- meeting / visit / presentation / survey schedules
- selected opportunity and quotation milestone dates when configured as calendar-worthy events

Rules:

- Calendar aggregates action-bearing events from existing records.
- Personal Calendar shows a user's owned or assigned work.
- Team Calendar shows subordinate or permitted shared work.
- Manager View emphasizes overdue work, near-term commitments, and hot projects.
- Opportunity and quotation dates may contribute calendar signals without becoming duplicate calendar records.

## 12. Dashboard Strategy Freeze

The dashboard stack should answer operational questions, not simply restate table data.

Core dashboard blocks:

- pipeline
- forecast
- hot projects
- overdue activities
- follow-up health
- won/lost outcome visibility
- role-specific KPI summaries

Rules:

- Lead KPI and opportunity KPI should not be blended into one ambiguous count.
- Forecast must be opportunity-based.
- Revenue and commercial visibility must continue follow pricing authorization boundaries.
- Dashboard cards should prioritize actionability over vanity metrics.

## 13. Capability Map

| Capability | Primary Workspace | Owning Domain |
| --- | --- | --- |
| Relationship master management | Sales / Manager | Customer + Contact |
| Prospecting and awareness capture | Marketing | Lead |
| Sales qualification and project pursuit | Sales | Opportunity |
| Pricing, revision, and approval | Sales / Manager | Quotation |
| Follow-up and activity discipline | All | Activity |
| Daily scheduling and reminders | All | Calendar workspace |
| Contextual business history | All | Timeline |
| Forecast review | Manager / Executive | Opportunity analytics |
| Priority escalation | Manager / Sales | Hot project model |
| Outcome monitoring | Manager / Executive | Opportunity outcome |

## 14. Journey Views

### Customer Journey

```text
Prospect Customer
-> Relationship Development
-> Active Customer
-> Repeat Opportunity / Quotation Cycles
```

### Project Journey

```text
Lead
-> Opportunity
-> Follow-up / Qualification
-> Quotation
-> Revision / Approval
-> PO Received
-> Delivery Planning
```

### Activity Journey

```text
Planned Activity
-> Due
-> Completed / Rescheduled / Cancelled
-> Follow-up or Next Action
-> Timeline + Calendar visibility
```

## 15. State Machine Freeze

### Lead

```text
Open
-> Qualified / Handoff Ready
-> Converted to Opportunity
-> Lost / Cancelled
```

### Opportunity

```text
Open
-> In Progress
-> Quotation in Flight
-> Won
-> Lost
```

### Quotation

```text
Draft
-> Sent
-> Under Revision
-> Pending Approval
-> Approved / Rejected / Returned
-> Commercially Referenced by Opportunity Outcome
```

Frozen rule:

- Opportunity outcome is the business result state.
- Quotation approval is a document control state.

## 16. Gap Summary: Current System vs Blueprint

| Area | Current State | Blueprint Direction | Gap Type |
| --- | --- | --- | --- |
| Terminology | Historical docs still mix `enquiry` and `opportunity`. | Opportunity is the official sales project term. | Refactor |
| Lead vs opportunity model | Schema already has `crm_leads` and `crm_opportunities`, but older ADR lineage still references shared enquiry history. | Keep split-domain model and retire mixed terminology in governance docs. | Refactor |
| Timeline | Follow-up/timeline concepts exist in features, but platform-wide generated timeline philosophy is not yet frozen as one rule. | Generated timeline view from activities + events. | Enhancement |
| Calendar | Date fields and follow-up schedules exist, but calendar-as-workspace is not yet fully defined. | Calendar becomes cross-role operational workspace. | New capability |
| Forecast fields | Opportunity and quotation timeline fields exist, but business meaning is not yet frozen centrally. | Expected Award Date and Expected Delivery Date become governed forecast concepts. | Enhancement |
| Hot Project | Data support exists in opportunity and quotation flows. | Formalize Hot Project as governed priority signal with auto-suggest and override. | Enhancement |
| Activity model | Follow-up exists in multiple domains. | Activity becomes the shared model across work types. | Refactor |
| Workspace model | Role-oriented pages exist, but workspace philosophy is incomplete. | Freeze marketing, sales, manager, executive, and calendar workspace roles. | Enhancement |

## 17. Recommended Refactoring Strategy

### No Change

- Preserve organization, RBAC, approval, PDF, document artifact, and quotation foundations.
- Preserve customer ownership and contact sharing governance.
- Preserve won/lost governance where PO received defines won.

### Enhancement

- Align dashboard, reporting, and calendar behavior to the frozen forecast and Hot Project definitions.
- Expand opportunity and quotation views to expose the frozen timeline and calendar concepts consistently.

### Refactor

- Remove remaining business documentation that still treats `enquiry` as the primary sales term.
- Consolidate follow-up and activity semantics under one shared business model.
- Reconcile older ADR wording with the split lead/opportunity model now reflected in schema and UI direction.

### New Capability

- Calendar Workspace
- generated cross-entity Timeline
- My Day operational surface
- broader activity orchestration and automation

## 18. Governance Notes for Phase R.1

Phase R.1 should use this blueprint to audit:

- where code, docs, reports, and APIs still use historical `enquiry` wording
- where activity data is duplicated instead of normalized conceptually
- where calendar and timeline behavior is implicit rather than governed
- where dashboard metrics still need formal mapping to frozen business definitions

## 19. Entry Criteria for Next Phase

Phase R.1 may begin when:

1. this blueprint is accepted as the business baseline
2. terminology conflicts are treated as governance backlog instead of hidden assumptions
3. capability audit work references this document explicitly