Roo-Code/docs/CLOUD_ARCHITECTURE.md

Roo Code Cloud Integration Architecture

This document describes the technical architecture of Roo Code's cloud integration features, including design decisions, implementation details, and extension points.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         VS Code Extension                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │   Webview   │  │ ClineProvider│  │  WebviewMessageHandler │  │
│  │     UI      │◄─┤              │◄─┤                        │  │
│  └─────────────┘  └──────┬───────┘  └────────────────────────┘  │
│                          │                                        │
│  ┌─────────────────────┐ │ ┌──────────────────────────────────┐ │
│  │   CloudService      │◄┴─┤  ProviderSettingsManager        │ │
│  │   (Singleton)       │   │  (Profile Management)           │ │
│  └──────────┬──────────┘   └──────────────────────────────────┘ │
│             │                                                     │
│  ┌──────────┴──────────┐   ┌──────────────────────────────────┐ │
│  │   AuthService       │   │      SettingsService             │ │
│  │ - WebAuthService    │   │  - CloudSettingsService         │ │
│  │ - StaticTokenAuth   │   │  - StaticSettingsService        │ │
│  └─────────────────────┘   └──────────────────────────────────┘ │
│                                                                   │
│  ┌─────────────────────┐   ┌──────────────────────────────────┐ │
│  │  CloudShareService  │   │      CloudAPI                    │ │
│  │  (Task Sharing)     │───┤   (HTTP Client)                  │ │
│  └─────────────────────┘   └──────────────────────────────────┘ │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                        ┌───────────────────────┐
                        │   Roo Cloud Service   │
                        │   (External API)      │
                        └───────────────────────┘

Core Components

CloudService (Singleton)

The central orchestrator for all cloud functionality:

class CloudService extends EventEmitter<CloudServiceEvents> {
	private static _instance: CloudService | null = null
	private authService: AuthService
	private settingsService: SettingsService
	private shareService: CloudShareService
	private cloudAPI: CloudAPI

	// Singleton pattern ensures single instance
	static async createInstance(context: ExtensionContext): Promise<CloudService>
	static get instance(): CloudService
}

Key Responsibilities:

• Manages lifecycle of cloud components
• Provides unified API for cloud features
• Handles event propagation
• Ensures proper initialization order

Authentication Layer

AuthService Interface

interface AuthService {
	initialize(): Promise<void>
	login(): Promise<void>
	logout(): Promise<void>
	isAuthenticated(): boolean
	getUserInfo(): CloudUserInfo | null
	getSessionToken(): string | null
}

WebAuthService

Handles browser-based OAuth flow:

class WebAuthService implements AuthService {
	private async startAuthFlow() {
		// 1. Generate state for CSRF protection
		// 2. Open browser with auth URL
		// 3. Start local server to receive callback
		// 4. Exchange code for tokens
		// 5. Store tokens securely
	}
}

StaticTokenAuthService

For CI/CD and automated environments:

class StaticTokenAuthService implements AuthService {
	constructor(token: string) {
		// Use provided token directly
		// No browser flow needed
	}
}

Settings Synchronization

CloudSettingsService

Manages real-time settings synchronization:

class CloudSettingsService extends EventEmitter {
	private refreshTimer: RefreshTimer
	private cachedSettings: OrganizationSettings | null

	async initialize() {
		// 1. Fetch initial settings
		// 2. Start refresh timer
		// 3. Listen for auth changes
	}

	private async fetchSettings() {
		// 1. Get auth token
		// 2. Call API
		// 3. Validate response
		// 4. Update cache
		// 5. Emit change event
	}
}

Refresh Strategy:

• Initial fetch on authentication
• Periodic refresh (configurable interval)
• Force refresh on specific events
• Exponential backoff on failures

Profile Management

ProviderSettingsManager

Handles the complex merge of cloud and local profiles:

class ProviderSettingsManager {
	async syncCloudProfiles(
		cloudProfiles: Record<string, ProviderSettings>,
		currentProfileName?: string,
	): Promise<SyncResult> {
		// 1. Load local profiles
		// 2. Identify cloud-sourced profiles
		// 3. Merge with conflict resolution
		// 4. Preserve local-only profiles
		// 5. Update active profile if needed
	}
}

Conflict Resolution:

• Cloud profiles take precedence
• Local modifications are preserved until next sync
• Deleted cloud profiles are removed locally
• Local-only profiles are never touched

Task Sharing

CloudShareService

Manages task sharing with clipboard integration:

class CloudShareService {
	async shareTask(taskId: string, visibility: ShareVisibility) {
		// 1. Call API to create share
		// 2. Copy URL to clipboard
		// 3. Return share details
	}

	async canShareTask(): boolean {
		// Check organization settings
		// Verify user permissions
	}
}

Share Flow:

1. User initiates share
2. Task data is already on server (if telemetry enabled)
3. Create share record with visibility
4. Generate shareable URL
5. Auto-copy to clipboard

Event System

Task Lifecycle Events

Events flow through multiple layers:

// Task emits event
task.emit(RooCodeEventName.TaskCompleted, tokenUsage, toolUsage)

// ClineProvider proxies to CloudService
provider.on(RooCodeEventName.TaskCompleted, (...args) => {
	CloudService.instance.captureEvent({
		name: "task_completed",
		properties: { ...args },
	})
})

// TelemetryClient sends to cloud
telemetryClient.capture(event)

Event Categories:

• Lifecycle: Created, Started, Completed, Aborted
• State: Focused, Unfocused, Active, Idle
• Execution: Message, ModeSwitch, ToolUse
• Analytics: TokenUsage, ToolFailure

