DEV Community: Digital

Stop chasing client assets: a TypeScript state machine for content handoffs

Digital — Tue, 20 Oct 2026 09:07:52 +0000

A website project can have two backlogs: code to ship and content the client still needs to provide. Most project boards track the first one very carefully. The second backlog often lives in scattered emails, chat messages, shared folders, and an optimistic sentence: "I'll send the logo tomorrow."

This is not simply a file-upload problem. It's a small workflow problem with states, permissions, versioning, and clear ownership.

Here is a practical approach to designing that workflow. The code below is a reference design, not a claim about the internals of any particular product.

Start with requirements, not uploads

Instead of asking a client to "send your content," define the things a project actually needs.

For a small business website, that might mean:

Homepage headline and introduction
Logo in a usable format
Services descriptions
Team photos with permission to publish
Contact details and opening hours
Legal text provided or approved by the responsible party

Each requirement should have a label, a short explanation, an owner, a due date if appropriate, and a status. A photo cannot be "done" merely because someone uploaded a blurry thumbnail.

A minimal data model could look like this:

type RequirementStatus =
  | "requested"
  | "received"
  | "changes_requested"
  | "approved";

type Requirement = {
  id: string;
  projectId: string;
  label: string;
  guidance: string;
  status: RequirementStatus;
  dueAt?: string;
  currentVersion: number;
  approvedAt?: string;
  approvedBy?: string;
};

The important distinction is received !== approved. Upload success is a storage event; approval is a business decision.

Express approval as a state machine

If you model statuses as arbitrary strings that anyone can overwrite, bugs appear quickly. What happens when a client uploads a new version after approval? What if a background job overwrites a human review?

Define explicit transitions:

type State =
  | "requested"
  | "received"
  | "changes_requested"
  | "approved";

type Event =
  | "upload"
  | "request_changes"
  | "approve"
  | "reopen";

type Actor = "client" | "team";

const transitions: Record<
  State,
  Partial<Record<Event, State>>
> = {
  requested: { upload: "received" },
  received: {
    request_changes: "changes_requested",
    approve: "approved",
  },
  changes_requested: { upload: "received" },
  approved: { reopen: "requested" },
};

function nextState(
  state: State,
  event: Event,
  actor: Actor
): State {
  const teamActions: Event[] = [
    "request_changes",
    "approve",
    "reopen",
  ];

  if (teamActions.includes(event) && actor !== "team") {
    throw new Error("Reviewer permission required");
  }

  const next = transitions[state][event];
  if (!next) {
    throw new Error(`Invalid transition: ${state} -> ${event}`);
  }

  return next;
}

Security note: never trust an actor value sent by the browser. In production, derive permissions from the authenticated session or a server-validated client-share grant. Apply the transition inside a transaction and check the expected version so two simultaneous actions cannot silently overwrite one another.

This small state machine gives a developer something concrete to test. For example: can a client approve their own deliverable? No. Can a reviewer request changes after receiving a file? Yes. Can an approved asset be reopened intentionally? Yes.

Treat each upload as a version

A requirement and its files are not the same entity.

The requirement might be "Team photo." Its upload history could be photo-1.jpg, then photo-final.jpg, then team-landscape.jpg. Keep immutable upload records, attach them to the requirement, and store which version is approved.

For each upload, record a generated object key, file size, media type, upload time, checksum when useful, and who submitted it. Don't use the original filename as your storage key; filenames collide and may contain unsafe characters.

When a new version arrives, move the requirement from changes_requested to received and make the new version the one awaiting review. Preserve the prior review history for context.

A client portal should minimize friction

You usually don't need clients to learn a project-management suite just to send assets.

A good client view is a focused page with:

The project's required items.
A short explanation and example for each item.
An input appropriate to the item: text field or file picker.
A visible status and correction comments.
A clear indication that the submission worked.

Mobile matters: clients may already have their photos on a phone. Don't require account creation when a narrower, secure access mechanism can do the job.

A shared URL, however, is not permissionless magic. Use a random, unguessable token, store only a secure representation server-side where feasible, scope it to one project, set an expiry, support revocation, and rate-limit requests. Don't put sensitive personal data in the link itself.

