Projects

Projects are the top-level organizational unit in brdz, providing a way to group related applications together.

What is a Project?

A project represents a logical collection of applications. Think of it as a workspace or namespace where you can organize multiple related apps.

Examples:

A company might create projects for different products or services
A developer might separate personal, freelance, and open-source projects
Teams might organize projects by client, department, or environment

Project Structure

Account
├── Project: production
│   ├── App: web-frontend
│   ├── App: api-backend
│   └── App: admin-panel
├── Project: staging
│   ├── App: web-frontend
│   └── App: api-backend
└── Project: personal
    └── App: portfolio-site

Project Properties

Slug

A unique identifier for the project.

Must be unique within your account
URL-safe (lowercase letters, numbers, hyphens)
Cannot be changed after creation
Used in CLI commands and API calls

Examples: production, staging, my-project

Membership

Projects support multiple team members.

Control who can access the project
Members can manage apps within the project
Separate access control per project

Apps

A project contains zero or more applications.

Each app belongs to exactly one project
Apps within a project are independent
Projects provide organizational structure

Why Use Projects?

1. Organization

Group related applications together.

Project: e-commerce
├── App: storefront
├── App: checkout
├── App: admin-dashboard
└── App: api

2. Environment Separation

Maintain separate projects for different environments.

Account
├── Project: production
├── Project: staging
└── Project: development

3. Access Control

Control team access at the project level.

Project: client-acme
├── Members: dev-team, client-team
└── Apps: website, portal

Project: internal-tools
├── Members: dev-team only
└── Apps: dashboard, analytics

4. Resource Isolation

Keep resources separate and manageable.

Project: website
└── Apps: frontend, backend

Project: mobile-apps
└── Apps: ios-app, android-app

Project Lifecycle

1. Creation

brdz projects:create my-project

A new project is created with:

Unique slug
Creation timestamp
Your account as owner
Empty app list

2. Adding Apps

brdz ctx:use  # Select the project
brdz apps:create my-app

Apps are created within the project context.

3. Team Collaboration

# Add team members (if supported)
brdz projects:add-member my-project user@example.com

Team members can now access and manage apps within the project.

4. Management

# List projects
brdz projects:list

# Get project details
brdz projects:get my-project

# Update project (if supported)
brdz projects:update my-project --name "Production"

Best Practices

1. Use Descriptive Names

Choose clear, meaningful project slugs:

✅ Good:

production
e-commerce-platform
client-acme-website

❌ Bad:

proj1
test
asdf

2. Organize by Purpose

Group apps that belong together:

Project: marketing
├── App: landing-page
├── App: blog
└── App: newsletter

Project: product
├── App: web-app
├── App: mobile-api
└── App: admin

3. Separate Environments

Use different projects for different environments:

Project: production
Project: staging
Project: development

This provides:

Clear separation of concerns
Different access controls
Independent configurations

4. Plan Your Structure

Think about your organizational needs:

By Environment:

production/
staging/
development/

By Product:

website/
mobile-app/
api/

By Client:

client-a/
client-b/
client-c/

By Team:

frontend-team/
backend-team/
devops-team/

5. Document Your Projects

Keep documentation about:

Project purpose and scope
Which apps belong in the project
Team members and their roles
Related resources and dependencies

Common Patterns

Microservices

Project: platform
├── App: user-service
├── App: payment-service
├── App: notification-service
├── App: api-gateway
└── App: admin-panel

Multi-tenant SaaS

Project: saas-production
├── App: main-app
├── App: admin-dashboard
└── App: api

Project: saas-staging
├── App: main-app
└── App: api

Agency/Freelance

Project: client-acme-corp
├── App: corporate-website
└── App: employee-portal

Project: client-globex
├── App: marketing-site
└── App: web-app

Project: personal
└── App: portfolio

Development Workflows

Project: feature-branches
├── App: feature-auth
├── App: feature-payments
└── App: feature-dashboard

Project: staging
└── App: integrated-app

Project: production
└── App: live-app

Limitations

Project Slug Immutability

Slugs cannot be changed after creation
Choose carefully during creation
Plan your naming convention beforehand

Project Deletion

Cannot delete projects with existing apps
Must delete all apps first
Deletion is permanent

Scope

Projects cannot be nested
Projects cannot share apps
Each app belongs to exactly one project