Cross-Feature Surface Audit

Purpose

This audit reviews the current org and portal surfaces through one lens:

• where cross-feature linkage is already strong
• where it is weak or partial
• where it is missing
• where it risks becoming noisy

Use this document to guide refinement work without reopening the core domain model.

Read this together with ../product/client-operating-model.md and ../product/cross-feature-link-matrix.md.

Audit Rubric

• strong the page links adjacent features in a way that helps the next job
• weak the page has the right ownership, but the cross-feature follow-through is still thin
• missing the page should surface a relationship or next action and does not yet
• noisy risk the page could easily over-link or imply the wrong ownership model if not constrained

Cross-Feature Patterns Already Working Well

These patterns are emerging correctly across the repo.

1. Client account is the obvious anchor

Strong evidence:

• client detail now owns people, projects, time, drive, contracts, billing, and activity
• invoices and subscriptions link back to the client account instead of hiding behind a generic billing hub
• portal access is moving through client contacts and client-account grants, not a parallel client directory

2. Projects are useful but not mandatory

Strong evidence:

• billing can run from the client account without requiring project setup
• drive can exist at the client level without a project
• time may reference a project, but the client account remains valid on its own

3. Commercial records are separating correctly

Strong evidence:

• quotes, contracts, invoices, and subscriptions all exist as distinct commercial records
• invoices and subscriptions now have separate top-level operational routes
• contracts are no longer Drive-owned

4. Portal is acting more like a projection layer

Strong evidence:

• portal billing, files, and projects are client-safe projections of org truth
• multi-company grant work is steering the portal away from one-membership-equals-one-company assumptions

Org Surface Audit

