The one-page workflow spec we write before building any internal web app

Most internal web apps we are asked to build start life as a spreadsheet, a WhatsApp group, or both. The owner knows something is broken. Orders slip, follow-ups get missed, two people update the same row. But when we ask "what should the app do?", the answer is usually a list of screens.

Screens are the wrong starting point. A screen list hides the hard parts: who is allowed to do what, what happens when a step fails, and which numbers the owner looks at on Monday morning.

So before any design or code, we write one page instead of a 30-page SRS: a page that the business owner, the developer and the person doing the work every day can all read and argue about. The template and how we fill it are below.

The template

WORKFLOW: <one line, verb + object, e.g. "Track service visits from booking to payment">

TRIGGER: what starts it (a call, a form, an order, a date)
DONE WHEN: the exact state that means this item is finished

PEOPLE (role -> what they can do)
- ...

STEPS (happy path, numbered, max ~10)
1. ...

WHEN IT GOES WRONG (one line each)
- ...

DATA WE KEEP (fields, and where they come from today)
- ...

CONNECTS TO (other tools, direction of data)
- ...

THE MONDAY NUMBER: the one report the owner opens every week
OUT OF SCOPE FOR V1: things we agreed not to build yet

That's it. If it doesn't fit on one page, the workflow is probably two workflows.

1. One workflow, written as a verb

"CRM" is not a workflow. "Follow up every inquiry within 24 hours until it becomes a quote or is closed" is. Writing it as a verb plus an object forces you to pick one job. Everything else goes into a later version.

2. Trigger and "done when"

These two lines catch more confusion than anything else on the page. If the sales head thinks a lead is "done" when a quote goes out and the owner thinks it's done when the advance is paid, your status field, your reports and your reminders will all be wrong. Agree on it in writing.

3. Roles, not people

List roles with verbs: "Field staff: view own visits, mark complete, upload photo." "Manager: assign visits, edit any visit, see team report." Every role is extra screens, permissions and test cases, so this list is also the biggest lever on effort. When a client wants six roles, we ask which two are needed in week one.

4. Happy path in ten steps or fewer

Number the steps. Use the words the team already uses ("job card", not "service entity"). If someone on the floor reads it and says "that's not how we do it", you just saved a sprint.

5. When it goes wrong

This is the section most specs skip, and where most of the build time hides. One line each:

• Customer cancels after the visit is assigned
• Payment link fails or is paid twice
• Staff member leaves and has open items
• Two people edit the same record

You don't need the solution yet. You need the list, so nobody is surprised in week six.

6. Data we keep, and where it lives today

Write each field and its current home: "Customer phone: Excel column C, sometimes in WhatsApp only." This tells you how much cleanup the import needs. Data migration is the line item that gets underestimated most often in our experience, because old sheets have duplicates, merged cells and three date formats.

7. Connects to

Payment gateway, WhatsApp Business, Tally, a shipping partner, Google Sheets. Write the direction too: "we send invoice to Tally" is different work from "we read stock from Tally". Each connection is its own small project with its own failure cases, so name them now.

8. The Monday number

Ask the owner: "What is the one number you want to see every Monday?" Pending visits older than 48 hours. Quotes sent vs won. Unpaid invoices by age. That one report decides which fields are mandatory, and it gives you a clear test of whether v1 is working.

9. Out of scope for v1

Write down what you agreed not to build. Mobile app, customer login, multi-branch, AI anything. This line protects both sides. It also turns "can we just add..." into a calm conversation about v2.

How we use the page

• We fill it in on a call with the owner and one person who does the work daily. Usually that takes under an hour.
• We turn the steps and roles into a clickable prototype before writing backend code. Changing a prototype is cheap; changing a migrated database is not.
• The page becomes the first section of the written scope, so estimates trace back to roles, steps, connections and data, not to a vague feature list.

When the page shows the client really needs an off-the-shelf tool, we say so. Some workflows are better served by a SaaS subscription than a custom build. If you're unsure which side you're on, this comparison of website vs web app vs SaaS is a good first read.

Why this works

A one-page spec is short enough that busy owners read it, and specific enough that developers can estimate from it. It moves the arguments to the cheapest moment: before anyone has built anything.

We use this page on every custom web app and most software and API projects we take on. Copy the template, change the headings to fit your team, and see how many "small" features turn out to be separate workflows.

Brightcode is a web development team in Delhi NCR that builds websites, ecommerce stores and custom web apps. Got a workflow stuck in a spreadsheet? Send us a short brief.