# Organizations, regions and projects

Catalyst organizes everything you run into three nested scopes — organizations contain regions, and regions contain projects. Together they define how access, infrastructure, and workloads are isolated from one another.

```mermaid
flowchart LR
  subgraph ORG[Organization]
    direction LR
    USERS(Users)
    subgraph R1["Region AWS"]
      direction LR
      P1(Project dev) ~~~ P2(Project prod)
    end
    subgraph R2["Region Azure"]
      direction LR
      P3(Project dev) ~~~ P4(Project prod)
    end
    subgraph R3["Region GCP"]
      direction LR
      P5(Project dev) ~~~ P6(Project prod)
    end
    USERS ~~~ R1
    R1 ~~~ R2
    R2 ~~~ R3
  end
```

## Organizations

An **organization** is the top-level management unit in Catalyst, where you manage your plan, users, and access control. A single organization can span regions across AWS, Azure, GCP, and on-premises, giving platform teams one place to govern workloads across clouds and environments.

Both users and API keys use role-based access control, with roles that can be assigned globally or scoped to specific projects. For the full role matrix, SSO, and API key management, see [Identity and Access](https://docs.diagrid.io/operate/platform-operations/identity-and-access).

## Regions

A **region** is a physically isolated unit of the Catalyst data plane that hosts a set of projects together with the backing infrastructure they share. An organization can contain multiple regions, typically separated by:

- **Cloud provider** — run regions on AWS, Azure, and GCP, all managed from the same organization.
- **Geography** — keep workloads and data close to your users, or within a compliance boundary.
- **Environment** — isolate dev/test from production at the infrastructure level.

Each region is an isolated Kubernetes cluster with its own infrastructure and capacity. For day-2 operations on regions, see [Regions](https://docs.diagrid.io/operate/platform-operations/regions).

## Projects

A **project** is the unit of workload isolation within a region. Apps, components, and policies are all scoped to a project, and resources in one project cannot be accessed from another. A region contains multiple projects, typically used to separate environments (dev, staging, production) or teams.

Each project also exposes the network details applications use to reach it: an **HTTP endpoint** and **gRPC endpoint** for the Catalyst Dapr APIs, shared by every app in the project, plus an **egress address** that Catalyst uses as the source IP when it calls back into your applications. See [Connect to Catalyst](https://docs.diagrid.io/develop/connect) for how applications wire them up.

For day-2 operations on projects (creating, listing, deleting), see [Projects](https://docs.diagrid.io/operate/platform-operations/projects).

## Self-hosted (Catalyst Enterprise)

When you run [Catalyst Enterprise](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted) in your own infrastructure, these conceptual scopes map directly onto Kubernetes:

| Catalyst concept | Kubernetes equivalent |
|---|---|
| **Organization** | A logical management boundary (no direct Kubernetes object) |
| **Region** | A Kubernetes cluster running a fully managed Dapr deployment |
| **Project** | A Kubernetes namespace |

Because a project maps to a namespace, the `namespace` field on resources you apply declaratively (such as configurations or workflow access policies) equates to the project name. You manage these resources through the `diagrid` CLI and the Catalyst console, not through `kubectl`.

For the full self-hosted topology — control plane, data plane, workload identity, and network policies — see [System Architecture](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/system-architecture).