# Multi‑Org Strategy (Region × Project)

This guide outlines a practical approach to creating and operating multiple Amigo organizations (tenants) by region and project. Use this when you have disjoint user populations (e.g., clinical cohorts, product lines) and/or region‑specific residency requirements.

## Why Multiple Orgs

* Data residency and latency: Keep user data and traffic in‑region.
* Strict isolation: Separate cohorts (e.g., Women‑A vs Men‑B) and lines of business.
* Governance boundaries: Independent roles, audit trails, and promotion controls per org.
* Safer operations: Limit blast radius; roll out/rollback changes per org.

## Naming Convention

Use a consistent postfix pattern: `<base>-<project>-<region-tag>`

* `<base>`: Company/program slug (letters only), e.g., `acme` or `acmehealth`.
* `<project>`: Cohort or product slug, e.g., `women-a`, `men-b`.
* `<region-tag>`: Alphabetic tag for the region of the org (letters only). Recommended:
  * US (N. Virginia, us‑east‑1) → `useast`
  * EU (Frankfurt, eu‑central‑1) → `eucentral`
  * AU (Sydney, ap‑southeast‑2) → `apsoutheast`

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
graph TB
Company\[Amigo Platform]
Company --> Base1\[acme]
Base1 --> Project1\[women-a]
Base1 --> Project2\[men-b]
Project1 --> Region1\[useast]
Project1 --> Region2\[eucentral]
Region1 --> Env1\[acme-women-a-useast-prod]
Region1 --> Env2\[acme-women-a-useast-staging]
Region2 --> Env3\[acme-women-a-eucentral-prod]
Region2 --> Env4\[acme-women-a-eucentral-staging]
style Env1 fill:#DDE3DB,stroke:#2c3827,color:#100F0F
style Env2 fill:#F0DDD9,stroke:#AA412A,color:#100F0F
style Env3 fill:#DDE3DB,stroke:#2c3827,color:#100F0F
style Env4 fill:#F0DDD9,stroke:#AA412A,color:#100F0F" %}

{% hint style="info" %}
Constraints

* Org IDs allow letters and hyphens only; length 4-20.
* Prefer lowercase for readability and consistency.
* Avoid reserved or generic names (see Create Organization errors for reserved IDs).
  {% endhint %}

Examples:

* `acme-women-a-useast`
* `acme-men-b-eucentral`
* `acme-trials-apsoutheast`

Tip: If you need finer granularity (e.g., multiple projects in the same region), extend `<project>` (for example, `women-a`, `women-a2`) while keeping the region tag unchanged.

## Region Selection

* Create a separate org per region to satisfy data residency and performance goals.
* Use the region’s base URL for all API calls and SDK `baseUrl` settings.
  * See Getting Started → Regions & Endpoints for current regional hosts.

## Creating Organizations

* Provision each org with a unique, region‑specific ID following the naming convention above.
* Use the Create Organization API (requires the provisioning header and permissions):

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/organization/" method="put" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

Notes:

* This endpoint requires the `x-mongo-cluster-name` header and appropriate permissions; see the OpenAPI details.
* After creation, your org is addressable at `<org-id>.amigo.ai` for frontend access.

## Access and Roles

* Treat each org as a hard boundary for RBAC. Grant administrators per org; avoid cross‑org role assignments.
* Invite users to the specific org(s) they belong to; do not share user identities across unrelated cohorts.
* Keep default roles as‑is unless you have a clear need for custom roles.

## Services and Tools per Org

* Services and tools are org‑scoped by design. Define only what a cohort needs inside that org.
* Publish tools in the team branch associated with the org’s team; prefer `repo: "team"` for org‑specific tools.
* Deprecate unused tool versions to manage cost.

## Recommended Environments

* Minimum recommended: one staging org and one production org per region × project.
* Add more environments as your DevOps flow requires (e.g., `dev`, `qa`, `pilot`, `perf`).
* Use separate orgs per environment to isolate data, configuration, and rollouts.
* Naming: append an environment suffix after the region tag, for clarity, e.g.:
  * `acme-women-a-useast-staging`
  * `acme-women-a-useast-prod`

{% hint style="info" %}
Start with staging and production per region × project. Add `dev`, `qa`, or other environments only as needed.
{% endhint %}

{% hint style="info" %}
Keep org IDs within the allowed character set and length limits.
{% endhint %}

## Deployment and Change Management

* Roll out changes per org; use versioned promotion and rollback where applicable.
* Monitor reliability and performance by org and version; address regressions without impacting other orgs.

## Checklist

* Pick the target region; decide the `<region-tag>`.
* Define `<base>` and `<project>` slugs; confirm total length ≤ 20.
* Create the org via the API with required headers and permissions.
* Configure services and publish tools for that org.
* Invite users and assign org‑local roles.
* Validate end‑to‑end in the region; monitor and iterate.

## Related

* Getting Started → [Regions & Endpoints](https://docs.amigo.ai/developer-guide/getting-started/regions-and-endpoints)
* Core API → [Tools](https://docs.amigo.ai/developer-guide/classic-api/core-api/tools)
* Best Practices → [Version Sets & Promotion](https://docs.amigo.ai/developer-guide/operations/devops/version-sets-best-practices)