> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan an app before building

> Turn an operational outcome into a small, governed KayanOS application before adding fields, forms, or automation.

## 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.

```text theme={null}
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](/build/entities).
* Choose detailed field types in [Entity fields and layouts](/build/entity-fields-and-layouts).
* Build the capture path in [Forms](/build/forms).

![KayanOS application planning workspace](https://kayanos.app/docs-images/en/build/plan-an-app.png)