Concepts/Location: Difference between revisions

A '''location''' is a physical place inside a facility where care happens or resources sit — a building, a wing, a ward, a room, or a single bed. Locations form a nested tree that mirrors the real geography of your facility, so the platform can answer questions like "which bed is this patient in?" and "who is allowed into this ward?".

== What it represents ==

In Care's FHIR-aligned model, a location maps to the '''Location''' resource. Each location records:

* '''What kind of place it is''' — a name, a description, and a physical form such as ward, room, or bed

* '''Where it sits in the tree''' — its parent and children, since every place can nest inside a larger one and hold smaller ones, with no fixed limit on depth

* '''Whether it is usable''' — and, for beds and rooms, a finer operational state (occupied, unoccupied, housekeeping, contaminated, isolated, closed)

* '''Who is in it''' — the encounter, if any, currently occupying the place (most meaningful for a bed)

* '''Who may work there''' — the organizations granted access to this part of the facility

A location is a ''place'', not a ''department'' or a ''team''. A ward as a physical space is a location; the unit of staff and responsibility that runs it is an [[Concepts/Organization|organization]]. The two are linked, but they are different primitives — you nest places inside places, and you grant an organization access to a place.

== Classification ==

Two attributes describe what a location ''is'', and they are fixed when it is created.

* '''Mode''' separates a ''kind'' of place from a concrete ''instance'' of one. A <code>kind</code> is a class of location — &quot;a ward&quot;, &quot;a building&quot; — and can contain children. An <code>instance</code> is one specific place — &quot;Bed 12&quot;, &quot;Room 4&quot; — and is a leaf: instances cannot have children.

* '''Form''' is the physical type, drawn from a standard FHIR list: site, building, wing, ward, level, corridor, room, bed, vehicle, house, and more. This is what lets a deployment model the difference between a wing and the beds inside it.

Beds are not a separate concept in Care — a bed is simply a location whose form is <code>bed</code> and whose mode is <code>instance</code>. The whole facility map, from building down to bed, is one uniform tree.

== Lifecycle ==

A location's own status is deliberately simple — it describes whether the place exists and is usable, not whether someone is in it.

<syntaxhighlight lang="text">active → inactive

(unknown)</syntaxhighlight>

* '''active''' — the location is live and can be used for encounters and assignments

* '''inactive''' — retired from routine use but kept for history; it does not disappear

* '''unknown''' — status has not been determined

Separately, beds and rooms carry an '''operational status''' that changes far more often: occupied, unoccupied, housekeeping, contaminated, isolated, or closed. This is the day-to-day signal a bed-management board reads, and it is distinct from the location simply being <code>active</code>.

== How it connects ==

Locations are the spatial backbone that other primitives attach to.

* '''Encounters''' occupy locations over time. When a patient is admitted to a bed, a record captures ''which'' place, ''when'' occupancy began, and ''whether'' it is planned, active, reserved, or completed. From these records the platform derives a location's current encounter and whether it is free or reserved — which is how a bed knows it is taken.

* '''Organizations''' are granted access to locations. Giving a [[Concepts/Facility Organization|facility organization]] access to a ward lets every user under that organization work in the ward and its descendants, through the role they hold. Access flows ''downward'': grant it at the building and it reaches every room and bed inside.

* '''Facility''' owns the whole tree. Every location belongs to exactly one [[Concepts/Facility|facility]], and the root of its tree sits at the facility level.

One important consequence of the tree: access and other inherited properties cascade to descendants asynchronously. When you change who can reach a ward, the rooms and beds beneath it settle a moment later rather than instantly — expect it to be eventually consistent, not immediate.

== Permissions ==

Access to locations is governed by facility-level permissions. Viewing the location tree is open to most clinical roles; changing the tree or its access grants is reserved for administrators and senior staff.

! Permission

! Description

! System Roles

| <code>can_write_facility_locations</code>

| Create, edit, or delete a location, and add or remove an organization's access to one (add a ward, room, or bed; change status; grant org access)

| Facility Admin, Admin, Staff

| <code>can_create_facility_organization</code>

| Create a root location (one with no parent) at the top of the facility tree

| Facility Admin

| <code>can_list_facility_locations</code>

| View a facility's locations, the location tree, and which organizations have access to a location

| Admin, Doctor, Facility Admin, Administrator, Admin, Staff, Nurse, Staff, Pharmacist

| <code>can_manage_facility_organization</code>

| Grant or change an organization's access to a location

| Facility Admin, Administrator

| <code>can_write_encounter</code>

| Assign or move an encounter (a patient) to a location, such as placing them in a bed

| Admin, Doctor, Nurse, Facility Admin

Roles are granted through facility and organization memberships, and because location access follows the tree, a permission held at a parent location cascades down to everything nested beneath it.

== FHIR reference ==

Care's location aligns with the FHIR [<nowiki/>https://build.fhir.org/location.html Location] resource, including its mode (<code>kind</code> / <code>instance</code>), physical-form codes, and operational-status codes for beds and rooms.