For file uploads, validate size and type server-side, isolate storage by project, scan content where appropriate, and only generate short-lived download URLs for authorized viewers.

Automate reminders, not relationships

A reminder job should query outstanding requirements, not blast the same generic email to every client.

A useful notification says exactly what remains missing or needs changes and provides a direct way to continue. Make the cadence predictable and easy to pause. If a client is blocked because they have not commissioned their team photos yet, another identical reminder will not solve it.

A simple scheduled job can:

for each active project:
  find outstanding requirements
  skip if all items are approved
  skip if a reminder was sent too recently
  send a concise summary of the remaining items
  record the reminder event for audit and rate limits

The event log also helps answer "Did the client receive the request?" without relying on someone's memory.

Define a finish line

Metrics are useful only if they describe progress toward an actual handoff. Consider measuring:

Time from project kickoff to final content approval
Share of uploads approved on first review
Number of correction rounds
Outstanding items by project
Reminder count before completion

If files arrive quickly but require many corrections, improve the item guidance. If guidance is clear but clients can't finish submissions, examine the interface and access flow.

When does this need its own tool?

For one client, a well-structured document and shared folder might be enough. For an agency juggling multiple websites, a requirement-based workflow can save coordination overhead and avoid ambiguous handoffs.

Disclosure: I'm working on ParaDocs, a tool focused on requesting, reviewing, and collecting client content through a simple client link. This article describes a general engineering approach; the sample code is illustrative and is not the source code of ParaDocs.

I'd be interested to hear how other developers manage asset approval and version changes before launching client sites.

Stop Chasing Clients for Website Content: A Practical Intake Workflow

Digital — Fri, 16 Oct 2026 13:35:37 +0000

You can have a great design system, a clean component library, and a perfect deployment pipeline—and still miss your website launch date because a client has not sent their copy.

This is not a technical bug. It is a content intake problem.

If you build websites for clients, here is a simple process you can reuse to collect logos, text, photographs, and approvals without turning every project into an endless email thread.

Why a shared folder is not a complete intake process

A folder answers where files live. It does not tell you:

Which files are still missing.
Which page each piece of copy belongs to.
Whether an image is approved for publication.
Who should provide or review an item.
What needs correction before development can move forward.

Adding another chat thread usually makes this worse. A better approach starts with structured requests.

Step 1: Turn vague requests into individual deliverables

Instead of asking for "all website content," create a short checklist that a busy client can understand.

For a small services website, try:

Area	Request	Expected format
Brand	Primary logo	SVG, PNG, or high-resolution image
Home	Main headline and introduction	Short text
Services	Service names and descriptions	Text per service
About	Company story and team information	Text and optional photos
Contact	Public contact details and opening hours	Text
Portfolio	Approved project photographs	Image uploads
Compliance	Required legal/privacy information	Client-approved text

Keep the requests concrete. "Write an About page" can be intimidating; "Tell us in 3–5 sentences what your company does and whom it helps" is easier to answer.

Step 2: Establish a single source of truth

Choose one place for the client to submit information. It might be a project portal, form, or dedicated collection link.

The goal is not to force the client to adopt your project-management stack. They should be able to click a link, understand the next task, and submit their content.

For internal tracking, give each request a status:

Requested — still waiting for the item.
Received — provided but not yet reviewed.
Revision needed — there is a specific correction to make.
Approved — ready to use.

A collection process that makes missing items visible will be more useful than a random pile of uploads.

Step 3: Reduce the effort required from the client

A few details make a big difference:

Use plain-language labels, not internal jargon.
Explain what a good answer looks like.
Let clients provide partial information and return later, where possible.
Make the process work on mobile.
Avoid unnecessary sign-ups when the client simply needs to upload a file or submit text.

Your client is probably not thinking about your sprint board. They are thinking about running their business.

Step 4: Agree on a realistic submission deadline

Content is a dependency. Treat it as part of the project timeline.

At kickoff, identify the minimum content needed to start design and the final content needed before launch. Explain the consequences of missing each milestone.

For example:

Please send the logo and primary page copy by Tuesday. We can begin layout work once those arrive. Remaining photos and final approvals can follow by Friday.

