Workspace Management
Relevant source files
The following files were used as context for generating this wiki page:
Workspace Management is a core system within ATMOS designed to handle the lifecycle, configuration, and isolation of development environments. It provides the infrastructure necessary to map physical project paths to logical "Workspaces" that can be managed via the web interface. This system ensures that developers can switch between different contexts, manage local paths, and maintain stateful configurations for individual projects.
The system spans the entire stack, from database entities that persist workspace metadata to specialized React components that provide a management interface. It integrates closely with the File System API to resolve local paths and the WebSocket-based service layer to perform CRUD operations on workspace data.
Architecture and Data Flow
The workspace architecture follows a typical client-service-database pattern. The frontend interacts with a WorkspaceService via WebSocket actions, which in turn interacts with the database layer.
System Flow
The following diagram illustrates the flow of a workspace creation request from the UI through the service layer to the database.
Data Model
The persistence layer for workspaces is defined using SeaORM entities. Each workspace is identified by a unique UUID and is associated with a specific local path on the host machine.
Workspace Entity Schema
| Field | Type | Description |
|---|---|---|
id | Uuid | Primary key identifying the workspace. |
name | String | A descriptive name for the workspace. |
local_path | String | The absolute path on the file system where the project resides. |
created_at | DateTime | Timestamp of creation. |
updated_at | DateTime | Timestamp of the last modification. |
Sources: crates/infra/src/db/entities/workspace.rs:10-25
Frontend Management View
The WorkspacesManagementView component serves as the primary administrative interface for users. It allows for viewing existing workspaces, creating new ones, and deleting those that are no longer needed. It utilizes the useWorkspaceStore (referenced in implementation logic) to manage the global state of active and available workspaces.
Component Logic Flow
Service Layer Implementation
The WorkspaceService in the core-service crate handles the business logic for workspace operations. It is responsible for translating WebSocket requests into database queries and ensuring data integrity.
Key Service Operations
- List Workspaces: Retrieves all persisted workspace entries from the database.
- Get Workspace: Fetches a specific workspace by its ID.
- Create Workspace: Validates the provided name and path before persisting a new entity.
- Delete Workspace: Removes a workspace entry and potentially cleans up associated metadata.
// Representative structure of workspace service logic
pub async fn create_workspace(
&self,
name: String,
local_path: String
) -> Result<workspace::Model, Error> {
// Logic to insert into DB via SeaORM
}
Sources: crates/core-service/src/service/workspace.rs:15-60
Integration with Wiki System
Workspaces act as the primary context for the Project Wiki system. When the Wiki tab is accessed, the system derives an effectivePath based on the current workspace's localPath. This ensures that documentation is correctly scoped to the active project environment.
Path Resolution Logic
Conclusion
Workspace Management provides the foundational context for all operations within ATMOS. By mapping physical file system locations to managed logical entities, it enables features like scoped documentation, project-specific terminals, and persistent environment configurations. The tight integration between the Rust core services and the React frontend ensures a seamless experience for managing complex multi-project workflows.