gitpod/memory-bank/systemPatterns.md

System Patterns: Gitpod

System Architecture

Gitpod follows a microservices architecture composed of several key components that work together to provide the complete development environment platform. The system is designed to be:

• Scalable: Handles many concurrent users and workspaces
• Resilient: Maintains availability despite component failures
• Extensible: Allows for adding new features and integrations
• Secure: Isolates workspaces and protects user data

High-Level Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Git Platforms  │     │  User Browser   │     │  IDE Clients    │
│  (GitHub, etc.) │     │                 │     │  (VS Code, etc.)│
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                           API Gateway                           │
└─────────────────────────────────────────────────────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Auth Service   │     │  Dashboard      │     │  IDE Service    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────┬───────┴───────────────┬───────┘
                         │                       │
                         ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  WS Manager     │     │  Image Builder  │     │  Content Service│
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Kubernetes Infrastructure                    │
└─────────────────────────────────────────────────────────────────┘

Key Components

Core Services

1. Workspace Manager (ws-manager): Orchestrates workspace lifecycle, managing creation, starting, stopping, and deletion of workspaces.

2. Workspace Daemon (ws-daemon): Runs on each node, managing workspace resources, file system operations, and runtime aspects.

3. Image Builder: Builds Docker images for workspaces based on configuration and caches them for quick startup.

4. Content Service: Manages file content, including git operations, file synchronization, and backup.

5. IDE Service: Manages the IDE instances (VS Code, JetBrains) that run in workspaces.

6. Dashboard: Web UI for managing workspaces, projects, and user settings.

7. Auth Service: Handles authentication and authorization across the platform.

8. Proxy: Routes traffic to the appropriate services and workspaces.

Supporting Components

1. Registry Facade: Provides efficient access to container images.

2. Blobserve: Serves static content from container images.

3. Supervisor: Runs inside each workspace, managing the workspace's internal services.

4. Public API: Provides programmatic access to Gitpod functionality.

Design Patterns

Microservices Pattern

Gitpod is built as a collection of loosely coupled services, each with a specific responsibility. This enables independent scaling, deployment, and maintenance of components.

Container Orchestration

Kubernetes is used to manage the deployment, scaling, and operation of application containers across clusters of hosts.

Event-Driven Architecture

Components communicate through events for asynchronous operations, improving scalability and resilience.

API Gateway Pattern

A central API gateway routes requests to appropriate services, handling cross-cutting concerns like authentication.

Circuit Breaker Pattern

Services implement circuit breakers to prevent cascading failures when downstream services are unavailable.

Sidecar Pattern

The Supervisor component runs alongside workspace applications as a sidecar, providing common functionality.

Immutable Infrastructure

Workspaces are treated as immutable, with changes to configuration resulting in new environments rather than modifications to existing ones.

Component Relationships

Workspace Lifecycle

1. User requests a workspace through the dashboard or Git integration
2. Auth service validates the request
3. Workspace Manager creates the workspace specification
4. Image Builder ensures the required image is available
5. Workspace Manager instructs Kubernetes to create the workspace pod
6. Workspace Daemon initializes the workspace environment
7. Supervisor starts within the workspace
8. IDE Service connects the IDE to the workspace
9. Proxy routes user traffic to the workspace

Data Flow

1. User Code: Managed by Content Service, synchronized between workspace and git repositories
2. Configuration: Stored in database, applied by Workspace Manager during workspace creation
3. Build Artifacts: Cached by Image Builder for reuse in future workspaces
4. User Data: Stored in database, accessed through Dashboard and API

Key Technical Decisions

1. Kubernetes-Based: Leveraging Kubernetes for container orchestration provides scalability and standardized infrastructure management.

2. Multi-IDE Support: Supporting multiple IDEs (VS Code, JetBrains) increases flexibility for users with different preferences.

3. Prebuild System: Prebuilding environments before they're needed significantly reduces startup times.

4. Workspace Pods: Each workspace runs in its own Kubernetes pod, providing isolation and resource management.

5. TypeScript and Go: Core services are implemented in TypeScript (user-facing) and Go (system-level), balancing developer productivity and performance.

6. gRPC Communication: Internal services communicate using gRPC for efficient, typed communication.

7. Leeway Build System: Custom build system for managing the complex dependencies between components.

8. Kubernetes Deployment Configuration: All code that defines Kubernetes objects for deployable components lives in install/installer. This centralized approach ensures consistent deployment patterns across all components.

Development Workflows

Product Requirements Document (PRD) Workflow

Gitpod uses a structured PRD workflow for feature development to ensure proper planning, documentation, and implementation:

1. Requirements Gathering (Plan Mode): Understand the problem, explore existing components, gather information
2. PRD Creation (Plan Mode): Create a detailed document in prd/ with standardized sections
3. Implementation Planning (Plan Mode): Identify files to modify and plan the approach
4. Implementation (Act Mode): Create/modify necessary files following the plan
5. Documentation Update (Act Mode): Update memory bank with new knowledge
6. Verification: Ensure implementation meets requirements and documentation is complete

This workflow ensures thorough planning, clear documentation, and knowledge preservation for all feature development.