Skip to main content

Client Drive Specification

Purpose​

This document is the source of truth for the client drive product.

Use it to answer:

  • what the agency and client should experience
  • what belongs in the drive versus outside it
  • how files, folders, rich docs, and requests relate to each other
  • which visibility and collaboration rules are required in the first real version

Read this together with file-collaboration-model.md for the high-level product rationale and ../development/client-drive-implementation-plan.md for the backend schema and migration plan.

Product Decision​

The product should use a client-first drive model.

That means:

  • every active client account has a drive by default
  • the client drive is the primary organizational unit
  • the org-wide drive page is a global finder across client drives, not the main place items are organized
  • the drive supports both uploaded files and in-app rich text docs
  • file requests are a lightweight coordination layer that sits on top of the drive
  • authenticated portal collaboration is the default client-facing access model
  • scoped external upload links may exist for one-off contributors, but they do not replace portal access

Primary Surfaces​

Org​

The agency needs two drive experiences:

  • a client-specific drive inside each customer workspace
  • a global drive finder across all visible client drives

The client-specific drive is the primary working surface.

The global drive finder is for:

  • recent items
  • search across clients
  • quick retrieval
  • jumping into the right client drive

Portal​

The client needs a shared drive surface inside the portal.

The portal drive must support:

  • browsing shared folders and files
  • reading shared rich text docs
  • uploading files back to the agency
  • creating shared rich text docs
  • seeing and fulfilling file requests

Core Jobs​

The drive is only correct if it solves all of these jobs together:

  • organize shared account and project artifacts in one predictable place
  • retrieve the right file or doc quickly from either the client workspace or the org-wide finder
  • let the agency ask for something specific without forcing every upload through a request
  • let the client share something back without guessing where it belongs
  • preserve who uploaded or authored an item and why it exists
  • support one-off outside contributors without exposing the full client workspace

Core Object Model​

The drive is made of items.

First-version item kinds:

  • folder
  • file
  • doc

Important distinction:

  • file means an uploaded binary asset such as PDF, TXT, image, or video
  • doc means an in-app rich text document authored in the editor

Requests are related to the drive but are not themselves drive items.

Folder Model​

The first real version should support real nested folders inside each client drive.

Folder rules:

  • folders belong to one client account
  • folders may optionally sit inside another folder
  • folders may optionally be project-linked
  • folders inherit visibility from their parent when nested
  • moving an item between folders may also change its effective project context if the destination folder is project-linked

Do not start with fake folders created only from tags or kinds.

The UI should behave like a real drive.

Visibility Model​

The first version should keep visibility simple.

Allowed visibility states:

  • shared
  • internal

Rules:

  • shared items are visible in the client portal
  • internal items are visible only on the agency side
  • internal agency visibility follows client-account access by default
  • do not require per-file team restrictions in the base model

Future team-restricted or exception-based internal visibility can be layered on later, but it is not part of the first required model.

Access Modes​

The product should treat access mode as a separate decision from visibility.

Required access modes:

  • internal: org members with client-account visibility can use internal items
  • portal-shared: authenticated portal users with an active grant can browse and contribute to shared items
  • external-upload-link: a scoped destination link that lets an outside contributor upload into one exact place without browsing the rest of the drive

Rules:

  • portal access remains the default for ongoing client collaboration
  • external upload links exist for one-off contributors such as contractors, signers, or client-side collaborators who should not become full portal users yet
  • external upload links must be destination-scoped, time-bound, and upload-oriented
  • do not treat an upload link as a second general-purpose shared-drive surface
  • if the same outside person needs recurring collaboration, move them into the portal grant model instead of minting endless guest links

Authorship And Collaboration​

Both agency users and portal users can contribute to the drive.

First-version collaboration rules:

  • agency users can upload files
  • portal users can upload files
  • agency users can create rich text docs
  • portal users can create rich text docs
  • uploader and author side must remain visible on the item

The product must preserve whether an item came from:

  • the agency
  • the client
  • an external upload-link contributor
  • a system-generated workflow later if needed

Rich Text Docs​

