Plan an app before building - KayanOS Documentation

Start with an outcome the team can measure

An application is not a collection of screens. It is a controlled way to move a record from an initial state to a clear outcome with the right evidence, owner, and review point. Write one sentence before opening the builder:

“The team can receive, assess, decide, and report on [work type] within [target], while each decision has an accountable owner and evidence.”

Examples:

“The licensing team can receive a permit request, schedule an inspection, record conditions, and issue a reviewable decision.”
“The maintenance team can accept a fault report, route it to a district, record the visit, and measure time to completion.”
“The HR team can request leave, check coverage, record approval, and keep the employee and manager informed.”
“The project office can track a project change, assess its budget impact, approve it, and show open changes on a dashboard.”

Use the same planning canvas for every app

Design question	What to decide	Example for a permit service
Outcome	What is the completed result?	approved, rejected, or returned permit request
Primary record	What item moves through the process?	permit request
Supporting records	What has its own owner or lifecycle?	inspection, condition, appointment, decision letter
Actors	Who submits, works, reviews, and administers?	applicant, intake officer, inspector, reviewer, administrator
Status	What are the meaningful stages?	draft, received, assessment, inspection, decision, closed
Evidence	What proves the result?	attachments, findings, signed decision, timestamps
Boundaries	What must stay restricted?	personal data, inspection evidence, internal notes, payroll or budget data
Measure	How will the team know it improved?	time to first review, backlog by stage, overdue inspections, decision rate

If you cannot answer a row, keep the first release smaller. It is better to launch a focused request-to-decision path than a large model with no agreed owner or status meaning.

Detailed example: licensing and inspection service

1. Define the record map

Entity	Why it exists separately	Key relationships
Permit requests	One submitted request and its current decision	relates to applicant, site, inspection, and decision
Applicants	A person or organization may submit several requests	relates to requests and contact preferences
Sites	One location can have repeated inspections or permits	relates to requests and inspections
Inspections	A visit has its own schedule, inspector, findings, and result	relates to request, site, and assigned member
Decisions	A decision has reviewer, date, conditions, and document output	relates to request and reviewer
Follow-up tasks	A required action must be owned and dated	relates to request or inspection and assigned member

2. Define the first-release status lifecycle

Do not start with dozens of statuses. Use the smallest set that tells a worker what to do next.

Draft → Received → Assessment → Inspection required → Decision ready → Closed
                         ↘ Returned for information ↗

For every status, write:

who can move the record into it;
the evidence required before the move;
the next accountable role;
whether the record remains editable;
the dashboard or report question it must answer.

3. Design the entry experience

The intake form should ask only for data needed to route the work: category, site, contact method, description, and evidence. Do not ask an applicant to choose internal owner, internal priority, or decision status. The internal review layout can expose additional fields: assigned member, risk level, inspection window, internal notes, and decision controls. One entity can support both experiences without showing every field to every person.

4. Define decisions before automation

Write the human decision first:

Decision	Required inputs	Accountable role	Recorded outcome
Is the request complete?	category, site, required evidence	intake officer	received or returned for information
Is an inspection needed?	category, risk, site characteristics	service manager	inspection required or decision ready
Is the inspection acceptable?	finding, photos, recommendation	inspector or reviewer	pass, fail, or follow-up
Can a permit be issued?	complete evidence, conditions, reviewer	authorized reviewer	approved, rejected, or returned

Only after this table is clear should you add a notification, task, calculated date, document template, or automation. Automation should carry out a defined, reviewable next step—not invent the policy.

5. Plan the measures

Pick measures that help the team act, not vanity totals.

requests received and closed by week;
backlog by current status and owner;
average time from received to first review;
inspections due this week and overdue;
returned requests grouped by missing evidence;
decision outcomes by category and location.

Each measure needs a field and status design that supports it. If “overdue inspection” matters, you need a scheduled Date-time range, a status, and a clear definition of completed.

Adapt the pattern to other work

If you are building…	Primary entity	Supporting records	Useful measure
A maintenance desk	work order	site, visit, part, follow-up task	time to completion by district
A social-service intake	service case	appointment, assessment, referral	cases awaiting assessment
An HR leave process	leave request	coverage task, approval	leave awaiting manager decision
A procurement request	purchase request	quote, approval, budget allocation	request value awaiting approval
A project change flow	change request	impact assessment, decision, task	open changes by budget impact

The record map changes; the planning questions do not.

Build in deliberate increments

Release 1: make the record usable

Create the primary entity, a serial reference, essential fields, a small status lifecycle, and one entry form or layout. Test the full path with a non-production record.

Release 2: make responsibility visible

Add member ownership, due dates, tasks, restricted notes, and the review layout. Confirm each role sees only what it needs.

Release 3: make the work measurable

Add dashboards, reports, calculated indicators, and document output. Re-check that the fields used for reporting are structured and consistently entered.

Release 4: automate only stable decisions

Add notifications, record creation, or routing after the manual workflow has run successfully. Keep a reviewer in the loop where the result creates an obligation, changes a status, or communicates outside the organization.

Planning checklist

One sentence describes the outcome and target.
The primary entity and every supporting entity have a distinct lifecycle.
Each status tells a worker what to do next.
Each sensitive field has an access decision.
The initial form does not ask for internal-only data.
The first dashboard questions are known before building calculations.
A non-production record proves the normal path and one exception path.

Next steps

Create the record model in Entities.
Choose detailed field types in Entity fields and layouts.
Build the capture path in Forms.

​Start with an outcome the team can measure

​Use the same planning canvas for every app

​Detailed example: licensing and inspection service

​1. Define the record map

​2. Define the first-release status lifecycle

​3. Design the entry experience

​4. Define decisions before automation

​5. Plan the measures

​Adapt the pattern to other work

​Build in deliberate increments

​Release 1: make the record usable

​Release 2: make responsibility visible

​Release 3: make the work measurable

​Release 4: automate only stable decisions

​Planning checklist

​Next steps