Cross-Feature Link Matrix

Purpose

This document defines the canonical allowed-link matrix between the main client-work entities.

Use it to answer:

• which entities may link directly
• how strong that link should be
• why the link exists
• what the link must not imply

Read this together with client-operating-model.md.

Link Strength Legend

• required ownership the relationship is part of the core data model
• optional context the relationship is valid but not mandatory
• workflow handoff the relationship explains how one record informed or produced another
• projection only the relationship exists at the surface/runtime level, not as independent ownership
• forbidden direct link the product should avoid using this as a canonical first-wave relation

Portal Meaning In This Matrix

portal in this matrix means the portal-facing runtime and visibility context granted to the client through portal access grants.

It does not mean a separate business-owned record that competes with org truth.

Canonical Pair Matrix

Pair	Strength	Why the link exists	Do not use it for
client account ↔ project	required ownership	projects belong to a client relationship	creating project-owned clients
client account ↔ quote	required ownership	quotes belong to one commercial client relationship	making quotes free-floating sales objects
client account ↔ contract	required ownership	contracts belong to one legal/commercial client relationship	treating contracts as generic workspace files
client account ↔ invoice	required ownership	invoices belong to one client's billing history	making invoices project-owned by default
client account ↔ subscription	required ownership	recurring service belongs to the client account first	requiring a project before a subscription can exist
client account ↔ drive item	required ownership	every shared or internal artifact belongs to a client workspace	using the global drive as the ownership anchor
client account ↔ portal	required ownership	portal access is granted per client company	using portal identity as the client record
project ↔ quote	optional context	a quote may price scoped project work	forcing every quote to pick a project
project ↔ contract	optional context	a contract may govern one scoped deliverable/project	making project linkage mandatory for all contracts
project ↔ invoice	optional context	an invoice may bill project work when helpful for clarity/reporting	forcing project linkage for routine billing
project ↔ subscription	optional context	a subscription may reference the service context it supports	turning subscriptions into project-owned records
project ↔ drive item	optional context	files and docs may be easier to retrieve when project-linked	making project context required for normal collaboration
project ↔ portal	projection only	the portal shows project truth through the selected client grant	creating separate portal-owned project records
quote ↔ contract	workflow handoff	an accepted quote may lead to a contract	collapsing offer and agreement into one record
quote ↔ invoice	workflow handoff	an accepted quote may produce one or more invoices	assuming all invoices must have quotes
quote ↔ subscription	workflow handoff	an accepted quote may create a recurring service	assuming subscriptions require a quote forever
quote ↔ drive item	forbidden direct link	quotes are commercial records, not collaboration-owned artifacts	storing quote ownership in Drive
quote ↔ portal	projection only	portal may eventually show selected quote state when the client needs it	treating portal quote views as a separate quote system
contract ↔ invoice	optional context	an invoice may relate to contracted work or milestones	auto-deriving invoice truth purely from contract state
contract ↔ subscription	optional context	a contract may govern a recurring commercial relationship	making contract linkage mandatory for every subscription
contract ↔ drive item	forbidden direct link	contract attachments should remain contract-owned, not Drive-owned	putting signed PDFs back into shared Drive ownership
contract ↔ portal	projection only	portal may show governed contract state and contract-owned attachments	using portal files as contract truth
invoice ↔ subscription	workflow handoff	some invoices are produced from recurring service state	collapsing one-time invoice state into subscription status
invoice ↔ drive item	forbidden direct link	invoices are finance records with Stripe/native artifact paths	organizing invoice ownership through Drive folders
invoice ↔ portal	projection only	portal should expose invoice state and pay/download actions	making the portal the finance source of truth
subscription ↔ drive item	forbidden direct link	recurring billing should not be organized as collaboration storage	storing plan/service truth as Drive artifacts
subscription ↔ portal	projection only	portal should show active service and renewal state	creating portal-only subscription truth
drive item ↔ portal	projection only	shared items appear in portal when visibility permits	making portal-specific copies of drive items

Strong Default UI Adjacency

The matrix above should drive UI adjacency rules.

Progressive-Disclosure Interaction Rule

Optional context must remain available without becoming permanent form furniture.

Use the shared linked-items pattern when all of these are true:

• the relationship connects otherwise independent feature records
• the owning record remains valid without the relationship
• adding the relationship improves retrieval, context, or follow-through
• the relationship does not silently change money, access, visibility, routing, or ownership

