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:

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:

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

Alternative close path:

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

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

Project Journey

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

Activity Journey

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

15. State Machine Freeze

Lead

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

Opportunity

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

Quotation

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