Page	Current cross-feature quality	What is working	What is weak, missing, or noisy	Next refinement
overview	strong	Good operational snapshot that links out to clients, invoices, and time without pretending to be the whole product	Drive, contracts, and commercial provenance are still lighter than billing/time signals	Add typed attention lanes for collaboration and legal/commercial work without collapsing them into one umbrella status
analytics	weak	Correctly separated from overview as the reporting drill-in	Still sparse as a cross-feature command surface and does not yet connect all tracks consistently	Add drill-ins by track: delivery, receivables, recurring revenue, billing attention, and later collaboration signals
clients list	strong	Correct anchor-first workspace; makes clients the main entry into all other tracks	The list still under-expresses how each client is being run across delivery, commercial, and collaboration	Add compact account-mode signals such as project-led, recurring-billed, and active shared-drive usage when those signals are reliable
clients/[clientId] overview	strong	Best current hub for the full operating graph because it sits on the anchor	Could still be clearer about recommended next actions across tracks	Add deliberate next-step actions based on account state rather than generic edit buttons
clients/[clientId]/people	strong	Correctly keeps people and portal access tied to the client company	Billing/contact-role relationships are still light; signer, finance-contact, and approver semantics are not yet explicit	Add company-role cues only where they meaningfully affect billing, contracts, or portal workflows
clients/[clientId]/projects	strong	Correctly shows projects as client-owned delivery units	Commercial and collaboration context around each project is still sparse	Add selective signals for linked contract, linked recurring coverage, and shared-drive activity when explicit
clients/[clientId]/time	weak	Correct client-account-scoped work log	Time-to-billing follow-through is still mostly implied rather than surfaced	Add reviewed billable totals and invoice-readiness cues without auto-converting time into finance truth
clients/[clientId]/drive	strong	Correct collaboration home inside the client workspace	Request flows, folder depth, and project-linked retrieval still need depth	Add request-centric actions, destination clarity, and clearer project-linked organization
clients/[clientId]/contracts	strong	Correctly keeps contracts out of Drive and inside the client commercial spine	Cross-links to quotes, subscriptions, and invoices are not yet standardized	Show governed project, source quote, recurring-service context, and billing impact only when explicit
clients/[clientId]/billing	strong	Strongest current cross-feature surface; combines client anchor, billing identity, invoices, and subscriptions well	Time-informed billing, contract linkage, and quote follow-through are still partial	Make this the canonical commercial hub for the client by showing quote and contract adjacency when useful
clients/[clientId]/activity	weak	Good candidate for a unified event projection	Risks becoming noisy if delivery, billing, portal, and collaboration events are mixed without strong typing	Keep activity grouped by domain event type and link back to the owning record, not just the feed item
projects list	weak	Correct delivery workspace with its own job	Still light on commercial and collaboration cross-signals	Add compact tags for client, contract coverage, recent shared updates, and billable work posture where explicit
projects/[projectId] overview	weak	Strong delivery-first detail view with updates and time adjacency	Collaboration and commercial context still feel secondary or partial	Add explicit but narrow side links to linked client drive items, linked contract scope, and billing context when present
projects/[projectId]/time	strong	Good delivery-to-time link	Still mostly one-way; billing consequences are not visible enough	Surface reviewed billable totals and invoice-readiness cues without turning the page into billing
projects/[projectId]/updates	strong	Correct project-to-portal projection loop	Still light on related drive and contract context	Allow updates to reference deliverables, requests, or commercial milestones when explicit
time entries	strong	Correct queue-switched operational list; time already feeds billing rollups conceptually	Commercial follow-through is still not surfaced enough in the workspace	Add explicit reviewed-billable-to-invoice recommendations and client/account coverage signals
time/timer	strong	Correct utility route rather than a separate workspace	Limited commercial and collaboration awareness while timing	Add light project/client/contract hints only when they reduce mistakes, not as mandatory structure
invoices	strong	Correct top-level operational queue with client linkage and status queues	Source-of-work context is still too thin: quote, contract, subscription, and time lineage are not standardized	Show why the invoice exists when known, not just what its Stripe state is
invoices/[invoiceRecordId]	weak	Strong client anchor and billing actions	Missing clearer provenance and follow-through to linked quote, project, contract, or subscription when present	Add a commercial provenance block with only explicit links
subscriptions	strong	Correct top-level recurring-service queue separated from invoices	Service context is still thinner than it should be	Make the recurring service more legible: what the client is paying for, what governs it, and what work it often funds
subscriptions/[subscriptionRecordId]	weak	Strong status/action surface	Missing plan history, quote/contract handoff, and clearer delivery linkage when applicable	Add history and origin context without making projects mandatory
quotes	strong	Correct bridge between commercial intent and downstream billing	Relationship to contracts and ongoing service still needs clearer handoff language	Standardize how accepted quotes lead to contracts, invoices, or subscriptions
quotes/[quoteRecordId]	weak	Good commercial detail surface with links to invoice/subscription when they exist	Missing stronger contract handoff and client-facing lifecycle cues	Add explicit origin/outcome block: proposed, accepted, invoiced, converted to recurring, contracted
contracts	strong	Correctly treated as a first-class legal/commercial queue rather than a Drive bucket	Still not fully integrated with the rest of the commercial spine	Standardize quote, subscription, invoice, and project adjacency where explicit
contracts/[contractId]	weak	Strong separation from Drive; contract-owned attachments are correct	Client-commercial follow-through is still partial	Add deliberate related-record blocks for governing quote, covered project, and related billing context
drive global finder	strong	Correctly acts as a retrieval surface, not the main ownership surface	Risks becoming noisy if it starts surfacing arbitrary commercial links	Keep it client-first and project-aware; do not reintroduce commercial ownership through convenience links
portals	strong	Correct separate control plane for access and readiness	Still light on how portal state intersects with billing, files, and active delivery for a given client	Add compact cross-track readiness signals per client account
portals/[clientId]/*	weak	Correct per-client portal operational view	Still needs richer links back into the client’s billing, files, and delivery truth	Add “open related client workspace” handoffs and cross-track readiness summaries
settings/billing	strong	Correctly separates agency SaaS billing/configuration from client billing operations	Little issue here; the separation is the value	Keep this surface configuration-only and avoid operational records here

Portal Surface Audit

Page	Current cross-feature quality	What is working	What is weak, missing, or noisy	Next refinement
overview	strong	Good comprehension-first projection of active work, billing state, and recent client-safe events	Could be better at showing next actions across all three tracks	Add clearer prompts for what needs client action now: pay, upload, review, acknowledge
projects	strong	Correct delivery projection with client-safe status and updates	Commercial and collaboration context around a project is still limited	Add related shared files and governing commercial cues only when explicit
projects/[projectId]	strong	Good project drill-in with delivery focus	Shared artifacts and request loops can still deepen	Add clearer deliverable, file-request, and acknowledgment paths
billing	strong	Correctly projects invoice and subscription truth into the portal	Quotes and contracts are not yet part of the client-facing commercial story	Decide which pre-billing and governing commercial records belong in the portal and add only those
files	strong	Correct projection of the shared drive	Request workflow and upload-back loops still need more prominence	Make requests, return uploads, and “what changed” more task-shaped
activity	weak	Good candidate for a unified client-safe event stream	Risks becoming noisy if it becomes a generic dump of unrelated events	Keep activity typed by delivery, billing, and collaboration classes
settings	weak	Correct home for client-safe account controls	Company-grant versus identity-scoped settings still need sharper separation	Distinguish identity settings from selected-company settings more clearly
support	weak	Correct place for client help context	Still not deeply wired into project, billing, or request context	Let support entry start from the current company and, when appropriate, current project/billing/request context

Highest-Value Refinements

If the goal is to improve cross-feature coherence without reopening the whole model, prioritize these.

1. Standardize commercial provenance

On quote, contract, invoice, and subscription detail, always show explicit origin and outcome links when they exist.

Examples:

• source quote
• governing contract
• linked project
• produced invoice
• produced subscription

2. Make client detail the canonical hub

Client detail should remain the place where all three tracks can be understood together.

That means strengthening:

• next actions
• account mode clues
• track health summaries

3. Keep project pages delivery-first but commercially legible

Project pages should not become billing pages.

They should still show when a project is:

• covered by recurring service
• tied to a contract
• generating billable work likely to surface commercially

4. Keep drive collaboration-owned

Do not solve commercial linkage by pushing more commercial records into Drive.

Instead:

• keep project and client retrieval strong
• keep requests explicit
• keep commercial artifacts in their own domains

5. Turn portal from visibility-only into response-loop support

The portal already projects truth well enough to support:

• payments
• file uploads
• request fulfillment
• acknowledgment of delivery milestones later

That is the next meaningful cross-feature layer.

Ranked Implementation Checklist

1. Land commercial provenance blocks on quote, invoice, subscription, and contract detail using only explicit relationships.
2. Land stronger client-detail cross-track next actions on the overview tab so the client account becomes the real operating hub.
3. Add project-level commercial context cues: linked contract, recurring coverage, and invoice posture only when explicit.
4. Add time-to-billing readiness signals in client and project time surfaces without auto-collapsing time into finance truth.
5. Standardize commercial origin and outcome summaries in client billing so quotes, contracts, invoices, and subscriptions read as one spine.
6. Add client-level operating-mode signals in the clients collection once those heuristics are reliable.
7. Add portal-side response-loop actions for pay, upload, and request fulfillment.
8. Expand analytics into track-specific drill-ins for delivery, recurring revenue, receivables, and billing attention.