Skip to main content

Client Operating Model

Purpose​

This document defines the operating model that is emerging across the agency app.

Use it to answer:

  • what the app fundamentally is
  • what the agency is allowed to optimize for
  • which workflows are canonical versus optional
  • how cross-feature linkage should work without turning the product into a rigid ERP

Read this together with domain-model.md, logic-rules.md, and cross-feature-link-matrix.md.

Core Thesis​

The product is a client-account operating graph.

It is not:

  • a project-management tool with billing bolted on
  • a billing tool with projects bolted on
  • a file-sharing tool with a CRM shell

The one required anchor is the client account.

Around that anchor, the agency can run three main operating tracks:

  • delivery
  • commercial
  • collaboration

Those tracks should inform each other when useful, but none of them should become a mandatory prerequisite for the others.

The Required Anchor​

clientAccount is the operational anchor for the first-wave product.

That means:

  • projects belong to a client account
  • invoices, subscriptions, quotes, and contracts belong to a client account
  • drive items belong to a client account
  • portal access is granted at the client-account level

The agency should never need to ask:

  • "which project owns this client relationship?"
  • "which file workspace creates the client record?"
  • "which invoice creates the commercial identity?"

The answer is always the client account first.

Client-Root Product Law​

The client account is not just the data anchor. It is the parent context for the product.

That means:

  • the client detail workspace is the simple home for everything the agency knows about that client
  • projects, invoices, subscriptions, contracts, files, requests, notes, tasks, and future client-owned records all sit under that client context
  • users should be able to enter clients/[clientId] and understand the client's world without first choosing an operational specialty view

Important rule:

Do not model sidebar workspaces as separate ownership universes.

They are operational projections over the same client-root truth.

This is the core app model, not a Drive-specific convention.

In general:

  • clients/[clientId] is the simple, consolidated view of what one client owns
  • sidebar workspaces are the agency's advanced operational views over what clients own
  • those operational views may be cross-client, queue-based, or specialty-shaped, but they still project the same underlying client-owned records

Examples:

  • Clients is the client-account directory and entrypoint
  • Projects is the advanced operational view across project work for one or many clients
  • Drive is the advanced operational view across shared files, uploads, requests, and client/project collaboration artifacts
  • Invoices and Subscriptions are the advanced operational views across commercial records
  • Contracts is the advanced operational view across agreement work

If a user opens Drive, Invoices, or Contracts, they are not leaving the client model. They are looking at one layer of the same client-owned system in a more operational way.

The Three Operating Tracks​

1. Delivery​

Delivery is how the agency runs work.

Core objects:

  • projects
  • project updates
  • time entries

Primary questions answered:

  • what work is active
  • who is doing it
  • what changed for the client
  • how much time was spent

Important rule:

Projects are optional structure, not a global prerequisite.

An agency may run delivery through projects, but it must still be valid to:

  • log time directly to a client account
  • invoice a client without a project
  • share drive items without a project

2. Commercial​

Commercial is how the agency prices, formalizes, bills, and governs the client relationship.

Core objects:

  • quotes
  • contracts
  • invoices
  • subscriptions

Primary questions answered:

  • what was proposed
  • what was agreed
  • what is due
  • what recurring service is active

Important rule:

This is one commercial spine, not one generic billing bucket.

The objects are related, but they must stay distinct:

  • quotes express offer and intent
  • contracts express legal commitment and governing terms
  • invoices express one-time money due or paid
  • subscriptions express recurring service state

3. Collaboration​

Collaboration is how the agency and client exchange working artifacts.

Core objects:

  • drive items
  • files
  • rich docs
  • file requests

Primary questions answered:

  • what has been shared
  • what does the client need to upload back
  • where do working artifacts live
  • how can both sides retrieve the right artifact later

Important rule:

Drive is collaboration-owned.

It must not become the generic attachment dump for every other feature.

Additional rule:

Feature-owned artifacts stay feature-owned.

  • billing owns billing records and billing attachments
  • contracts own contract records and contract attachments
  • projects own project files and project collaboration artifacts
  • drive owns general shared files, ad hoc file collection, and cross-context file retrieval

The platform may share one upload/storage/metering layer underneath those features, but Drive must not become the business owner for every attachment-shaped record in the product.

The Access And Projection Layer​

Portal access is not a fourth ownership track.

It is the client-facing projection layer on top of the same client-account truth.

Core objects:

  • client contacts
  • portal users
  • portal access grants

Important rule:

Portal does not create a second business model.

It projects client-account, project, billing, and drive truth into a client-safe runtime.

Additional rule:

The portal should let client users act from the context they are already in.

  • if a file belongs to a project, the client should be able to upload it from the project
  • if a file belongs to a contract, the client should handle it from the contract flow
  • if a file belongs to billing, the client should handle it from the billing flow
  • only general shared client material should require Drive as the primary surface

Do not force the client to navigate by storage type when the business context is already known.

