# Concepts

Reference vocabulary for using compose_run.

<Mermaid
  chart={`erDiagram
    ORGANIZATION {
        uuid id PK
        string name
        string slug
    }
    USER {
        uuid id PK
        uuid organization_id FK
        string email
        string role
    }
    PROJECT {
        uuid id PK
        uuid organization_id FK
        string name
        string size
        int disk_gb
    }
    STACK {
        uuid id PK
        uuid project_id FK
        string name
        string docker_compose
        string status
    }
    ORGANIZATION |o--o{ USER : "has member"
    ORGANIZATION ||--o{ PROJECT : owns
    PROJECT ||--o{ STACK : hosts
`}
/>

A user belongs to at most one org. There is no multi-org membership. An org
owns projects; each project runs on its own VM and hosts one or more stacks.
Deleting a project deletes its stacks.

## Organization (Org)

Billing and permissions container. An org owns projects, members and API
keys. A user belongs to a single org.

## Project

A logical workspace within an org. Groups related stacks (e.g. `prod`,
`staging`). Identified by a `project_id` UUID.

## Stack

A deployed instance of a `docker-compose.yml`. Identified by a `stack_id`
UUID. Has its own lifecycle (deployments, logs, metrics).

## Deploy (Deployment)

An execution of the deploy pipeline on a stack. Each deploy has a status
(`pending`, `running`, `success`, `failed`).

## API key

An authentication token attached to an org. Carries one or more **scopes**
(e.g. `deploy`) that define its permissions. Used by the
[public webhooks](/developer/webhooks-overview).

## Scope

Granular permission carried by an API key. The `deploy` scope authorizes
triggering redeploys via webhook.