= Multi-Tenancy and Organizations

The portal is fully multi-tenant aware. Everything happens in the context of an "Organization".
This context dictates multiple parameters, for example which service providers or service offerings are available to the organization.

Users of the platform must be part of one or multiple organizations and can have different access rights in different organizations.

Some parts of the portal are global:

* Organizations
* Users

Everything else happens in the context of an organization.
Therefore, organizations are a main part of the user interface and will be prominently displayed and enforced.

Users can either be manually granted access to an organization by an organization admin, or they can get an invitation which allows them to join the organization with a certain role.

Potential candidates to implement this functionality:

* https://django-organizations.readthedocs.io/[django-organizations: multi-user accounts^] (Has some https://django-organizations.readthedocs.io/en/latest/reference/backends.html[invitation^] functionality)
* https://github.com/raphaelm/django-scopes[django-scopes] (Safely separate multiple tenants in a Django database)
* https://github.com/dfunckt/django-rules[`rules`^] to realize object-level permissions

== Source of Truth of Organizations

Today, VSHN has the notion of organizations in the context of the https://kb.vshn.ch/appuio-cloud/references/architecture/control-api.html[APPUiO Control API^].
We must make sure to not duplicate this concept and be very clear about the source of truth.
Also to prepare for a potential integration of APPUiO features into the portal.

An organization in APPUiO manages:

* A user group in VSHN Account (Keycloak)
* A sales order in VSHN Central (Odoo)
* A Kubernetes namespace in the Control API

The https://github.com/appuio/appuio-cloud-agent[APPUiO Cloud Agent^] connects to the control API via the Kubernetes API to retrieve certain information, for example user group mapping.
We therefore cannot just switch the organization handling to the Portal.
Should we decide to do so, we would need to have a proper migration path.

As organizations must also be available in the portal, we must keep the APPUiO Control API and the portal database in sync: Creating, updating and deleting an organization in the Portal must do the same in the APPUiO Control API, and vice versa.
This will imply some form of synchronization mechanism, with all its downsides of data consistency.

The main source of truth is the APPUiO Control API and has precedence over the data in the portal (at least from now, that's subject to future changes).
This includes the https://kb.vshn.ch/appuio-cloud/references/architecture/control-api-billing-entity.html[BillingEntity^] as well.

== Organization Origin

For some functionality, like filtering available control planes or service plans, we need to know the origin of an organization.
As this is a feature specific to the portal, we track the origin of the organization in the portal.

Organization origins have a specific configuration, to be managed in the portal.
A default organization origin can be specified, for organizations not having a specific origin configured during creation.

== Organization Origin Configuration

The organization origin configuration specifies certain behavior:

* Which control planes and plans are available to the organization
* Default billing entity