Agency Play Styles​

The product should support multiple valid operating styles without losing coherence.

Project-led agency​

Typical path:

  • create client account
  • create projects
  • log time to projects
  • publish project updates
  • bill with project context when useful
  • share project-linked drive items

Commercial-led agency​

Typical path:

  • create client account
  • issue quote and/or contract
  • create invoices or subscriptions directly from the client account
  • use projects only when delivery structure becomes useful

Collaboration-led agency​

Typical path:

  • create client account
  • start a shared drive workspace immediately
  • exchange files and docs without requiring formal project setup
  • introduce contracts, invoices, or subscriptions only when needed

Time-led agency​

Typical path:

  • create client account
  • log time directly against the client account
  • optionally associate some work with projects later
  • convert reviewed time into billing suggestions, not mandatory invoice payloads

Hybrid agency​

Typical path:

  • use all three tracks where they genuinely help
  • keep project, billing, and drive context additive instead of forcing every record through the same structure

Canonical Path Versus Allowed Variations​

There is a recommended path, but not a required lockstep funnel.

  1. create the client account
  2. add people and portal access as needed
  3. set billing identity/defaults when commercial work starts
  4. add projects if delivery needs explicit structure
  5. add drive organization when collaboration needs retrieval and exchange
  6. add quotes, contracts, invoices, or subscriptions when the commercial relationship needs them

Allowed variations​

These must remain valid:

  • invoice without project
  • subscription without project
  • drive without project
  • contract without drive ownership
  • portal access without an active project
  • time entry without project context

These should not be treated as second-class workflows.

Cross-Feature Relationship Rules​

Tracks may inform each other, but they do not own each other​

Examples:

  • time may inform invoice drafting
  • a quote may lead to a subscription
  • a contract may govern a project
  • a drive item may be project-linked

But:

  • time does not own invoices
  • projects do not own subscriptions
  • drive does not own contracts
  • portal does not own client-account truth

Client account is required; project is optional context​

Project links should exist when they explain delivery context, not as a prerequisite for normal agency operations.

Time informs billing without hard-locking it​

Time can recommend billable line items.

Humans still decide:

  • what is invoiced
  • how line items are grouped
  • what is omitted
  • what is overridden

Quotes, contracts, invoices, and subscriptions stay separate​

They may hand off into each other, but they should not collapse into one shared status field or one generic commercial record.

Drive stays collaboration-owned​

Drive can link to client accounts and optionally projects.

It should not become the default storage layer for:

  • contract attachments
  • invoice exports
  • subscription records
  • other commercial artifacts unless the product explicitly defines them as collaboration items

Portal is projection, not parallel truth​

Portal surfaces should expose:

  • client-safe project truth
  • client-safe billing truth
  • shared drive truth

Portal must not invent separate records that drift away from org truth.

Relationship Grammar​

Cross-feature links should fall into one of these categories.

Explains what client relationship this record belongs to.

Examples:

  • invoice to client account
  • project to client account
  • drive item to client account

Adds optional meaning without becoming required.

Examples:

  • invoice to project
  • contract to project
  • drive item to project

Explains how one record produced or informed the next step.

Examples:

  • quote to invoice
  • quote to subscription
  • quote to contract

Explains what the portal or another surface is allowed to show.

Examples:

  • portal billing view to invoice state
  • portal files view to shared drive items
  • portal projects view to client-visible project updates

A link the model should avoid because it blurs ownership or recreates legacy drift.

Examples:

  • contract as a drive item
  • subscription as a project-owned record
  • portal as a second client directory

UX Rules For Cross-Feature Linking​

Every cross-feature link should answer one of these:

  • what is this attached to
  • why does this exist
  • what should I do next

If a link answers none of those, it is probably noise.

Examples:

  • client detail should show all three tracks because it is the anchor workspace
  • invoice detail should show client, project if present, and commercial follow-through if present
  • project detail should prioritize client, updates, time, and only show commercial context when it is explicit

Keep domain problems typed​

Do not collapse different problem classes into one umbrella status.

Examples:

  • billing attention is not the same as delivery risk
  • contract pending is not the same as overdue invoice state
  • drive request backlog is not the same as project delay

Anti-Patterns​

Avoid these patterns.

  • making project selection mandatory for normal invoicing
  • using drive as the fallback attachment bucket for commercial records
  • treating portal as a second operations system
  • flattening quotes, contracts, invoices, and subscriptions into one generic billing status
  • linking unrelated records just because the schema technically allows it
  • forcing every agency into one sequence of project, time, billing, and files

What Good Looks Like​

The product is coherent when all of these are true:

  • the agency can choose how to run each client without losing the shared model
  • the client account remains the obvious anchor everywhere
  • delivery, commercial, and collaboration tracks are distinct but interoperable
  • the portal feels like a projection of org truth instead of a second application model
  • cross-feature links feel useful, not decorative or noisy