Data Flow

Profile Synchronization Flow

1. User signs in
   └─> AuthService.login()
       └─> CloudSettingsService.fetchSettings()
           └─> ProviderSettingsManager.syncCloudProfiles()
               └─> ClineProvider.postStateToWebview()
                   └─> UI updates

2. Admin updates profile
   └─> Cloud webhook (future)
       └─> CloudSettingsService.refresh()
           └─> Same flow as above

3. User switches profile
   └─> WebviewMessageHandler.loadApiConfiguration()
       └─> ProviderSettingsManager.activateProfile()
           └─> Update global state
           └─> Update current task API

Task Sharing Flow

1. User clicks share
   └─> WebviewMessageHandler.shareCurrentTask()
       └─> CloudService.shareTask()
           ├─> CloudAPI.shareTask()
           │   └─> POST /api/extension/share
           └─> vscode.env.clipboard.writeText()

2. If task not found (backfill)
   └─> TelemetryClient.backfillMessages()
       └─> Retry share

Security Architecture

Authentication Security

1. OAuth 2.0 Flow

   • PKCE for enhanced security
   • State parameter for CSRF protection
   • Secure token storage in VS Code

2. Token Management

   • Access tokens with short expiry
   • Refresh tokens for long-lived sessions
   • Automatic token refresh

3. Static Token Mode

   • For CI/CD environments only
   • Environment variable based
   • No persistent storage

Data Security

1. API Communication

   • HTTPS only
   • Certificate pinning (future)
   • Request signing (future)

2. Profile Security

   • API keys never synced
   • Only configuration synced
   • Local encryption for sensitive data

3. Task Sharing Security

   • Visibility controls
   • Expiration dates
   • Access logging

Extension Points

Adding New Cloud Features

1. New Service Pattern

class NewCloudService {
	constructor(
		private cloudAPI: CloudAPI,
		private settingsService: SettingsService,
	) {}

	async initialize() {
		// Setup logic
	}

	// Feature methods
}

2. Integration Steps
   • Add to CloudService initialization
   • Create message handlers
   • Update webview communication
   • Add telemetry events

Custom Authentication Providers

interface AuthProvider {
	type: "oauth" | "apikey" | "custom"
	initialize(): Promise<void>
	authenticate(): Promise<AuthResult>
	refresh(): Promise<AuthResult>
}

Event Extensions

// Define new event
enum CustomEventName {
	CustomAction = "customAction",
}

// Add to event schema
const customEventSchema = z.object({
	[CustomEventName.CustomAction]: z.tuple([
		z.string(), // taskId
		z.object({
			/* payload */
		}),
	]),
})

// Emit event
task.emit(CustomEventName.CustomAction, taskId, payload)

Performance Considerations

Caching Strategy

1. Settings Cache

   • 5-minute TTL
   • Force refresh on auth change
   • Invalidate on error

2. Profile Cache

   • Persistent local storage
   • Sync on startup
   • Incremental updates

3. API Response Cache

   • ETag support
   • Conditional requests
   • Bandwidth optimization

Optimization Techniques

1. Lazy Loading

   • Cloud features load on demand
   • Defer non-critical operations
   • Progressive enhancement

2. Batching

   • Group API requests
   • Debounce rapid changes
   • Bulk operations

3. Background Sync

   • Non-blocking UI updates
   • Queue offline changes
   • Retry with backoff

Error Handling

Error Categories

1. Authentication Errors

   • Token expired
   • Invalid credentials
   • Network issues

2. API Errors

   • Rate limiting
   • Server errors
   • Validation failures

3. Sync Errors

   • Conflict resolution
   • Data corruption
   • Version mismatch

Recovery Strategies

class ErrorRecovery {
	async handleAuthError(error: AuthError) {
		if (error.code === "TOKEN_EXPIRED") {
			// Attempt refresh
			// Fallback to re-login
		}
	}

	async handleSyncError(error: SyncError) {
		if (error.code === "CONFLICT") {
			// User chooses resolution
			// Or automatic resolution
		}
	}
}

Testing Strategy

Unit Tests

describe("CloudShareService", () => {
	it("should share task with organization visibility", async () => {
		// Mock CloudAPI
		// Test share flow
		// Verify clipboard
	})
})

Integration Tests

describe("Profile Sync", () => {
	it("should merge cloud and local profiles", async () => {
		// Setup test profiles
		// Trigger sync
		// Verify merge result
	})
})

E2E Tests

describe("Cloud Features E2E", () => {
	it("should complete full auth and sync flow", async () => {
		// Simulate login
		// Wait for sync
		// Verify UI state
	})
})

Future Enhancements

Planned Features

1. Real-time Collaboration

   • WebSocket connections
   • Live task sharing
   • Collaborative editing

2. Advanced Analytics

   • Custom dashboards
   • Team metrics
   • Cost tracking

3. Enterprise Features

   • SSO integration
   • Audit logging
   • Compliance tools

Architecture Evolution

1. Microservices

   • Separate auth service
   • Independent share service
   • Scalable architecture

2. Edge Computing

   • Regional endpoints
   • CDN integration
   • Reduced latency

3. Offline Support

   • Local queue
   • Sync on reconnect
   • Conflict resolution

Conclusion

The cloud integration architecture is designed to be:

• Modular: Easy to extend and maintain
• Secure: Multiple layers of protection
• Performant: Optimized for responsiveness
• Reliable: Graceful error handling
• Scalable: Ready for growth

For implementation details, see the source code in:

• /packages/cloud/src/
• /src/core/webview/
• /packages/types/src/