Workspace file architecture

Request and state flow

Oqullus owns browser state, selected folder, page-local filters, open editor tabs, and transient favorites. The backend owns canonical public IDs, hierarchy, display paths, ACL rows, trash state, and history metadata. Object storage owns current bytes and, only when bucket versioning is enabled, historical bytes.

Routing boundary

The browser calls BFF /workspace/v2 routes. The BFF validates the user token, exchanges it for the workspace-file audience, and proxies to backend /workspace routes. Uploads use BFF multer.memoryStorage; content downloads stream backend to BFF, while Oqullus materializes the response as a Blob.

The backend and BFF expose a presigned file-resolution endpoint, but Oqullus does not use it. Backend multipart-upload service methods have no matching HTTP, BFF, or UI contract in the reviewed baselines.

Identity and authorization

Files and folders have stable UUID public IDs. Rename and move update PostgreSQL metadata without changing the object key. Effective permission is the highest direct file grant or ancestor-folder grant:

Role	Effective operations
Viewer	List and read
Editor	Viewer operations plus content edit, rename, and move
Maintainer	Editor operations plus share and delete

Grants target users by email. Group grants are not implemented. Ancestor rows may be returned as traversal-only folders so a user can reach a directly shared descendant.

The deployed backend chooses preferred_username, then falls back through client claims and sub, and stores that value as root name, ACL subject, owner, and audit actor. Email/member selection in Oqullus is therefore coupled to a mutable display identity rather than one immutable account subject. Backend main separates root display name from owner_id, but the owner and ACL value is still the selected username string.

The workflow output-notebook route is a separate exception: it accepts a valid workspace user plus dag_id, task_id, run_id, and try_number, constructs an object key, and reads it without checking access to that workflow run. See SEC-WSF-001.

Persistence and consistency

PostgreSQL and object storage do not share a transaction. Create, update, clone, and revert mutate object storage before committing metadata. Permanent deletion deletes object storage before committing metadata deletion. There is no outbox, operation record, compensation, or reconciliation job in the reviewed source.

History rows store an object version ID. The shared platform-stacks bucket contract only creates or adopts buckets; it does not declare or reconcile versioning on either AliCloud OSS or AWS S3. A live read of the assessed OSS Workspace bucket confirmed the default unversioned state. The deployment consequently has no recorded version IDs, so history metadata cannot retrieve older bytes. Enabling versioning later protects only subsequent writes; it does not reconstruct content already overwritten.

Listing and query boundaries

Folder and shared-item endpoints return full authorized collections. Trash applies the same offset and limit separately to folders and files and returns no combined total. Search applies name predicates, materializes all matching files, filters permissions in Python, builds all paths, and only then slices the page. Oqullus does not call the backend search route and paginates loaded arrays in the browser.

Deployment boundary

The assessed KCL config deploys:

• two workspace-file backend replicas;
• one KubeBlocks PostgreSQL replica with a 20 GiB volume;
• 100m CPU and 256 MiB memory requests per API replica, with 250m/512 MiB limits;
• the shared workspace S3 or OSS bucket under prefix workspace-file-management/;
• backend image 5dcbb22 in w-t5e2kcxjd.

The PostgreSQL component disables its exporter and uses termination policy Delete. No workspace-file-specific backup, point-in-time recovery, capacity alert, or restore exercise appears in the reviewed KCL.

Backend main adds explicit root ownership and provider-neutral storage error mapping, but is not the deployed baseline. It does not close the output-notebook authorization, transfer, versioning, cleanup, pagination, or consistency gaps.

Observability and recovery

The service returns HTTP errors through the BFF and emits application/container logs. No file-operation correlation ID, cross-store reconciliation metric, upload-size metric, orphan-object alert, trash-cleanup alert, or history recoverability check was found in the assessed deployment source.

Oqullus catches several list errors and substitutes an empty array or retains old state, so the user cannot reliably distinguish no data from an unavailable backend. Recovery is manual refresh and retry.