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

# Core concepts

> Learn the KayanOS objects that keep public-service data, accountable work, evidence, and decisions connected without duplicating the source of truth.

KayanOS works best when people use the same words for the same things. A service request is not a task; a task is not a calendar event; a file is not a permission; and a notification is not proof of a decision. This guide defines the building blocks so your team can model a service clearly before it creates screens, forms, or reports.

The examples use the Citizen Services Directorate request `CSR-2026-00042`. Its path is simple: a request is received, checked, assigned, inspected when necessary, decided, communicated, and closed. The same model can support permits, complaints, maintenance, licensing, project follow-up, or workforce operations.

## Goal

Understand how people, records, work, evidence, and access connect so that a member can move from a notification to the correct record and know what to do next.

## The shared vocabulary

| Term                    | Meaning in KayanOS                                                                             | What it is not                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Organization            | The workplace context that owns members, data, settings, and access rules                      | A generic label that grants a member access to every record                     |
| Member                  | A staff identity in the organization, with assignments, roles, and available actions           | A citizen or applicant unless you deliberately model that person as a record    |
| Role                    | A reusable set of permitted verbs for resources at an approved scope                           | A job title that automatically grants every capability                          |
| Scope                   | The bounded part of the organization, hierarchy, form, or resource where a verb applies        | A visual filter that can be ignored when saving                                 |
| Application and section | The organization’s navigation structure for related entities, forms, and dashboards            | The data itself or a substitute for a permission check                          |
| Entity                  | A reusable definition of a kind of operational record, such as service requests or inspections | One individual citizen request                                                  |
| Record                  | One stored item of that entity, such as `CSR-2026-00042`                                       | A temporary popup, toast, or dashboard card                                     |
| Field                   | One named value on a record, such as status, owner, location, serial ID, or amount             | A translated title; expressions use stable field keys rather than labels        |
| Relation                | A controlled connection between records, such as a request and its inspections                 | A pasted paragraph describing another record                                    |
| Form                    | A designed way to collect or update data                                                       | The sole durable source for a decision that belongs on an entity record         |
| Form session            | One person’s in-progress or submitted interaction with a form                                  | A replacement for the service lifecycle                                         |
| Status                  | The approved current stage of a record or task                                                 | A free-text note with no accountable meaning                                    |
| Task                    | A piece of accountable work with a role, due date, status, and activity                        | The service case itself or a legal approval by default                          |
| Event                   | A planned time window, meeting, inspection, or review                                          | Evidence that the event took place or that an external invitation was delivered |
| Library item            | A controlled file, folder, or space holding evidence or approved material                      | A public-access bypass or a substitute for record fields                        |
| Notification            | A prompt that points to relevant work                                                          | The work, evidence, or decision it announces                                    |

## Start with the durable record

The primary record is the answer to “What are we managing?” In the Citizen Services Directorate scenario, it is **Citizen Service Request**. It holds durable facts that staff must search, review, filter, report on, and retain:

* the human reference `request_id`, generated by the Serial ID field;
* service category, requester path, location, and submitted information;
* current status and accountable owner;
* requested amount, fee rate, and a calculated estimated fee where the policy requires it;
* links to inspections, documents, tasks, and other related operational work; and
* the final decision, decision date, and citizen-facing outcome where applicable.

Use a dedicated entity when related work has its own lifecycle. An inspection should be a related record when it needs an inspector, scheduled date, location, findings, attachments, and a status separate from the request. Do not place a series of unrelated inspection notes in one long-text request field if staff must later count, filter, assign, or audit them.

## Choose the right object for each action

When designing a service, ask where a fact should survive after the interaction ends.

| Need                                    | Recommended object                                   | Example                                                                  |
| --------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
| Collect a citizen’s initial information | Form that creates or updates the request record      | Citizen intake asks for category, location, and supporting files         |
| Give staff an issued reference          | Serial ID field on the request entity                | `CSR-2026-00042` appears in a letter and service conversation            |
| Derive a repeatable value               | Calculated field on the entity                       | `estimated_fee` derives from the requested amount and approved rate      |
| Assign a specific next action           | Task related to the request                          | “Check uploaded evidence by 14:00” is assigned to the Registry Officer   |
| Reserve a time with internal colleagues | Calendar event                                       | Field inspection at a service-center room with inspector and manager     |
| Keep evidence in an approved place      | Library file/folder or an approved record file field | Inspection report and photograph bundle in the restricted request space  |
| Ask a quick coordination question       | Internal chat                                        | Inspector asks whether the request location was corrected                |
| Record the authoritative finding        | Request or inspection record                         | Inspector saves the verified address and inspection outcome              |
| Alert someone to work                   | Notification                                         | The manager receives a task-assigned notification that links to the task |

