> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/how-it-works/the-estate.md).

# The estate

Every session happens somewhere. The estate is ReSouris's model of where.

```
Tenant
 └── Location        a site — a hospital, a community diagnostic centre
      └── Building
           └── Floor
                └── Area        usually a department
                     └── Space  the room, bay, ward or channel work happens in
```

Five levels, fixed. There is no sixth, and you cannot skip one: a floor is always in a building, and a building is always on a site.

## A space attaches in exactly one of two places

This is the rule that decides how everything else behaves, and it is the one worth reading twice.

**A physical space hangs off an Area.** A room, a bay, a ward. The levels above it — floor, building, location — exist to *locate* that Area. You never attach a space directly to a floor or a building, even though it might feel natural to.

**A space that is not part of the estate hangs off the Tenant.** Working from home. A remote reporting channel. A virtual clinic. These are real places work happens and they are not anywhere, so they belong to the trust as a whole.

That second case is not an unfilled field. It is a deliberate answer, and it has a consequence worth knowing: because a trust-held space sits *above* every department, **every department can use it and none of them owns it**. That is usually what you want for home working and remote reporting.

The Estate page shows these as two separate groups — the site tree, and a section headed **Held by the trust** — precisely so the second group does not read as leftovers of the first.

## An Area is usually a department, and sometimes nobody's

Most Areas correspond to a department: Cardiology, Radiology, the Endoscopy unit. The Area carries that relationship, and a space reaches its department *through* its Area rather than keeping a second copy of the answer.

But an Area may have **no department at all**, and this is supported on purpose. A shared main reception, a corridor of interview rooms, a staff room — these are real Areas that no single department owns. ReSouris shows them as *"no department — shared"* rather than leaving a blank that looks like missing data.

If Areas were required to have an owner, a trust with a shared reception would have to invent one.

## Three separate facts about a space

A space carries three things that are easy to conflate. They are independent, and each answers a different question.

| Fact           | Example                                      | Who decides            | What it drives                    |
| -------------- | -------------------------------------------- | ---------------------- | --------------------------------- |
| **Category**   | `room`, `bay`, `ward`, `channel`             | ReSouris — a fixed set | What the scheduler may do with it |
| **Type name**  | "Cath lab", "MRI machine room", "Ward round" | You — free text        | What the label says               |
| **Assignment** | Trust-assigned, ad-hoc                       | You                    | Whether it is reliably available  |

### Why the type name is free text

Because departments do not agree, and they should not have to.

Cardiology says *cath lab*. Radiology says *modality*. An endoscopy unit says *procedure room*. All three are `category = room` underneath — which is what the scheduler reasons about when it works out that two sessions cannot use the same place at the same time — but none of them says "room" out loud.

So the category is a fixed set the system understands, and the type name is whatever your department calls it. Adding a new word does not require anything from us.

**A space that has never been given a type name is not blank.** It falls back to its category's own word, so an unnamed room reads "Room" and an unnamed channel reads "Channel". The label is always something.

### Why a channel is not a place

A `channel` is the category for something that is not somewhere: home working, a remote reporting queue, a monitoring feed. Channels attach to the tenant and ReSouris will refuse to put one inside a building — not as a validation quirk, but because a "Working @ Home" on Level 2 is a false statement about the world.

## Off-site is a place. "Nowhere" is not.

A Location can be flagged **off-site**, and this means *not this site* — a community diagnostic centre, a partner hospital, a satellite clinic. It is somewhere; it is just somewhere else.

That is a different claim from a space held by the trust, which is not anywhere at all. ReSouris used to run both through a single boolean and could not tell them apart. If your trust runs a diagnostic centre, the distinction matters constantly: a CDC has an address, a floor plan and rooms you can book, and none of that is true of a reporting channel.

## Space codes are unique within their parent, not the trust

Two buildings may each have a "Room 1", and a trust should not have to rename one of them to satisfy a database.

So a space code is unique **within its Area**. Trust-held spaces, which have no Area, are unique within the tenant instead — because otherwise every `HOME` and `ONLINE` code would be free to collide with every other.

## Authoring the estate

Both routes need the **`admin.estate.write`** permission, which is granted to tenant administrators. Platform operators deliberately do not have it: a trust's description of its own buildings is not a platform operator's to write.

### One at a time

From **Organisation → Estate**, each level carries **Edit** and an **Add** control for the level below it. Renaming is separate from re-parenting on purpose — moving a floor into another building would silently move every space under it, and no rename form says that is what you are doing.

### From a spreadsheet

**Organisation → Estate → Import** takes a CSV with one row per Area, carrying the whole path down from the site — which is the shape an estate spreadsheet is usually already in.

| Column                                  | Required | Notes                                             |
| --------------------------------------- | -------- | ------------------------------------------------- |
| `location`, `building`, `floor`, `area` | Yes      | every level's parent is mandatory                 |
| `ods_site_code`                         | No       | the national code for the site                    |
| `is_onsite`                             | No       | defaults to true                                  |
| `department`                            | No       | matched by name; blank means the Area is nobody's |
| `space_code`                            | No       | must already exist — see below                    |
| `space_type_name`                       | No       | the department's word for it                      |
| `space_assignment`                      | No       | `trust_assigned` or `ad_hoc`                      |

Two behaviours to rely on:

**The whole file is one transaction.** If any row is invalid the upload is refused and *nothing* is written. A part-loaded estate is worse than no estate — told "212 of 400 rows", you cannot work out which 188 are missing without diffing the file against the tree by hand.

**Re-uploading is safe.** Rows are matched by name within their parent, so a corrected file updates what is there rather than duplicating it. Fix the typo, upload the same file again.

**The import places spaces; it does not create them.** A `space_code` must already exist in the [Spaces](/set-up-what-you-schedule/manage-spaces.md) catalogue. A space carries a category that drives what the scheduler may do with it, and guessing one from a spreadsheet column would put a scheduling decision into your model on the strength of a typo.

## Related

* [Spaces — the catalogue](/set-up-what-you-schedule/manage-spaces.md)
* [Resource management model](/how-it-works/resource-management-model.md)
* [Roster lifecycle](/how-it-works/roster-lifecycle.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.resouris.com/how-it-works/the-estate.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.