Rich text docs are a first-class drive item, not an afterthought.

Use cases:

  • briefs
  • notes shared with clients
  • polished deliverable docs
  • collaborative working docs that should be read in-app instead of downloaded

Rules:

  • docs live inside the client drive alongside files
  • docs can be shared or internal
  • docs can be account-wide or project-linked
  • shared docs are readable in the portal
  • internal notes that should never risk leaking to clients must stay outside this shared drive model

File Types​

The file drive must support ordinary business files from the first usable release.

Required categories include:

  • text files
  • PDFs
  • images
  • video files
  • general office or reference files

The schema should not hardcode the file universe beyond broad validation and metadata capture.

Request Layer​

Requests refine collaboration. They do not replace the drive.

Request use cases:

  • ask a client for source assets
  • request a signed file
  • request missing project materials
  • request approval-supporting uploads

Request status set:

  • requested
  • submitted
  • reviewed
  • closed

Request rules:

  • a request belongs to a client account
  • a request may optionally target a project
  • a request may optionally target a destination folder
  • fulfilling a request creates or links real drive items
  • normal uploads must still be allowed without a request
  • a request may optionally be fulfilled through a scoped external upload link when the recipient should not receive full portal access

The agency should be able to generate an upload link from a shared folder or request destination.

This link must let the recipient upload directly into that exact location.

Required behavior:

  • the link resolves to one destination folder or request target
  • the recipient sees the destination name, the requesting agency context, and any upload instructions
  • the recipient can upload files into that destination without seeing sibling folders, unrelated files, or internal items
  • the submission records uploader provenance, timestamp, and link origin for the agency
  • the agency can revoke the link, set an expiry, and choose one-time versus reusable submission behavior

Authentication rule:

  • if the recipient already has portal access or should become an ongoing collaborator, route them through portal login
  • if the recipient is outside the current portal grant set, allow a verified external upload flow instead of forcing full portal-account creation first
  • do not allow a fully anonymous upload path in the first real version

Product rule:

An upload link is for contribution, not browsing.

It is not a public client portal.

The product needs to support two separate axes without creating two separate systems:

  • agency maturity:
    • organized agency: uses projects, requests, and clear destinations
    • unorganized agency: needs a fast client-scoped "put the file here" flow
  • uploader identity:
    • agency uploader
    • portal client uploader
    • outside contributor uploading because the client or agency does not actually hold the file

These must use the same upload-target model with different entry points, not separate backend systems.

Recommended rule set:

  • agency users can create contributor upload links for destinations they control
  • portal clients can always upload directly where they already have access
  • portal clients can view and forward existing contributor upload links for destinations they already have access to
  • portal clients can mint new contributor links within destinations they already access, never across arbitrary client scope
  • outside contributors should not need portal accounts

Important rule:

The actor who decides "someone else needs to upload this" should be authenticated.

The outside contributor who fulfills that request should not be forced through full portal account creation.

Balanced auth split:

  • creating a contributor link requires authenticated agency or authenticated portal-client access
  • fulfilling a contributor link does not require portal login
  • contributor fulfillment stays destination-scoped, upload-only, and lightly verified

This is the defensible low-friction model. It avoids both extremes:

  • requiring third-party portal login for one-off contributions
  • allowing unauthenticated actors to mint broad anonymous upload access

External Verification Rule​

The first real version should use email OTP only.

Required flow:

  • the recipient opens the upload link
  • they enter the email address they are using for this submission
  • the product emails a short-lived one-time code
  • after that code is verified, the recipient can upload into the destination

Do not add an optional passcode in the first version.

Reasoning:

  • the agency needs a low-friction flow for outside contributors

Current Implementation Status​

The current shipped baseline is the stronger destination-scoped contributor model, not the earlier cautious MVP.

