[memory bank] Initialize cline memory bank (#20632)

* [memory bank] Initialize cline memory bank

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Start documenting first components (blobserve, content-service, dashboard, ws-manager-mk2)

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document more components (supervisor, ws-daemon)

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] More components (ide-service, registry-facade, image-builder-mk3)

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document proxy, server and ws-proxy

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document gitpod-cli and gitpod-db

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document gitpod-protocol

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document ide-proxy, ide and ws-manager-bridge

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document ide-metrics and local-app

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document public-api-serverr and usage

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document common-go and workspacekit

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Document spicedb, scrubber and service-waiter

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Documented docker-up, image-builder-bob, node-labeler

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Documented openvsx-proxy, scheduler-extender, ipfs

Tool: gitpod/catfood.gitpod.cloud

* [memory-bank] Update rules to lay out the "components" structure

Tool: gitpod/catfood.gitpod.cloud

memory-bank/.clinerules

@@ -0,0 +1,107 @@
+# Gitpod Project Intelligence
+
+This file captures important patterns, preferences, and project intelligence that help me work more effectively with the Gitpod codebase. It serves as a learning journal that will be updated as I discover new insights.
+
+## Project Structure Patterns
+
+- **Component Organization**: The project is organized into components, each with its own directory in the `components/` folder
+- **API Definitions**: API definitions are typically in separate packages with `-api` suffix (e.g., `content-service-api`)
+- **Protocol Buffers**: gRPC service definitions use Protocol Buffers (`.proto` files)
+- **Build Configuration**: Each component has a `BUILD.yaml` file defining its build configuration
+- **Docker Configuration**: Components that run as containers have a `leeway.Dockerfile`
+
+## Code Style Preferences
+
+- **Go Code**:
+  - Follow standard Go conventions (gofmt)
+  - Error handling with explicit checks
+  - Context propagation for cancellation
+  - Structured logging
+
+- **TypeScript Code**:
+  - Use TypeScript for type safety
+  - React for UI components
+  - Functional components with hooks
+  - ESLint and Prettier for formatting
+
+## Development Workflow
+
+- **Build System**: Use Leeway for building components
+  - `leeway build` to build specific components
+  - `leeway exec` to run commands across components
+
+- **Testing**:
+  - Unit tests alongside code
+  - Integration tests in separate directories
+  - End-to-end tests in the `test/` directory
+
+- **Local Development**:
+  - Use Gitpod workspaces for development (dogfooding)
+  - Components can be run individually for testing
+  - Preview environments for testing changes
+
+## Critical Implementation Paths
+
+- **Workspace Lifecycle**: The critical path for workspace operations involves:
+  - Workspace Manager
+  - Image Builder
+  - Kubernetes
+  - Workspace Daemon
+  - Supervisor
+
+- **User Authentication**: The critical path for user authentication involves:
+  - Auth Service
+  - Dashboard
+  - Proxy
+
+## Known Challenges
+
+- **Build System Complexity**: The Leeway build system has a learning curve
+- **Component Dependencies**: Understanding dependencies between components can be challenging
+- **Testing Environment**: Setting up proper testing environments for all components
+
+## Tool Usage Patterns
+
+- **VS Code**: Primary IDE for TypeScript development
+- **GoLand/IntelliJ**: Often used for Go development
+- **Docker**: Used for containerized development and testing
+- **kubectl**: Used for interacting with Kubernetes clusters
+- **Werft**: CI/CD system for automated builds and tests
+
+## Documentation Patterns
+
+- **README.md**: Each component should have a README explaining its purpose
+- **API Documentation**: Generated from Protocol Buffer definitions
+- **Architecture Documentation**: System-level documentation in various formats
+- **Memory Bank Documentation**:
+  - Component-specific documentation is stored in `memory-bank/components/` directory
+  - Each component gets its own markdown file with detailed information about its purpose, architecture, and implementation
+  - API components (with "*-api" suffix) should NOT be documented separately as they are typically just interface definitions
+  - Component documentation should focus on the main service components that implement business logic
+  - Documentation follows a consistent structure with sections for Overview, Purpose, Architecture, Key Features, etc.
+
+## Evolution of Project Decisions
+
+This section will be updated as I learn about how and why certain architectural and design decisions were made.
+
+### Memory Bank Organization
+
+- **Component Documentation**: The decision to create separate documentation files for each component in the `memory-bank/components/` directory was made to:
+  1. Provide a clear, organized structure for component documentation
+  2. Allow for detailed documentation of each component's purpose, architecture, and implementation
+  3. Make it easier to find information about specific components
+  4. Enable incremental updates to component documentation without affecting other files
+
+- **API Component Exclusion**: The decision to exclude "*-api" components from separate documentation was made because:
+  1. API components primarily contain interface definitions, not implementation logic
+  2. The interfaces are typically documented within the main service component that implements them
+  3. Documenting API components separately would create redundancy
+  4. The focus should be on documenting the service components that implement business logic
+
+## User Preferences
+
+This section will be updated as I learn about specific user preferences for working with the codebase.
+
+---
+
+Note: This file will be continuously updated as I work with the Gitpod codebase and discover new patterns, preferences, and insights.

