# Organisational hierarchy

## What is the organisational hierarchy?

Nuvolos is organised into three hierarchical levels:

1. **Organisations** — administrative containers representing a customer entity (e.g. a university).
2. **Spaces** — self-contained projects within an organisation (e.g. a course, a research project, or a dataset).
3. **Instances** — parallel work environments (branches) within a space.

When you subscribe to Nuvolos, these are set up for you as part of the signup process.

## Organisations

An organisation is the highest level in Nuvolos. When you log in, you first choose an organisation, then select a space to work in.

By default, one customer entity (e.g. a university) corresponds to one organisation. In practice, a legal entity may have multiple organisations — for example, to separate different vendor dataset licenses. Organisations own all data and files created by their members.

### Organisation access control

An organisation has two types of members:

* **Organisation managers** oversee the organisation's assets. They can create and delete spaces, request new vendor datasets, and invite faculty members. Managers have view access to all instances in all spaces, giving them read access to all data in the organisation.
* **Faculty members** can create new spaces (becoming space administrators automatically) and invite colleagues or students to spaces where they are administrators.

## Spaces

A space is a self-contained project within an organisation, encapsulating both data and software. Spaces can be created for a course, a summer school, a research project, a dataset, or any other activity. Each space contains one or more [instances](#instances), which are separate work environments that allow for access control and sharing between space members.

Each space consumes resources — compute time, file storage, database storage, and optionally credits for high-performance workloads. These resources are tracked and billed through *resource pools* (see [Resources and the hierarchy](#resources-and-the-hierarchy) below).

### Space access control

Access to space contents is controlled at the instance level. Each space has one or more **space administrators** with special privileges:

* Invite other administrators, editors, and viewers to any instance in the space.
* Create new instances.
* Editor rights on all instances in the space.

The user who creates a space automatically becomes its administrator.

### Space visibility

Spaces have visibility settings that control who can access them. This can only be set on space creation. The default setting is **Private**.

* **Public** — available to all organisation members, including external members. All users automatically become viewers of the master instance.
* **Faculty-only** — accessible only to faculty members of the organisation. Faculty automatically become viewers of the master instance. Typical example: a vendor dataset with a faculty-wide licence.
* **Private** — accessible only to users explicitly invited by the space administrator. Only organisation managers have automatic view access.

## Instances

Instances are parallel work environments (branches) within a space. You can create as many instances as you need, allowing a project to be divided into separate experimental runs, different approaches to a codebase, or different versions of an application.

Instances can be captured in [snapshots](https://docs.nuvolos.com/features/nuvolos-basic-concepts/snapshots) for versioning and distribution. You can transfer files, code, applications, or other data between instances, and revert to previous snapshots as needed. A main branch can hold tested results while each researcher works in their own branch.

In teaching use cases, instructors and students typically use different instances, forming separate branches of the same teaching material.

### Instance access control

Each space has a **Master** instance created automatically — the primary working instance that acts as the source of truth. The Master instance cannot be deleted, except if the entire space is removed.

In education spaces (courses), a second special instance called **Distributed** is also created automatically. The Distributed instance is used by the [distribution process](https://docs.nuvolos.com/features/nuvolos-basic-concepts/distribution) to deliver materials and collect assignments. It is only relevant in teaching workflows — research and dataset spaces do not use it. For details, see [The Distributed instance](https://docs.nuvolos.com/features/object-distribution/the-distributed-instance).

{% hint style="info" %}
Each user can have one of the following roles per instance:

* **Viewer** — read access to all snapshots, but cannot create or delete them.
* **Editor** — can modify the current state (add, remove, update files, tables, and other objects) and has all viewer rights.
  {% endhint %}

## Use cases

The three-level hierarchy supports a range of workflows:

* **Institution-wide vendor data** — vendor datasets reside in the organisation. Organisation managers can see all data across all spaces.
* **Teaching a course** — faculty members create a space per course and become its administrator. Students are invited as members. Separate instances can be created per student for assignments, or multi-user instances for group work. Teaching assistants can be given the space administrator role.
* **Managing a research project** — researchers create a space per collaboration and invite collaborators (including from other organisations). Each collaborator can work in their own instance and share results when ready.
* **Private workflows** — faculty members create private spaces where only organisation managers have automatic view access.

For more information on user roles, see the [Roles](https://docs.nuvolos.com/administration/roles) section.

## Resources and the hierarchy

Resource consumption in Nuvolos is tracked through [resource pools](https://docs.nuvolos.com/pricing-and-billing/resource-pools-and-budgets), which act as cost centres. Resource pools map onto the organisational hierarchy at two levels:

* **Organisation-level mapping** — an entire organisation is mapped to a resource pool. All resource usage across all spaces in the organisation is billed against that pool. There is always a default resource pool associated to every organisation and any new space created in it automatically inherits this mapping.
* **Space-level mapping** — individual spaces can be mapped to a different resource pool. This allows, for example, a researcher with their own grant to bill high-performance computation against a separate budget.

The resources tracked per pool include:

* **CU (Compute Units)** — compute time consumed by application runs using "Included" sizes. Each subscription includes a CU capacity; usage beyond it is charged in credits. See [CU limits](https://docs.nuvolos.com/administration/monitoring-resource-usage/ncu-limits-and-capacities).
* **File system storage** — total Nuvolos file system (NFS) storage used across all spaces in the pool. Exceeding the limit triggers daily credit charges. See [File system limits](https://docs.nuvolos.com/administration/monitoring-resource-usage/file-system-limits-and-capacities).
* **Resting storage** — storage used by [rested spaces](https://docs.nuvolos.com/administration/space-management/resting-spaces) (inactive spaces moved to cheaper storage). See [Resting limits](https://docs.nuvolos.com/administration/monitoring-resource-usage/resting-limits-and-capacities).
* **Credits** — used for high-performance (credit-based) application sizes, database computation, and any overage beyond CU or storage limits.

{% hint style="info" %}
Resource pool managers can monitor usage across all mapped spaces from the **Resources** dashboard (available in the user menu). Space administrators can see detailed usage for their own spaces. See [Monitoring resource usage](https://docs.nuvolos.com/administration/monitoring-resource-usage) for details.
{% endhint %}