Workspace Browser Ecosystem

Relevant source files

The following files were used as context for generating this wiki page:

• src/components/workspace/workspace-browser.tsx
• src/hooks/services/workspace/use-workspace-data.ts
• src/lib/services/workspace/client.ts
• src/lib/services/workspace/helpers.ts
• src/lib/services/workspace/shared.ts
• src/hooks/services/workspace/use-workspace-dialog-handlers.ts
• src/components/workspace/workspace-job-result-view.tsx
• src/components/workspace/workspace-mini-browser.tsx

The Workspace Browser Ecosystem is a centralized management system for user data, job results, and shared resources within the platform. It provides a hierarchical file-system-like interface for users to organize biological data (such as contigs, reads, and genomes), manage computational job outputs, and collaborate via shared folders.

The ecosystem is built on a multi-layered architecture comprising React components for the UI, custom React hooks for data orchestration, and a dedicated API client for communicating with the underlying Workspace service. It supports two primary modes: Home mode, representing the user's private workspace, and Shared mode, encompassing items shared with the user or organizational root directories.

Sources: [src/components/workspace/workspace-browser.tsx:43-60], [src/hooks/services/workspace/use-workspace-data.ts:25-36]

Core Architecture and Components

The ecosystem follows a modular design where the WorkspaceBrowser acts as the primary shell, coordinating several specialized sub-components and hooks.

Component Hierarchy

• WorkspaceBrowser: The top-level container that manages state for searching, filtering, and view modes.
• WorkspaceDataTable: Renders the list of files and folders, handling selection and sorting logic.
• WorkspaceToolbar: Provides controls for searching, filtering by type, refreshing data, and triggering creation actions (folders/workspaces).
• WorkspaceBreadcrumbs: Navigation component that reflects the current path hierarchy and allows users to jump back to parent levels.
• WorkspaceActionBar: A contextual menu that appears when items are selected, providing actions like Download, Delete, Copy, and Move.
• WorkspaceMiniBrowser: A lightweight version of the browser used within dialogs for selecting destination paths during copy or move operations.

Sources: [src/components/workspace/workspace-browser.tsx:75-140], [src/components/workspace/workspace-mini-browser.tsx:96-120], [src/components/workspace/workspace-toolbar.tsx:50-70]

Data Flow Diagram

The following diagram illustrates the flow of data from the Workspace API through the orchestration hooks to the UI components.

Data Orchestration

The system uses specialized hooks to manage different data states based on the user's current location in the workspace.

useWorkspaceData

This hook is the central coordinator for data fetching. It determines which API calls to make based on the browser's current state:

• Home Mode: Fetches items from the current user's /home directory.
• Shared Root: Merges user workspaces with items explicitly shared with them.
• Path View: Fetches contents of a specific subdirectory.
• Job Result View: Specialized fetching for hidden dot-folders associated with computational jobs.

Sources: [src/hooks/services/workspace/use-workspace-data.ts:40-80], [src/components/workspace/workspace-job-result-view.tsx:90-110]

Item Processing and Sorting

Items are processed through filtering (by name or type) and sorting before being rendered. Sorting logic prioritizes folders and job results over files.

Sort Field	Logic Description
Folders First	Folders and job_result types are always moved to the top regardless of field sort.
Name	Case-insensitive alphabetical comparison of item names.
Size	Numerical comparison of bytes (folders often show 0 or null).
Creation Time	Comparison based on the timestamp derived from creation_time.

Sources: [src/lib/services/workspace/helpers.ts:145-185], [src/components/workspace/workspace-mini-browser.tsx:165-175]

Workspace Objects and Types

The ecosystem handles a wide variety of specialized biological and technical data types.

Type Categories

The system categorizes types into several groups defined in the workspace service types:

• Upload Types: contigs, reads, genbank_file, gff, etc.
• Viewable Types: pdb, pdf, json, html, txt.
• Group Types: genome_group, feature_group, experiment_group.
• Structural Types: folder, directory, job_result.

Sources: [src/lib/services/workspace/types.ts:320-450], [src/lib/services/workspace/helpers.ts:100-115]

Object Metadata Structure

Workspace objects are represented by a standardized metadata object transformed from the raw API response (which often returns items as positional arrays).

// Transformed object structure
{
  id: string;             // Index 4
  path: string;           // parent path (Index 2) + name (Index 0)
  name: string;           // Index 0
  type: string;           // Index 1
  creation_time: string;  // Index 3
  owner_id: string;       // Index 5
  size: number;           // Index 6
  user_permission: string;// Index 9 ('o', 'a', 'w', 'r', 'n')
  global_permission: string; // Index 10
}

Sources: [src/lib/services/workspace/helpers.ts:22-38], [src/lib/services/workspace/shared.ts:15-20]

Security and Permissions

Access control is enforced at both the UI and API levels based on user_permission and global_permission flags.

Permission Levels

Code	Level	Description
o	Owner	Full control, including deletion and permission management.
a	Admin	Administrative access similar to owner.
w	Write	Can upload, create folders, and modify items.
r	Read	View and download only.
n	None	No access (used primarily for global permissions).

The hasWriteAccess utility checks if either the user or global permission level includes 'o', 'a', or 'w'.

Sources: [src/lib/services/workspace/helpers.ts:125-142], [src/lib/services/workspace/shared.ts:10-15]

Job Result Integration

A unique feature of the Workspace Browser is the specialized handling of computational job outputs. When a workspace object has the type job_result, the browser switches to a WorkspaceJobResultView.

Job Result Architecture

Job results consist of a visible metadata object and a hidden "dot-folder" (e.g., .job_name) containing the actual output files.

API Integration

The WorkspaceApiClient handles JSON-RPC communication with the backend. It includes specific handling for methods like Workspace.ls, Workspace.get, and Workspace.list_permissions.

Core API Methods

Method	Params	Description
Workspace.ls	{ paths: string[] }	Lists contents of directories.
Workspace.get	{ objects: string[], metadata_only: boolean }	Retrieves object metadata or data.
Workspace.create	{ objects: [path, type, meta][] }	Creates folders or upload nodes.
Workspace.delete	{ objects: string[], force: boolean }	Removes objects; force allows non-empty folder deletion.
Workspace.copy	{ objects: [src, dest][], move: boolean }	Copies or moves objects between paths.

Sources: [src/lib/services/workspace/client.ts:50-130], [src/lib/services/workspace/methods/crud.ts:20-60]

User Interface Actions and Dialogs

The useWorkspaceDialogHandlers hook manages complex multi-step operations like deleting folders and ensuring write access before copy/move.

• Delete Validation: Before deletion, the system checks if folders are non-empty to warn the user.
• Write Access Verification: Before copying or moving, the ensureDestinationWriteAccess helper verifies permissions for the destination folder and its parent if creating a new name.
• Path Sanitization: All folder and workspace names are passed through sanitizePathSegment to ensure compatibility with the underlying storage system.

Sources: [src/hooks/services/workspace/use-workspace-dialog-handlers.ts:45-90], [src/lib/services/workspace/helpers.ts:310-350]

Conclusion

The Workspace Browser Ecosystem provides a robust, permission-aware interface for managing complex biological datasets. By abstracting the complexities of JSON-RPC communication and positional array parsing into a modern React-based architecture, it allows users to navigate large-scale data and computational results with a familiar file-browser experience.