memory-bank/activeContext.md

@@ -0,0 +1,119 @@
+# Active Context: Gitpod
+
+## Current Work Focus
+
+We are focusing on understanding the Gitpod codebase and architecture. The primary goal is to build a comprehensive knowledge base that will allow for effective development, troubleshooting, and enhancement of the Gitpod platform.
+
+Key areas of focus include:
+
+1. **System Architecture Understanding**: Mapping out the relationships between components and services
+2. **Component Documentation**: Creating detailed documentation for each component
+3. **Development Workflow**: Understanding how to effectively develop and test changes
+4. **Documentation**: Maintaining a comprehensive memory bank for future reference
+
+## Recent Changes
+
+- Created the initial memory bank structure with core files
+- Added a components subdirectory to the memory bank
+- Created detailed documentation for key components:
+  - blobserve: Service that provides static assets from OCI images
+  - content-service: Manages various types of content within the platform
+  - dashboard: Web-based user interface for Gitpod
+  - ws-manager-mk2: Kubernetes controller for managing workspace lifecycle
+  - supervisor: Init process that runs inside each workspace container
+  - ws-daemon: Node-level daemon for workspace operations
+  - ide-service: Manages IDE configurations and resolves workspace IDE requirements
+  - registry-facade: Modifies container images by adding layers for workspaces
+  - image-builder-mk3: Builds custom workspace images from user-defined Dockerfiles
+  - server: Main backend service handling API requests and user management
+  - proxy: Main entry point for all HTTP and WebSocket traffic
+  - ws-proxy: Handles routing and proxying of traffic to workspaces
+  - gitpod-cli: Command-line interface for interacting with Gitpod workspaces
+  - gitpod-db: Database layer for the Gitpod platform
+  - gitpod-protocol: Core type definitions and shared protocol library
+  - ide: Packages and manages IDEs available in Gitpod workspaces
+  - ide-proxy: Serves static IDE-related assets and proxies requests
+  - ws-manager-bridge: Bridges between workspace managers and the rest of the platform
+  - ide-metrics: Collects and processes metrics and error reports from IDE components
+  - local-app: Provides tools for interacting with Gitpod workspaces from local machine
+  - public-api-server: Provides a stable, versioned API for programmatic access to Gitpod
+  - usage: Tracks, calculates, and manages workspace usage and billing
+  - common-go: Foundational Go library providing shared utilities across services
+  - workspacekit: Manages container setup and namespace isolation for workspaces
+  - spicedb: Provides authorization and permission management
+  - scrubber: Removes or masks sensitive information from data
+  - service-waiter: Waits for services to become available
+  - docker-up: Sets up and manages Docker within workspace containers
+  - image-builder-bob: Builds and pushes workspace images during workspace startup
+  - node-labeler: Manages node labels and annotations for workspace scheduling
+  - openvsx-proxy: Caching proxy service for the OpenVSX registry
+  - scheduler-extender: Extends Kubernetes scheduling capabilities for workspaces
+  - ipfs: Provides distributed content-addressable storage for container images
+
+As work progresses, this section will continue to be updated to reflect:
+- Additional component documentation
+- Code changes implemented
+- Bug fixes
+- Feature additions
+- Refactoring efforts
+
+## Next Steps
+
+The immediate next steps are:
+
+1. **Explore Component Interactions**: Understand how components interact with each other
+2. **Set Up Development Environment**: Configure a local development environment for effective testing
+3. **Identify Initial Tasks**: Determine specific tasks or improvements to focus on
+4. **Establish Testing Approach**: Define how changes will be tested and validated
+5. **Update Memory Bank**: Continue to refine and expand the memory bank as new information is discovered
+
+## Active Decisions and Considerations
+
+### Architecture Decisions
+
+- **Component Boundaries**: Understanding and respecting the boundaries between different microservices
+- **API Contracts**: Maintaining compatibility with existing API contracts
+- **Performance Considerations**: Ensuring changes maintain or improve performance characteristics
+
+### Development Approach
+
+- **Testing Strategy**: Determining appropriate testing approaches for different types of changes
+- **Documentation Standards**: Establishing standards for code documentation and memory bank updates
+- **Collaboration Model**: Defining how to effectively collaborate with the team
+
+### Technical Considerations
+
+- **Backward Compatibility**: Ensuring changes maintain compatibility with existing clients and integrations
+- **Security Implications**: Evaluating security implications of any changes
+- **Scalability**: Considering how changes impact system scalability
+
+## Current Questions and Uncertainties
+
+As we begin working with the Gitpod codebase, several questions and uncertainties exist:
+
+1. **Component Interactions**: How do the various components interact in specific scenarios?
+2. **Performance Bottlenecks**: What are the current performance bottlenecks in the system?
+3. **Testing Approach**: What is the most effective way to test changes to different components?
+4. **Deployment Process**: What is the process for deploying changes to production?
+5. **Feature Priorities**: What features or improvements are currently prioritized?
+
+These questions will be addressed as we continue to explore the codebase and work with the system.
+
+## Active Experiments
+
+No active experiments are currently in progress. This section will be updated as experiments are designed and conducted to test hypotheses about the system or potential improvements.
+
+## Recent Learnings
+
+Initial exploration of the Gitpod codebase has revealed:
+
+- **Microservices Architecture**: Gitpod is built as a collection of loosely coupled services, each with specific responsibilities
+- **Go and TypeScript**: Backend services are primarily written in Go, while frontend components use TypeScript/React
+- **Kubernetes Native**: Many components are designed as Kubernetes controllers or operators
+- **gRPC Communication**: Services communicate using gRPC for efficient, typed communication
+- **Component Patterns**: Components follow consistent patterns:
+  - Go services typically have a cmd/ directory with command implementations
+  - TypeScript services use React and modern frontend practices
+  - Most components have a clear separation between API definitions and implementations
+
+This section will be continuously updated as new insights are gained through working with the system.