The rule is simple: coordinate in a message, but record the operational result in the entity or task that owns it. A chat message can create a task from its text, but the task still needs a clear owner, due date, and relationship to the request.

## Fields, labels, and keys

People see field titles such as **Request ID**, **Estimated Fee**, or **Inspection Date**. Builders also maintain stable keys such as `request_id`, `estimated_fee`, and `inspection_date`. A translated title helps a user understand the screen; a key is what calculations, conditions, templates, and integrations use.

Do not change a field title just to make an expression work. Do not use a translated label inside an expression. Keep the key stable, give it a clear title in every active language, and document what valid data looks like. For a full implementation guide, see [Entity fields and layouts](/build/entity-fields-and-layouts), [Serial IDs](/build/serial-ids), and [Calculated fields](/build/calculated-fields).

## Status, task, and decision are different controls

A record status describes the service’s approved stage: for example, **Received**, **Under review**, **Inspection scheduled**, **Decision ready**, or **Closed**. A task assigns work needed to move or verify that stage. A formal decision may additionally require a configured action, signature, or form response.

For example:

1. The request is **Received** after intake.
2. A completeness task is assigned to the Registry Officer.
3. The officer records missing evidence and moves the request according to the approved rule.
4. The Service Manager schedules an inspection and creates the related inspection record.
5. The inspector records findings; the request can become **Decision ready** only when the required evidence exists.
6. The authorized reviewer records the decision through the configured workflow. Closing a task alone does not prove that a formal signature or policy decision happened.

## Access follows the work

KayanOS permissions are based on assigned verbs and scopes. The same person may be allowed to list requests in one service center, open a specific inspection, update only their assigned work, download a file, or see a notification without being permitted to share or delete the underlying item.

Design access with the service path in mind:

* the Registry Officer may create and update intake data in the approved intake scope;
* the Field Inspector may open assigned requests and update inspections in the field-service scope;
* the Records Officer may open and share only the approved evidence space;
* the Service Manager may assign work and update the service status; and
* an administrator manages organization-wide setup but is not automatically the operational owner of every request.

Always test both an allowed route and a denied route. A member should not gain wider record access merely because they can see a sidebar category or receive a notification.

## A practical design check

Before building the next screen, write one sentence for each question:

1. What is the primary record?
2. Which fields are facts, which are calculated, and which are evidence links?
3. Which related records need their own lifecycle?
4. Who owns the next action at every status?
5. Which task, event, or notification helps the owner act without duplicating the record?
6. Which roles can list, open, create, update, share, or delete each resource, and in what scope?
7. What must be visible in Arabic and English for the service to be understandable?

If a question has no answer, delay automation, documents, dashboards, and external communication until the core model is clear.

## Safe testing

Create one controlled request with synthetic information. Add one inspection, one task, one event, and one evidence file. Then sign in as a non-owner test member and verify that the member can see exactly the intended records and actions. Record the result before removing the test data and temporary grants.

## Troubleshooting

| Problem                                                 | Check first                                                                                        |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Staff keep putting decisions in chat                    | Identify the record field, status action, or task activity that should hold the durable outcome    |
| A calculation cannot find a field                       | Confirm the stable field key and the calculation context; do not use a translated title            |
| An inspection cannot be filtered or assigned            | It may need to be a related entity rather than a repeated paragraph on the request                 |
| A member sees a notification but cannot open the target | Review the target record’s scope and the member’s open verb; a notification is not an access grant |
| A form submission is hard to report on                  | Confirm that important submitted values are mapped to the correct entity record fields             |

## Related guides

* Build access deliberately in [Roles and access](/start/roles-and-access).
* Learn how the interface exposes available work in [Navigate KayanOS](/start/navigate-kayanos).
* Follow a complete service path in [Explore an example workspace](/start/example-workspace).
* Design entities in [Plan an app before building](/build/plan-an-app) and [Entities](/build/entities).
* Configure formal form actions and signatures in [Form actions, logic, and signatures](/build/form-actions-logic-and-signatures).

![KayanOS workspace showing representative public-service records.](https://kayanos.app/docs-images/en/start/core-concepts.png)