============
Object Model
============

This page describes the key models in Eyrie and how they relate to each other.

Hierarchy: Project → Deployment Group → Deployment
====================================================

The core hierarchy is:

- **Project** (``eyrie.project``) — the top-level organizational unit. Has a
  unique ``slug`` (DNS-safe), an ``owner_id``, and contains all other
  resources.
- **Deployment Group** (``eyrie.deployment.group``) — groups deployments of
  the same type under a project. Has a ``group_type`` (e.g. ``odoo``, ``pgo``)
  and owns scopes, cluster links, and default settings.
- **Deployment** (``eyrie.deployment``) — a single running instance within a
  group. Inherits fields from its group via ``_inherits`` and adds
  instance-specific configuration (scope, branch, image, etc.).

Clusters
========

``eyrie.cluster`` represents a Kubernetes cluster. Clusters are **shared
resources** — they can be linked to multiple deployment groups and deployments
via many-to-many relationships:

- ``group_cluster_ids`` on the deployment group.
- ``cluster_ids`` on the deployment.
- ``deployment_cluster_ids`` on the scope (optional override).

Each cluster has a unique ``uid``, a ``slug`` derived from its name, and a
``state`` lifecycle (draft → init → active → transitioning → cancel → delete).

Namespaces
==========

``eyrie.namespace`` provides UID-based isolation. Every project gets a
namespace, and the namespace ID is propagated to deployment groups and
deployments via related fields. Namespaces ensure that Kubernetes resources
created by different projects do not collide.

Repositories and Branches
=========================

- **Repository** (``eyrie.repository``) — a git repository URL, optionally
  scoped to a project and/or deployment type.
- **Branch** (``eyrie.repository.branch``) — a branch within a repository.
  Deployments reference a branch to track which code to deploy.
- **Image** (``eyrie.repository.image``) — a container image built from a
  repository. Deployments can subscribe to an image to receive auto-re-deploys
  when the image is updated.

Datasources
============

``eyrie.datasource`` represents external data stores:

- **S3-like buckets** — used for backup storage. Provisioned via cloud
  providers and linked to scopes through ``backup_dest_datasource_id``.
- **Database connections** — connection strings for managed databases.

Each datasource has a ``data_type`` (e.g. ``s3like``) and a ``usage``
classification (e.g. ``remote_backup``).

Monitors
========

- **Monitor** (``eyrie.monitor``) — a health check attached to a deployment.
  Monitors have a type (``http_request``, resource-based), thresholds, and a
  state (``ok``, ``warning``, ``error``, ``unknown``).
- **Monitor Log** (``eyrie.monitor.log``) — historical check results. Logs
  are periodically pruned based on the scope's
  ``monitor_log_delete_after_seconds``.

Project Users
=============

``eyrie.project.user`` links a ``res.users`` record to a project with a
**role**:

- **user** — read-only access.
- **developer** — can manage deployments and trigger actions.
- **admin** — full control over the project.

The role hierarchy is enforced throughout the portal API. Deployment-level and
group-level overrides (``eyrie.deployment.user``) allow fine-grained
exceptions.