/migrate-to-teams - Multi-Tenancy Architecture Migration

Purpose

The /migrate-to-teams prompt transforms single-tenant applications into robust multi-tenant architectures. It handles the complex migration process while ensuring data isolation, security, and scalability for team-based SaaS applications.

Use Cases

SaaS Transformation: Convert single-user apps to team-based SaaS
B2B Evolution: Add organizational support to B2C products
Enterprise Scaling: Enable multi-organization deployments
White-Label Platform: Support multiple branded instances
Marketplace Creation: Enable vendor/customer separation

Argument Structure

/migrate-to-teams [isolation-strategy] [migration-approach] [--options]

Arguments

isolation-strategy (optional)
- Data isolation method
- Options: "row-level", "schema-based", "database-per-tenant"
- Defaults to intelligent selection
migration-approach (optional)
- Migration strategy
- Options: "gradual", "big-bang", "hybrid"
- Defaults to gradual
options (optional)
- --preserve: Keep single-user functionality
- --scale: Target scale (teams, users)
- --features: Team features to include

Examples

bash

# Basic team migration
/migrate-to-teams

# Row-level security approach
/migrate-to-teams "row-level"

# Gradual migration with preservation
/migrate-to-teams "row-level" "gradual" --preserve

# Enterprise-scale migration
/migrate-to-teams "schema-based" --scale="1000-teams"

Adaptation Strategies

Architecture Analysis

The prompt evaluates:

Current Structure
- Database schema
- API design
- Authentication system
- Data relationships
- Service boundaries
Migration Complexity
- Data volume
- Relationship complexity
- Performance requirements
- Downtime tolerance
- Rollback needs
Target Architecture
- Isolation requirements
- Scale projections
- Performance needs
- Compliance requirements
- Cost constraints

Isolation Strategy Selection

Row-Level Security (RLS)

Best for:

Simpler applications
Shared infrastructure
Cost optimization
Quick implementation

Schema-Based

Ideal for:

Medium complexity
Logical separation
Compliance needs
Moderate scale

Database-Per-Tenant

Suited for:

High isolation needs
Compliance requirements
Large enterprise clients
Complete customization

Memory Usage

Migration Documentation

.orchestre/
├── migration/
│   ├── teams/
│   │   ├── plan.md              # Migration strategy
│   │   ├── architecture.md      # Target architecture
│   │   ├── progress.md          # Migration tracking
│   │   └── rollback.md          # Rollback procedures
│   ├── schemas/
│   │   ├── before/              # Original schemas
│   │   ├── after/               # Multi-tenant schemas
│   │   └── migrations/          # Migration scripts
│   └── testing/
│       ├── scenarios.md         # Test scenarios
│       └── validation.md        # Validation criteria

Migration Plan Example

markdown

# Multi-Tenant Migration Plan

## Current State Analysis
- Single-tenant PostgreSQL database
- User-based authentication
- Shared resource model
- 50,000 active users

## Target Architecture
### Isolation Strategy: Row-Level Security
- Team table for organizations
- team_id on all resources
- RLS policies for isolation
- Team-scoped API endpoints

### Migration Phases

#### Phase 1: Foundation (Week 1-2)
1. Add team infrastructure
   - Create teams table
   - Add team_members junction
   - Update user model

2. Implement team management
   - Team creation API
   - Invitation system
   - Role definitions

#### Phase 2: Data Migration (Week 3-4)
1. Add team_id columns
   - All resource tables
   - Set default team per user
   - Create migration scripts

2. Update APIs
   - Add team context
   - Update authorization
   - Modify queries

#### Phase 3: Security & Isolation (Week 5)
1. Implement RLS policies
   - Create security policies
   - Test isolation
   - Performance optimization

2. Update application layer
   - Team switching
   - Cross-team permissions
   - Admin capabilities

#### Phase 4: Features & Polish (Week 6)
1. Team features
   - Billing per team
   - Team settings
   - Activity logs

2. Migration tools
   - User-to-team conversion
   - Bulk operations
   - Admin dashboard

Workflow Examples

Startup SaaS Evolution

bash

# 1. Plan migration
/migrate-to-teams "row-level" "gradual"

# 2. Implement foundation
/execute-task "Create team infrastructure from migration plan Phase 1"

# 3. Add team features
/add-enterprise-feature "team-management" "Invites, roles, and permissions"

# 4. Migrate existing users
/execute-task "Run user-to-team migration scripts"

Enterprise Platform Migration

bash

# 1. Analyze requirements
/migrate-to-teams "schema-based" --scale="enterprise"

# 2. Security audit
/security-audit "multi-tenancy"

# 3. Implement isolation
/execute-task "Implement schema-based isolation with connection pooling"

# 4. Add enterprise features
/add-enterprise-feature "sso" "Per-team SSO configuration"

Marketplace Transformation

bash

# 1. Design multi-sided architecture
/migrate-to-teams "database-per-tenant" "hybrid"

# 2. Implement vendor isolation
/execute-task "Create vendor database isolation system"

# 3. Add marketplace features
/execute-task "Build cross-tenant search and discovery"

# 4. Payment splitting
/add-enterprise-feature "marketplace-payments" "Multi-party payment flows"

Implementation Components

1. Team Infrastructure

sql