memory-bank/components/blobserve.md

@@ -0,0 +1,88 @@
+# Blobserve Component
+
+## Overview
+
+Blobserve is a service that provides static assets from OCI (Open Container Initiative) images. It serves as a specialized content delivery mechanism for container images, allowing efficient access to static content within those images.
+
+## Purpose
+
+The primary purpose of Blobserve is to:
+- Extract and serve static content from container images
+- Provide efficient access to image layers
+- Handle authentication with container registries
+- Serve HTTP requests for blob content
+
+## Architecture
+
+Blobserve operates as an HTTP server that:
+1. Connects to container registries
+2. Retrieves image content
+3. Extracts and caches static assets
+4. Serves these assets via HTTP
+
+## Key Files and Structure
+
+- `main.go`: Entry point that calls the Execute function from the cmd package
+- `cmd/root.go`: Defines the root command and basic service configuration
+- `cmd/run.go`: Implements the main server functionality
+- `pkg/blobserve`: Contains the core implementation of the blob serving functionality
+
+## Dependencies
+
+### Internal Dependencies
+- `components/common-go:lib`: Common Go utilities used across Gitpod
+- `components/registry-facade-api/go:lib`: API definitions for registry facade
+- `components/registry-facade:lib`: Library for interacting with container registries
+
+### External Dependencies
+- `containerd/containerd`: For container image handling
+- `docker/cli`: For Docker configuration handling
+- `prometheus`: For metrics and monitoring
+- `spf13/cobra`: For command-line interface
+
+## Configuration
+
+Blobserve is configured via a JSON configuration file that includes:
+- Authentication configuration for container registries
+- HTTP server settings
+- Repository mappings
+- Caching parameters
+- Monitoring endpoints
+
+## Integration Points
+
+Blobserve integrates with:
+1. **Container Registries**: Connects to registries like Docker Hub, ECR, GCR
+2. **Prometheus**: Exposes metrics for monitoring
+3. **Health Checking**: Provides readiness probes for Kubernetes
+
+## Security Considerations
+
+- Requires proper IAM permissions when using cloud-based container registries (e.g., AWS ECR)
+- Handles authentication credentials for private registries
+- Monitors file changes for authentication configuration updates
+
+## Common Usage Patterns
+
+Blobserve is typically used to:
+1. Serve static content from workspace images
+2. Provide efficient access to container image layers
+3. Cache frequently accessed content for performance
+
+## Metrics and Monitoring
+
+Blobserve exposes several Prometheus metrics:
+- `http_client_requests_total`: Counter of outgoing HTTP requests
+- `http_client_requests_duration_seconds`: Histogram of outgoing HTTP request durations
+- `http_server_requests_total`: Counter of incoming HTTP requests
+- `http_server_requests_duration_seconds`: Histogram of incoming HTTP request durations
+
+## Known Limitations
+
+- Requires specific IAM permissions when using cloud-based container registries
+- Authentication configuration must be properly set up for private registries
+
+## Related Components
+
+- **Registry Facade**: Works closely with Blobserve to provide access to container images
+- **Workspace Manager**: May use Blobserve to access workspace image content