mirror of
https://github.com/gitpod-io/gitpod.git
synced 2025-12-08 17:36:30 +00:00
f88268c889
* [memory-bank] Overhaul based on current usage - merge learning-journal.md into existing docs - introduce public-api.md - introduce components.md for more reliable lookup * [memory-bank] Compress
185 lines
7.8 KiB
Markdown
185 lines
7.8 KiB
Markdown
# System Patterns: Gitpod
|
|
|
|
## System Architecture
|
|
|
|
Gitpod follows a microservices architecture designed to be **Scalable**, **Resilient**, **Extensible**, and **Secure**.
|
|
|
|
### High-Level Architecture
|
|
|
|
```
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│Git Platforms│ │User Browser │ │IDE Clients │
|
|
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
|
|
│ │ │
|
|
└────────┬───────┴────────┬───────┘
|
|
▼ ▼
|
|
┌───────────────────────────────┐
|
|
│ API Gateway │
|
|
└───────────────────────────────┘
|
|
│ │
|
|
┌────────┴───────┐ ┌─────┴────────┐
|
|
│ Auth Service │ │ Dashboard │
|
|
└────────────────┘ └──────────────┘
|
|
│ │
|
|
┌────────┴───────┐ ┌─────┴────────┐
|
|
│ WS Manager │ │Image Builder │
|
|
└────────────────┘ └──────────────┘
|
|
│ │
|
|
┌────────┴────────────────┴────────┐
|
|
│ Kubernetes Infrastructure │
|
|
└───────────────────────────────────┘
|
|
```
|
|
|
|
## Key Components
|
|
|
|
### Core Services
|
|
|
|
| Component | Purpose |
|
|
|-----------|---------|
|
|
| **Workspace Manager** | Orchestrates workspace lifecycle (creation, starting, stopping, deletion) |
|
|
| **Workspace Daemon** | Manages workspace resources and file system operations on each node |
|
|
| **Image Builder** | Builds and caches Docker images for workspaces |
|
|
| **Content Service** | Manages file content, git operations, and synchronization |
|
|
| **IDE Service** | Manages IDE instances (VS Code, JetBrains) |
|
|
| **Dashboard** | Web UI for workspace and user management |
|
|
| **Auth Service** | Handles authentication and authorization |
|
|
| **Proxy** | Routes traffic to appropriate services and workspaces |
|
|
|
|
### Supporting Components
|
|
|
|
| Component | Purpose |
|
|
|-----------|---------|
|
|
| **Registry Facade** | Efficient access to container images |
|
|
| **Blobserve** | Serves static content from container images |
|
|
| **Supervisor** | Manages workspace internal services |
|
|
| **Public API** | Programmatic access to Gitpod functionality |
|
|
|
|
## Project Structure & Code Style
|
|
|
|
### Project Organization
|
|
- Components in `components/` directory
|
|
- API definitions in `-api` suffixed packages
|
|
- gRPC services defined with Protocol Buffers (`.proto`)
|
|
- `BUILD.yaml` for build configuration
|
|
- `leeway.Dockerfile` for containerized components
|
|
|
|
### Code Style
|
|
| Language | Key Practices |
|
|
|----------|---------------|
|
|
| **Go** | Standard conventions (gofmt), explicit error handling, context propagation, structured logging |
|
|
| **TypeScript** | Type safety, React for UI, functional components with hooks, ESLint/Prettier |
|
|
|
|
## Design Patterns
|
|
|
|
| Pattern | Implementation |
|
|
|---------|----------------|
|
|
| **Microservices** | Loosely coupled services with specific responsibilities |
|
|
| **Container Orchestration** | Kubernetes for deployment, scaling, and operations |
|
|
| **Event-Driven Architecture** | Asynchronous communication for scalability and resilience |
|
|
| **API Gateway** | Central routing with cross-cutting concerns handling |
|
|
| **Immutable Infrastructure** | Configuration changes create new environments |
|
|
|
|
## Component Relationships
|
|
|
|
### Workspace Lifecycle Flow
|
|
1. User requests workspace → Auth validates → WS Manager creates spec
|
|
2. Image Builder ensures image availability → WS Manager creates K8s pod
|
|
3. WS Daemon initializes environment → Supervisor starts
|
|
4. IDE Service connects IDE → Proxy routes traffic
|
|
|
|
**Key components**: ws-manager-mk2, ws-daemon, ws-manager-bridge, server, image-builder-mk3
|
|
|
|
### Data Flow
|
|
- **User Code**: Content Service manages synchronization
|
|
- **Configuration**: Database storage, applied by WS Manager
|
|
- **Build Artifacts**: Cached by Image Builder
|
|
- **User Data**: Database storage, accessed via Dashboard/API
|
|
|
|
## Key Technical Decisions
|
|
|
|
| Decision | Rationale |
|
|
|----------|-----------|
|
|
| **Kubernetes-Based** | Scalability and standardized infrastructure |
|
|
| **Multi-IDE Support** | Flexibility for different user preferences |
|
|
| **Prebuild System** | Significantly reduced startup times |
|
|
| **Workspace Pods** | Isolation and resource management |
|
|
| **TypeScript & Go** | Balance of developer productivity and performance |
|
|
| **gRPC Communication** | Efficient, typed service communication |
|
|
| **Leeway Build System** | Management of complex component dependencies |
|
|
| **K8s Deployment Config** | Centralized in `install/installer` for consistency |
|
|
| **Public API Architecture** | gRPC services defined in Protocol Buffers |
|
|
| **SpiceDB Authorization** | Fine-grained relationship-based access control |
|
|
|
|
## Development Workflows
|
|
|
|
### PRD Workflow
|
|
1. **Requirements Gathering** (Plan): Understand problem, explore components
|
|
2. **PRD Creation** (Plan): Create document with standardized sections
|
|
3. **Implementation Planning** (Plan): Identify files to modify
|
|
4. **Implementation** (Act): Create/modify files
|
|
5. **Documentation Update** (Act): Update memory bank
|
|
6. **Verification**: Validate implementation meets requirements
|
|
|
|
### Build Approaches
|
|
|
|
- **In-tree builds** (for development in a Gitpod workspace):
|
|
- TypeScript components: Use `yarn` commands defined in `package.json`.
|
|
- `yarn build`: Compile the component.
|
|
- `yarn test`: Run tests.
|
|
- `yarn lint`: Check code style.
|
|
- `yarn watch`: Watch for changes and rebuild.
|
|
- Go components: Use standard Go tools.
|
|
- `go build ./...`: Build all packages.
|
|
- `go test ./...`: Test all packages.
|
|
- `go run main.go`: Build and run.
|
|
- **Out-of-tree builds** (Leeway, primarily used in CI):
|
|
- `leeway build components/component-name:app`: Build a specific component.
|
|
- `leeway build -D components/component-name:app`: Build with dependencies.
|
|
- `leeway exec --package components/component-name:app -- command`: Run a command for a package.
|
|
|
|
|
|
### Testing & Development
|
|
- Unit tests alongside code
|
|
- Integration tests in separate directories
|
|
- End-to-end tests in `test/` directory
|
|
- Gitpod workspaces for development (dogfooding)
|
|
- Preview environments for testing
|
|
|
|
## Documentation Patterns
|
|
- README.md for component purpose
|
|
- API docs from Protocol Buffer definitions
|
|
- Component docs in `memory-bank/components/`
|
|
- Standardized structure (Overview, Purpose, Architecture, etc.)
|
|
- API components include Code Generation section
|
|
|
|
## Known Challenges
|
|
- Build system complexity
|
|
- Component dependency understanding
|
|
- Testing environment setup
|
|
|
|
## Evolution of Project Decisions
|
|
|
|
### Memory Bank Organization
|
|
- Component documentation in separate files for:
|
|
- Clear organization
|
|
- Detailed documentation
|
|
- Easy information finding
|
|
- Incremental updates
|
|
- API component documentation separated to:
|
|
- Define critical interfaces
|
|
- Clarify system boundaries
|
|
- Track API changes and versioning
|
|
|
|
## Build and Test Information
|
|
Document for each component:
|
|
- Build commands
|
|
- Test commands
|
|
- Dependencies
|
|
- Common issues
|
|
- Performance considerations
|
|
|
|
Update documentation in:
|
|
1. Component docs in `memory-bank/components/`
|
|
2. This file for general patterns
|
|
3. `techContext.md` for significant patterns
|