The compact outline Add button with the link icon is reserved for surfaces that can connect several different entity types, where it signals that a bundle of optional cross-feature context is available. Several possible entities open the type overview. Up to two selected records become removable icon chips on the same compact row; further selections collapse into a +N count and remain editable in the picker. Conditional pickers must stay inside the portalled popover so choosing a parent never inserts a new field into the surrounding page or dialog. The compact row must not wrap and change the surrounding layout.

When a surface exposes only one optional relationship, use a normal labeled select or multi-select field. Do not present a one-off Add project, Add task, or similar trigger; the ordinary field is clearer and fits naturally alongside the rest of the form.

Selection and presentation are separate states. Inside an editor, selected records are removable chips. After the owning record is saved, read surfaces should render explicit navigable links to the related records, not disabled or removable editor chips. Removing a connection must never delete the related record.

Use the configuration presentation only when several links jointly configure an active workflow, such as timer client, project, task, and note context. Required links must be named as required and cannot rely on color alone.

Do not use this pattern for:

• required client ownership
• a project's owning client
• task assignment, dates, status, or priority
• folder destinations, permissions, or visibility
• billing calculations, invoice line selection, payment configuration, or time-entry reservation
• provenance generated by a workflow handoff, such as an accepted quote producing an invoice

Creation is distinct from connection. If a picker supports creating the related entity, show Create <entity> as a footer action inside the picker; do not make the Add trigger create a new record directly.

Current Optional-Link Surface Audit

Surface	Relationship	Decision	Reason
project update	tasks	use labeled multi-select	optional delivery context; several tasks may be selected, but this is still one field type
time entry	project, task, saved note	use compact hierarchical linker	required client ownership stays explicit while optional work context remains collapsed
timer page and timer dialog	client, project, task, note	use configuration linker	one compact summary prevents four context controls from dominating the timer
active timer quick view	task, saved note	use compact linker	client/project are already summarized; secondary context stays optional
manual calendar event	client, project	use compact hierarchical linker	event scheduling is complete without work context
contract create/edit	project	use labeled select	client remains required ownership; project is explicitly optional context
drive file, folder, or doc	project	use labeled select	client remains required ownership; project improves retrieval
file request	project	use labeled select beside dedicated destination control	project is optional context; destination folder remains operational
note compose	client, project	keep current scope controls	today these values determine note scope and placement, not merely an optional link
invoiceable time selection	time entries	do not convert	selection changes amounts, reservations, and locking
quote/subscription	project	use labeled select in create/edit and navigable read links	client ownership remains required; the project is optional commercial context and is validated against that client
invoice	project	keep current operational selection and render a navigable read link	invoice project selection may drive time allocation and is not always harmless optional metadata
quote/invoice/subscription provenance	commercial records	render explicit read-only links	workflow-derived provenance should not look manually attachable unless the data model supports that action

Client account pages should link broadly

Because the client account is the anchor, its detail workspace may intentionally surface:

• projects
• people and portal access
• quotes, contracts, invoices, subscriptions
• drive items and requests
• activity across those tracks

Project pages should link narrowly

Project detail should always surface:

• client account
• project updates
• time

Project detail may surface when explicit:

• linked contracts
• linked drive items
• linked invoice context

Project detail should not imply that subscriptions or invoicing require projects.

Invoice and subscription pages should stay commercially typed

Invoice and subscription detail should always surface:

• client account
• billing actions

They may surface when explicit:

• linked project context
• linked quote handoff
• linked contract context

They should not surface arbitrary drive links just because files exist somewhere for that client.

Drive pages should stay collaboration-typed

Drive detail/list surfaces should always surface:

• client account
• project context if present
• visibility, uploader, and request context

They should not surface contracts, invoices, or subscriptions as if Drive owns them.

Portal pages should show projections, not alternate ownership

Portal pages may expose:

• projects and updates
• billing state
• shared files and docs
• company-specific access state

They should not create alternate primary records or alternate status models.

Design Guardrails

If a proposed new link does any of these, it is probably wrong:

• makes project linkage mandatory for billing
• makes Drive the fallback owner of commercial artifacts
• creates a portal-only version of an existing org record
• compresses delivery, legal, and finance states into one field
• removes the client account as the obvious anchor