update memory bank

Author: geropl

memory-bank/components/gitpod-db.md

@@ -49,7 +49,7 @@ The Gitpod DB component defines numerous entities that map to database tables, i
 - **User**: User accounts and profiles
 - **Workspace**: Workspace metadata and configuration
 - **WorkspaceInstance**: Running workspace instances
-- **Team**: Team organization and membership
+- **Team**: Represents an "Organization" within Gitpod, storing its core details, membership, and organization-level state (e.g., `maintenanceMode`). The entity is named `DBTeam` for historical reasons.
 - **Project**: Project configuration and settings
 - **Identity**: User identity and authentication
 - **Token**: Authentication tokens and credentials

memory-bank/components/public-api-server.md

@@ -120,7 +120,7 @@ The Public API Server is configured through a JSON configuration file:
 ## Integration Points
 
 The Public API Server integrates with:
-1. **Gitpod Server**: For core Gitpod functionality
+1. **Gitpod Server**: For core Gitpod functionality. The Public API Server often acts as a gRPC gateway, proxying requests to the Gitpod Server (TypeScript component) where the business logic for many `gitpod.v1` services (like `OrganizationService`) is implemented.
 2. **Database**: For persistent storage
 3. **Redis**: For caching and session management
 4. **Billing Service**: For billing-related operations

memory-bank/components/server.md

@@ -21,7 +21,7 @@ The primary purposes of the Server component are:
 
 The Server operates as an Express.js application with several key components:
 
-1. **API Server**: Provides HTTP and WebSocket endpoints for client communication
+1. **API Server**: Provides HTTP and WebSocket endpoints for client communication. It also directly hosts and implements `gitpod.v1` gRPC services (defined in `.proto` files within `components/public-api/`) for programmatic access.
 2. **Authentication System**: Handles user authentication and session management
 3. **Database Interface**: Interacts with the database for persistent storage
 4. **WebSocket Manager**: Manages real-time communication with clients
@@ -94,7 +94,7 @@ The Server supports multiple authentication methods:
 3. **OAuth Integration**: With GitHub, GitLab, Bitbucket, etc.
 4. **Personal Access Tokens**: For programmatic access
 
-Authorization is handled through a combination of user roles, permissions, and access controls.
+Authorization is handled through a combination of user roles and permissions, leveraging SpiceDB for fine-grained access control checks within its service implementations (including for gRPC services).
 
 ## Integration Points
 

memory-bank/components/spicedb.md

@@ -108,17 +108,13 @@ The schema defines various permissions for each entity type:
 
 ## Configuration
 
-The SpiceDB component is configured through a YAML schema file:
+The SpiceDB component's core configuration is its schema, defined in `components/spicedb/schema/schema.yaml`. This YAML file is central to Gitpod's authorization model and specifies:
+- **Object Definitions**: The types of resources being protected (e.g., `user`, `organization`, `project`, `workspace`).
+- **Relations**: How different objects can be related to each other (e.g., an `organization` has an `owner` which is a `user`; a `project` belongs to an `org`).
+- **Permissions**: What actions can be performed on objects, and how these permissions are derived from relations (e.g., `permission write_settings = owner + installation->admin` for an `organization`).
+- **Validation & Assertions**: Rules and tests to ensure the schema's integrity and correctness.
 
-```yaml
-schema/schema.yaml
-```
-
-This file defines:
-- Entity types (user, organization, project, workspace)
-- Relationships between entities
-- Permissions derived from these relationships
-- Validation rules and assertions for testing
+New permissions (like the `maintenance` permission for organizations) are added by modifying this schema file. Other components, such as the `server` component, then use a SpiceDB client to check these permissions at runtime to authorize operations.
 
 ## Integration Points
 

memory-bank/systemPatterns.md

@@ -112,7 +112,8 @@ Workspaces are treated as immutable, with changes to configuration resulting in
 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
+4. **Core Data Entities**: Key platform data (including User data, Organization/Team settings, Project details, Workspace configurations) is stored in the database (primarily MySQL, managed by `gitpod-db` component using TypeORM).
+    *   Notably, the `DBTeam` entity serves as the representation for "Organizations," storing organization-level details and settings. This is accessed via the Dashboard and various APIs.
 
 ## Key Technical Decisions
 
@@ -132,6 +133,10 @@ Workspaces are treated as immutable, with changes to configuration resulting in
 
 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.
 
+9. **Public API Architecture**: External programmatic access is provided via `gitpod.v1` gRPC services. These services are defined using Protocol Buffers (`.proto` files) located in the `components/public-api/gitpod/v1/` directory. The `server` component (TypeScript/Express.js based) directly implements and hosts these gRPC services. The `public-api-server` component (Go based) can act as an external-facing gRPC gateway.
+
+10. **Authorization with SpiceDB**: Fine-grained, relationship-based access control (ReBAC) is managed by SpiceDB. The authorization schema, defining resources, relationships, and permissions, is located in `components/spicedb/schema/schema.yaml`. Service implementations (e.g., within the `server` component) query SpiceDB to enforce these permissions.
+
 ## Development Workflows
 
 ### Product Requirements Document (PRD) Workflow