Rationalize Protocells content between cells/_index.md and goals.md

Organizations serve as logical boundaries and Cells serve as physical boundaries.

This design integrates three key components: Organizations, Organization Migration, and Cells.

This design integrates three key components: Organizations, Organization Migration, and Cells Infrastructure.

Progress is tracked in the [working epic](https://gitlab.com/groups/gitlab-com/gl-infra/-/work_items/1616).

### Motivation

GitLab.com operates as a single monolithic instance with a shared database, which creates a fundamental scalability

bottleneck.

As GitLab grows, the legacy cell's databases face increasing load and capacity constraints.

Protocells addresses this by enabling horizontal scalability through:

- **Logical Isolation**: Organizations provide a clear logical boundary for customer data and operations.

- **Physical Distribution**: Cells enable distributing Organizations across multiple self-contained GitLab instances.

- **Scalability**: Multiple Cells can operate independently, removing load from the legacy cell and enabling growth.

- **Feature Parity**: Maintaining consistent features across all deployment models (GitLab.com, Self-Managed,

  Dedicated).

#### Goals

- Introduce Organizations as the logical boundary with Organization Isolation to enable data separation.

- Establish a one-to-one mapping between instance and Organization on Self-Managed and Dedicated deployments.

- Deploy multiple self-contained GitLab instances as Cells on GitLab.com, each capable of hosting multiple

  Organizations.

- Ensure cross-organization operations utilize public APIs to maintain isolation boundaries.

- Achieve feature parity for Organizations and Cells across all deployment models.

- Relieve the [legacy cell](goals.md#legacy-cell)'s database.

#### Non-Goals

- Detailed implementation specifications for individual features.

- Regional compliance.

- Multi-Cloud support.

- Organization load re-balancing.

- Global Admins.

- Global settings.

### Proposal

```mermaid

        E -->|"canonical cell updated"| F["Topology Service"]

    end

    subgraph P3["3 · Cells"]

    subgraph P3["3 · Cells Infrastructure"]

        G["Incoming Request"] -->|"routed by org"| H["Routing Logic"]

        H -->|"lookup"| F

        F -->|"cell location"| H

Protocells is built on three pillars:

**1. Organizations**: Introduce Organizations as the logical boundary with

[Organization Isolation](../organization/isolation.md).

This prevents data and operations from crossing Organization boundaries.

Organization context resolution is established for all requests.

On Self-Managed and Dedicated, a one-to-one mapping between instance and Organization is established through the

[Organization ADR](../organization/decisions/007_self_managed_dedicated_single_organization.md).

**Result**: A top-level group, and its child resources (groups, projects and users, and so on) are transferred to its own Organization.

- When this Organization is moved to another cell, pages do not break when references are missing.

  For example, an issue tries to render the author name, but the author (User) was outside of this organization, and was not moved together with this org.

  That issue page should continue to render.

- Similarly, pages on the source cell should not break due to missing references.

  For example, a user in the organization that was moved to another made a comment on an issue in another organization.

  That issue page should continue to render.

| Pillar | Purpose | Result |

| ------ | ------- | ------ |

| 1. Organizations | Introduce Organizations as the logical boundary with [Organization Isolation](../organization/isolation.md). | A top-level group, and its child resources (groups, projects and users, and so on) are transferred to its own Organization. |

| 2. Organization Migration | Enable the movement of Organizations between Cells through the [Organization Data Migration](../organization-data-migration/_index.md) design document. | All data for an Organization are moved from one cell to another, without data loss. The canonical cell for that Organization is updated in Topology Service to switch over. |

| 3. Cells Infrastructure | Deploy multiple self-contained GitLab instances as Cells on GitLab.com through the [Cells Infrastructure](./infrastructure/_index.md) design document. | [Routing logic](http_routing_service.md) directs requests to the appropriate Cell based on Organization. |

**2. Organization Migration**: Enable the movement of Organizations between Cells through the

[Organization Data Migration](../organization-data-migration/_index.md) design document.

Pillar details:

This tooling supports migrating Organizations from the Legacy Cell to new Cells.

It enables horizontal scalability and load distribution across the infrastructure.

**Result**: All data for an Organization are moved from one cell to another, without data loss. The canonical cell for that Organization is updated in Topology Service to switch over.

**3. Cells**: Deploy multiple self-contained GitLab instances as Cells on GitLab.com, as described throughout this document.

Each Cell is capable of hosting multiple Organizations.

Cells operate as independent GitLab instances with their own databases and infrastructure.

**Result**: [Routing logic](http_routing_service.md) directs requests to the appropriate Cell based on Organization.

![Protocells pillars](/images/engineering/architecture/design-documents/protocells/protocells_pillars.png)

[Source](https://excalidraw.com/#json=kIOOzXyJ-snh5P_pK0RGX,xrCYj2lKaXxB79YySTBtbg)

| Pillar | Details |

| ------ | ------- |

| 1. Organizations | Prevents data and operations from crossing Organization boundaries, with Organization context resolution established for all requests. On Self-Managed and Dedicated, a one-to-one mapping between instance and Organization is established through the [Organization ADR](../organization/decisions/007_self_managed_dedicated_single_organization.md). When an Organization is moved to another Cell, pages on both the source and target Cell continue to render when references are missing. For example, an issue whose author (User) was not moved together with the Organization, or a comment made by a moved user on an issue in another Organization. |

| 2. Organization Migration | This tooling supports migrating Organizations from the Legacy Cell to new Cells. It enables horizontal scalability and load distribution across the infrastructure. |

| 3. Cells Infrastructure | Each Cell is capable of hosting multiple Organizations. Cells operate as independent GitLab instances with their own databases and infrastructure. |

This effort does not preclude other complementary efforts to support the legacy cell's database, such as [Data Retention](../../guidelines/data_lifecycle/data_retention.md).

- [**Organization Feature Parity**](https://gitlab.com/groups/gitlab-com/gl-infra/-/work_items/1871): Ensuring Organizations have consistent features across all deployment models.

- [**Cells Feature Parity**](https://gitlab.com/gitlab-org/architecture/readiness/-/blob/main/templates/platform_strategy/cells.md): Ensuring Cells support all GitLab features required for production use.

### Alternative Solutions

#### Multiple Independent Instances

**Pros:**

- Complete isolation between instances.

- Simple to operate.

**Cons:**

- No shared resources or features.

- Difficult to manage multiple instances.

- Does not provide the unified GitLab experience.

### Architecture overview

## Architecture overview

```plantuml

@startuml

## Goals

GitLab.com operates as a single monolithic instance with a shared database, which creates a fundamental scalability

bottleneck.

As GitLab grows, the legacy cell's databases face increasing load and capacity constraints.

The Cells architecture addresses this by enabling horizontal scalability through:

- **Logical Isolation**: Organizations provide a clear logical boundary for customer data and operations, with

  [Organization Isolation](../organization/isolation.md) enabling data separation. Cross-organization operations

  utilize public APIs to maintain isolation boundaries.

- **Physical Distribution**: Multiple self-contained GitLab instances are deployed as Cells on GitLab.com, each

  capable of hosting multiple Organizations. On Self-Managed and Dedicated deployments, a one-to-one mapping between

  instance and Organization is established.

- **Scalability**: Multiple Cells can operate independently, enabling growth and relieving the

  [legacy cell](#legacy-cell)'s database.

- **Feature Parity**: Maintaining consistent features for Organizations and Cells across all deployment models

  (GitLab.com, Self-Managed, Dedicated).

### Scalability

The main goal of this new shared-infrastructure architecture is to provide additional scalability for our SaaS Platform.

Organizations should have the same user experience on our SaaS platform as they do on a self-managed GitLab instance.

### Regions

GitLab.com is only hosted within the United States of America.

Organizations located in other regions have voiced demand for local SaaS offerings.

Cells provide a path towards [GitLab Regions](https://gitlab.com/groups/gitlab-org/-/epics/6037) because Cells may be deployed within different geographies.

Depending on which of an organization's data is located outside a Cell, this may solve data residency and compliance problems.

### Market segment

At this moment, GitLab.com has "social network"-like capabilities that may not fit well into a more isolated Organization model.

| Product     | Minimal impact on contributor workflows           | High     |

| Product     | On-premise like experience                        | Medium   |

| Product     | Minimize breaking changes                         | High     |

| Product     | Enables support for Regions                       | Low      |

| Product     | Limit impact on self-managed customers            | Low      |

| Operational | Provides 10x headroom                             | High     |

| Operational | Provides 100x headroom                            | Medium   |

| Operational | Small Cells                                       | Medium   |

| Migration   | Robust rollback and disaster recovery scenarios   | High     |

| Migration   | Scale existing GitLab.com database                | High     |

| Migration   | Re-balancing of Cells                             | Low      |

| Migration   | Customer can migrate from GitLab.com to Dedicated | Low      |

| Development | Easy usage in development environment             | Medium   |

  or new endpoints, but retaining major aspects of the system to work as before.

  The customer has a way to roll back to a previous known working state.

### Enables support for Regions

Support for Regions should enable us to run GitLab in different availability zones,

or completely different data centers.

This includes, but is not limited to allowing users to create Organizations in Europe, the US West or US East,

and GitLab Inc. to use different cloud infrastructure providers (Google Cloud, AWS) to serve customers.

Cells enable existing customers running Organizations to move their Organization between different deployment regions/data centers that are supported by GitLab on GitLab.com.

### Limit impact on self-managed customers (Omnibus/CNG)

The introduction of Cells should not impact small installations.

Additionally Cells may solve some issues with canaries today, for example not having a way to upgrade Sidekiq code for a subset of users.

### Regions

GitLab.com is only hosted within the United States of America.

Organizations located in other regions have voiced demand for local SaaS offerings.

Cells provide a path towards [GitLab Regions](https://gitlab.com/groups/gitlab-org/-/epics/6037) because Cells may be deployed within different geographies.

Depending on which of an organization's data is located outside a Cell, this may solve data residency and compliance problems.

This includes, but is not limited to allowing users to create Organizations in Europe, the US West or US East,

and GitLab Inc. to use different cloud infrastructure providers (Google Cloud, AWS) to serve customers.

Cells enable existing customers running Organizations to move their Organization between different deployment regions/data centers that are supported by GitLab on GitLab.com.

However, Regions is not part of Cells. Cells is just a small enabler but there

will be other steps required for Regions.

## Glossary

| Term                                | Description                                                                                                                                 | Discouraged Terms                          |