#Organization Structure

Zephyr Cloud organizes your deployments using three levels: Organizations, Projects, and Applications.

#Overview

• Organizations - Top-level grouping for teams and billing
• Projects - Groups of related applications from the same repository
• Applications - Individual deployable micro-frontends

#Application UID Format

Every application in Zephyr is identified by a unique application_uid in the format:

{app-name}.{project}.{organization}

Example: header-component.ecommerce-platform.acme-corp

This identifier is automatically generated during the first build:

• app-name: From your package.json name field
• project: From your Git repository name
• organization: From your Git remote URL owner

#Organizations

Organizations are the top-level entity in Zephyr Cloud, representing your company, team, or individual account.

#How Organizations Are Created

Organizations are automatically created from your Git remote URL during your first deployment. Zephyr extracts the organization name from the repository owner in your Git origin.

Git Repository Examples:

• github.com/acme-corp/my-repo → Organization: acme-corp
• gitlab.com/frontend-team/project → Organization: frontend-team
• bitbucket.org/company-name/repo → Organization: company-name
• Self-hosted Git instances are also supported

Note: If no Git repository is detected, the organization falls back to your authenticated username.

#Projects

Projects are automatically created from your Git repository name. All applications from the same repository are grouped under one project.

#What Projects Enable

• Configure which applications deploy to which cloud integrations
• Bulk update deployment settings
• Coordinate environment promotions
• Share environment variables and secrets
• Manage team access for multiple applications

#Example Structure

Organization: acme-corp
�� Project: ecommerce-platform
    �� Application: header-component
    �� Application: product-catalog
    �� Application: shopping-cart
    �� Application: checkout-flow

#Applications

Applications are individual deployable units. Each application has its own build output and can be deployed and versioned independently.

#Application Features

• Independent deployment - Own build and deployment lifecycle
• Version management - Independent versioning with tags and environments
• Dependency resolution - Can consume other applications as remote dependencies
• Custom environments - Staging, production, and feature branch environments

#Per-Application Configuration

Each application can have:

• Different cloud deployment targets
• Unique build settings and bundler configurations
• Independent access controls
• Custom domain configurations

#Teams and Access Control

Organizations can have multiple Teams for access management:

• Teams belong to Organizations
• Users belong to one or more Teams
• Teams have permissions for specific Projects or Applications
• Control who can deploy, manage versions, and configure settings

This allows you to grant different levels of access to different groups within your organization.

#Configuration Example

package.json:

{
  "name": "@acme-corp/header-component"
}

Git repository:

github.com/acme-corp/ecommerce-platform

Results in:

• Organization: acme-corp (from Git URL)
• Project: ecommerce-platform (from Git repository name)
• Application: header-component (from package.json name)
• Application UID: header-component.ecommerce-platform.acme-corp

#How It Works in the Dashboard

The dashboard follows this hierarchy:

1. Organization View - All projects and recent activity
2. Project View - Applications in a project, shared settings
3. Application View - Detailed management, versions, and deployments