When following up, list only the missing pieces. It is easier to act on "We still need your logo and three service descriptions" than "Just checking in."

Step 5: Keep review and approval separate from collection

"Uploaded" does not mean "approved."

A photo might lack permission for use, a service description might still be a draft, and contact details might be out of date. Record approvals explicitly rather than assuming that any submitted file is final.

For regulated businesses, get the appropriate legal and privacy information reviewed by the responsible people; a collection checklist cannot replace legal advice.

A message you can send to your next client

Hi [Name],

To keep your website project moving, I prepared a simple checklist of the content we need.

Please use this link to provide the texts, photos, logo, and business details: [link].

You can start with what you already have. Our first content milestone is [date].

If any request is unclear, just reply here and I'll help.

The tool I'm building around this workflow

I'm working on ParaDocs, a bilingual (French/English) tool for freelancers and web agencies. You prepare the content requests, send a single link, and keep track of what a client has submitted. Clients can provide text and files without creating an account.

It offers a 14-day free trial. I mention it because I'm involved in the project, not as an independent recommendation.

Question for fellow developers and agency owners: what is the most painful part of getting content from clients—collecting it, chasing missing items, or getting final approvals? I'd love to hear what workflow works for you.

I Built ParaDocs to Stop Chasing Clients for Files — and Added ChatGPT + MCP Support

Digital — Fri, 09 Oct 2026 14:34:03 +0000

I Built ParaDocs to Stop Chasing Clients for Files — and Added ChatGPT + MCP Support

If you build websites or deliver client projects, you know the real bottleneck is not always code. Sometimes, it's getting the logo, text, photos, and documents you need to finish the work.

The problem: the project is ready, but the content isn't

You've agreed on the scope, set up the project, and started building. Then come the inevitable questions:

Where's the final logo?
Has the client sent the team photos?
Is the homepage copy approved?
Which documents are still missing?

Email threads, chat messages, and scattered folders aren't a great system for answering these questions. They make progress harder to track and follow-ups easy to forget.

I created ParaDocs to make this part of client work much simpler.

A straightforward workflow for collecting client content

ParaDocs is designed for developers, freelancers, designers, agencies, and other professionals who need files and information from their clients.

Here's how it works:

Create a project and list the content you need: copy, logos, photos, PDFs, and other materials.
Send the client a secure link. They can open it on a phone or computer without creating an account or installing an app.
Track each request. See what is missing, received, approved, or needs a correction.
Review and request changes on specific items so the client knows exactly what to update.
Send reminders instead of repeatedly writing follow-up emails.
Download the project content as a ZIP when everything is ready.

For a typical website project, this means you can replace dozens of scattered messages with one organized place for content collection.

What about the reminders?

Chasing client content isn't the best use of your time. ParaDocs includes reminder scheduling, so the system can follow up on missing items while you focus on delivery.

You stay in charge of your client relationship, but you don't need to manually remember every outstanding file.

Why I added a ChatGPT plugin

I also wanted to make the workflow accessible from tools developers already use.

The ParaDocs ChatGPT integration provides operations for working with the account's client and project information. For example, a connected assistant can help you:

List your clients and projects.
Check which requested content items are still pending.
Review project progress.
Request a reminder for a project with missing items.

Instead of opening different screens for every status check, you can ask for the information in a conversation.

And why an MCP server?

Model Context Protocol (MCP) is a way to expose tools to compatible AI clients.

ParaDocs includes an MCP server, allowing compatible assistants to access supported client and project operations through a standardized tool interface. That opens the door to integrating content collection into a wider workflow instead of isolating it in a single dashboard.

The point is not to add AI for its own sake. It's to reduce routine administrative work and give teams more ways to access the information they already need.

Try it on a real project

If you currently use email threads, shared drives, chat messages, or checklists to collect content, I'd love for you to try ParaDocs and tell me what works and what doesn't.

ParaDocs offers a 14-day free trial, with no credit card required.

Try ParaDocs for free →

I'd also love to hear from fellow developers: How do you currently collect files and content from clients?

This article was prepared with AI writing assistance.