Implemented today:

  • authenticated org users can create, list, and revoke contributor upload links
  • org users can see whether each contributor link was created by agency staff or by a portal client, and can copy or reissue link URLs from first-class UI
  • authenticated portal clients can create, list, copy, and revoke contributor upload links for visible shared destinations
  • portal link creation now includes an explicit destination selector inside the creation dialog instead of relying only on per-folder launch points
  • links are destination-scoped to one explicit shared folder
  • request-origin links inherit the request destination and default to one submission / one file
  • outside contributors do not need portal accounts to fulfill a link
  • outside contributors verify with email OTP and then upload through a narrow upload-only flow
  • uploaded files record explicit external provenance plus verified submitter email and link origin

Current product law:

  • org users can create contributor links
  • portal clients can create contributor links inside visible shared destinations only
  • portal clients can copy and forward visible contributor links in first-class UI
  • contributor links never expand beyond one shared destination
  • outside contributors still fulfill through email OTP without portal login
  • email OTP is enough to tie the upload to a reachable identity and create an audit trail
  • if a contributor needs stronger or recurring access, they should move into the portal grant model instead of relying on a more complex guest-link flow

Org UI Contract​

Global drive finder​

The org global drive route should behave like a finder.

It must support:

  • search across visible client drives
  • a client rail or client finder list
  • recent items sorted by recent activity
  • filters for visibility and item type
  • quick jump from an item to the owning client workspace

This route is not the main place nested folders are managed long-term.

Client drive tab​

Each customer workspace should expose a Drive tab.

It must become the main place to:

  • browse the client's shared and internal workspaces
  • move through folders
  • upload files
  • create folders
  • create rich docs
  • manage request fulfillment
  • generate scoped upload links for shared destinations when a one-off outside contributor needs to send something in

This action belongs on shared folders only.

Entry points:

  • folder row or tile actions menu
  • folder detail header action when that folder is open

Do not show this action on:

  • internal folders
  • files
  • rich docs

Dialog contract:

  • title: Create upload link
  • destination summary: locked shared folder path
  • fields:
    • link label, prefilled from the folder name
    • optional instructions
    • expiry, default 7 days
    • submission mode, default reusable until expiry
    • optional max files limit

Success state:

  • show the full link
  • primary action is Copy link
  • secondary management action is Revoke link
  • show expiry and destination summary inline

This action belongs on requests that are still waiting for a response.

Entry point:

  • request row actions menu in the org drive request backlog

Availability rules:

  • show for requested items
  • if the request has no destination folder yet, replace the action with Set destination folder and do not allow link creation until the destination is explicit

Dialog contract:

  • title: Create request upload link
  • destination summary: locked request title plus destination folder
  • fields:
    • link label, prefilled from the request title
    • optional instructions, prefilled from the request description when useful
    • expiry, default to the request due date when present, otherwise 7 days
  • defaults:
    • single-use link
    • one file unless the agency explicitly broadens it

Post-create behavior:

  • the request should show that an active upload link exists
  • org users can copy or revoke that link from the request row
  • once a valid upload lands, the request moves through the normal submitted-review-close lifecycle

Portal UI Contract​

The client portal drive should prioritize comprehension and action.

It must let a client quickly answer:

  • what files or docs are shared with me
  • where do I upload something back
  • what requests are waiting on me
  • what changed recently

Public Sharing Rule​

Do not ship general public browsing of the drive as part of the baseline model.

Specifically:

  • do not allow a link that exposes a whole shared folder tree to anyone on the internet
  • do not allow anonymous no-identity uploads into shared client folders
  • do not blur together portal access, upload links, and future public read links as if they were the same capability

If a later phase needs read-only public delivery links for specific files, treat that as a separate capability with its own rules.

Explicit Non-Goals For The First Version​

Do not require these before the drive is considered correct:

  • a deep Dropbox-style permission matrix
  • real-time multiplayer editing
  • comments, suggestions, or approval workflows on every doc
  • enterprise records-management rules
  • file-level internal audience selection as the default model
  • general-purpose public drive browsing

Delivery Rule​

The drive is complete only when both of these are true:

  • the agency can treat the customer workspace as the main place to organize shared artifacts
  • the client can reliably find, upload, and read shared items in the portal without falling back to email history
  • the agency can safely collect one-off outside contributions into the right destination without exposing the rest of the drive