-- Core team tables
CREATE TABLE teams (
  id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  slug VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE team_members (
  team_id UUID REFERENCES teams(id),
  user_id UUID REFERENCES users(id),
  role VARCHAR(50) NOT NULL,
  joined_at TIMESTAMP DEFAULT NOW(),
  PRIMARY KEY (team_id, user_id)
);

2. Row-Level Security

sql

-- Enable RLS
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;

-- Create policies
CREATE POLICY team_isolation ON projects
  FOR ALL
  USING (team_id = current_setting('app.current_team_id')::UUID);

3. API Modifications

javascript

// Before: User context only
app.get('/api/projects', authenticate, async (req, res) => {
  const projects = await getProjectsByUser(req.user.id);
  res.json(projects);
});

// After: Team context
app.get('/api/teams/:teamId/projects', authenticate, authorize, async (req, res) => {
  const projects = await getProjectsByTeam(req.params.teamId);
  res.json(projects);
});

4. Migration Scripts

javascript

// Gradual migration script
async function migrateUserToTeam(userId) {
  // Create personal team
  const team = await createTeam({
    name: `${user.name}'s Team`,
    type: 'personal'
  });
  
  // Add user as owner
  await addTeamMember(team.id, userId, 'owner');
  
  // Migrate resources
  await migrateUserResources(userId, team.id);
  
  return team;
}

Migration Strategies

Gradual Migration

Best for active applications:

Add team infrastructure alongside existing
Migrate users in batches
Maintain backward compatibility
Remove legacy code after completion

Big-Bang Migration

For smaller applications:

Plan comprehensive migration
Execute during maintenance window
Complete transformation at once
Simpler but riskier

Hybrid Approach

For complex scenarios:

Infrastructure changes first
Gradual data migration
Feature rollout in phases
Risk mitigation built-in

Common Challenges

1. Data Isolation

Challenge: Ensuring complete isolation
Solution: RLS policies + application checks
Testing: Automated isolation tests

2. Performance Impact

Challenge: Query performance degradation
Solution: Proper indexing + query optimization
Monitoring: Performance baselines

3. Migration Complexity

Challenge: Complex data relationships
Solution: Phased migration + validation
Rollback: Checkpoint-based recovery

4. User Experience

Challenge: Seamless transition
Solution: Gradual UI changes + guides
Support: Migration assistance

Integration Points

With Other Prompts

← /orchestrate: Plan migration strategy
→ /execute-task: Implement phases
→ /add-enterprise-feature: Add team features
→ /security-audit: Validate isolation

With Existing Features

Authentication system
Billing integration
API structure
Admin panels
Reporting systems

Best Practices

Plan Thoroughly

bash

# Good: Comprehensive planning
/migrate-to-teams "row-level" "gradual" --scale="1000-teams"

# Risky: No planning
/migrate-to-teams

Test Isolation

bash

# After implementation
/security-audit "team-isolation"

# Create test scenarios
/execute-task "Create comprehensive team isolation test suite"

Monitor Performance

bash

# Before migration
/performance-check --baseline

# After each phase
/performance-check --compare-baseline

Advanced Scenarios

Multi-Region Teams

bash

/migrate-to-teams "schema-based" --features="multi-region,data-residency"
# Implements geographic isolation and compliance

Hierarchical Organizations

bash

/migrate-to-teams "row-level" --features="sub-teams,inheritance"
# Supports enterprise org structures

White-Label Platform

bash

/migrate-to-teams "database-per-tenant" --features="custom-domain,branding"
# Full isolation with customization

Tips

Start Simple: Row-level security works for most cases
Plan for Scale: Consider 10x growth in design
Test Thoroughly: Isolation bugs are critical
Communicate Changes: Users need clear migration guides
Monitor Closely: Performance impacts may emerge over time

/migrate-to-teams - Multi-Tenancy Architecture Migration ​

Purpose ​

Use Cases ​

Argument Structure ​

Arguments ​

Examples ​

Adaptation Strategies ​

Architecture Analysis ​

Isolation Strategy Selection ​

Row-Level Security (RLS) ​

Schema-Based ​

Database-Per-Tenant ​

Memory Usage ​

Migration Documentation ​

Migration Plan Example ​

Workflow Examples ​

Startup SaaS Evolution ​

Enterprise Platform Migration ​

Marketplace Transformation ​

Implementation Components ​

1. Team Infrastructure ​

2. Row-Level Security ​

3. API Modifications ​

4. Migration Scripts ​

Migration Strategies ​

Gradual Migration ​

Big-Bang Migration ​

Hybrid Approach ​

Common Challenges ​

1. Data Isolation ​

2. Performance Impact ​

3. Migration Complexity ​

4. User Experience ​

Integration Points ​

With Other Prompts ​

With Existing Features ​

Best Practices ​

Advanced Scenarios ​

Multi-Region Teams ​

Hierarchical Organizations ​

White-Label Platform ​

Tips ​

/migrate-to-teams - Multi-Tenancy Architecture Migration

Purpose

Use Cases

Argument Structure

Arguments

Examples

Adaptation Strategies

Architecture Analysis

Isolation Strategy Selection

Row-Level Security (RLS)

Schema-Based

Database-Per-Tenant

Memory Usage

Migration Documentation

Migration Plan Example

Workflow Examples

Startup SaaS Evolution

Enterprise Platform Migration

Marketplace Transformation

Implementation Components

1. Team Infrastructure

2. Row-Level Security

3. API Modifications

4. Migration Scripts

Migration Strategies

Gradual Migration

Big-Bang Migration

Hybrid Approach

Common Challenges

1. Data Isolation

2. Performance Impact

3. Migration Complexity

4. User Experience

Integration Points

With Other Prompts

With Existing Features

Best Practices

Advanced Scenarios

Multi-Region Teams

Hierarchical Organizations

White-Label Platform

Tips