File & Folder Management

Relevant source files

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

• apps/api/src/module/workspace/controllers/files.controller.ts
• apps/api/src/module/workspace/controllers/folders.controller.ts
• apps/api/src/module/workspace/services/files.service.ts
• apps/api/src/module/workspace/services/folders.service.ts
• apps/api/src/module/workspace/services/utilities.service.ts
• apps/portal/components/pagesComponents/_imagesScreen/components/folderItem/FolderItem.tsx
• apps/portal/components/pagesComponents/_imagesScreen/pages/workspace/WorkspaceItemsContainer.tsx
• apps/api/src/module/atlassian/atlassian.service.ts

The File & Folder Management system provides the core organizational structure for user-generated content within a workspace. It allows users to create a hierarchical folder structure to manage their images and videos, facilitating better organization and collaboration. The system is built around a set of RESTful API endpoints that handle operations for creating, updating, deleting, and moving folders and files.

This system is primarily implemented in the apps/api module, with controllers handling HTTP requests and services containing the business logic for interacting with the Firebase Realtime Database. The frontend components in apps/portal and apps/extensions consume these APIs to provide a user interface for managing workspace content.

Architecture Overview

The management of files and folders follows a standard three-tier architecture. Client requests from the web portal or browser extension are routed to the API controllers, which then delegate the business logic to the corresponding services. These services interact with the Firebase database to persist data.

This diagram shows the high-level flow for a file or folder operation.

Folder Management

Folder management is handled by WorkspaceFoldersService and exposed via FoldersController. It supports creating, updating, and deleting folders within a workspace.

Folder Data Structure

Folders are defined by the IWorkspaceFolder interface. Each folder has properties to manage its position in the hierarchy, appearance, and content.

Property	Type	Description
id	string	A unique identifier generated using nanoid.
creator	string	The UID of the user who created the folder.
name	string	The display name of the folder.
color	string	A string representing the folder's color.
parentId	`string	false`
nestLevel	number	The depth of the folder in the hierarchy. Max level is 2.
items	number	A count of the files directly within the folder.
created	string	ISO string timestamp of creation date.
updated	string	ISO string timestamp of the last update.
children	any[]	An array to hold child folders (appears unused in the logic).
isPublic	boolean	A flag to indicate if the folder is public.
rootFolderId	`string	false`

Sources: apps/api/src/module/workspace/services/folders.service.ts:10-11, apps/api/src/module/workspace/Interfaces/Folders.ts

API Endpoints

The following endpoints are available for folder management under the base path /api/v1/workspace/:workspaceId/folders.

Method	Endpoint	Description	Controller Method
POST	/	Creates a new folder in the specified workspace.	createWorkspaceFolder
PUT	/:folderId	Updates an existing folder's data (e.g., name, color).	updateFolderData
DELETE	/:folderId	Deletes a folder and its sub-folders.	deleteFolder

Sources: apps/api/src/module/workspace/controllers/folders.controller.ts:16-41

Core Operations

Folder Creation

When a user creates a folder, the createWorkspaceFolder service method is called. It generates a new folder object, assigns a unique ID, and adds it to the folders map in the workspace's database entry. The nesting level is limited to a maximum of 2.

This sequence diagram illustrates the folder creation process.

Folder Deletion

Deleting a folder is a recursive operation. The deleteFolder method in WorkspaceFoldersService uses the removeChildFoldersRecursive utility to identify the target folder and all its descendants.

1. All items (screenshots and videos) within the deleted folders have their parentId reset to false, effectively moving them to the root of the workspace.
2. The item counts of parent folders are updated recursively.
3. The folder and its children are removed from the workspace's folders object in Firebase.
4. The folder is also removed from any user's favoriteFolders list.

Sources: apps/api/src/module/workspace/services/folders.service.ts:129-210, apps/api/src/module/workspace/services/utilities.service.ts:49-70

File Management

File management primarily involves moving files (images and videos) between folders. This is handled by the moveItemsToFolder method in WorkspaceFoldersService.

API Endpoints

Method	Endpoint	Description	Controller Method
POST	/files/move	Moves one or more files to a different folder within the workspace.	moveFilesToFolder

Sources: apps/api/src/module/workspace/controllers/files.controller.ts:15-28

Moving Files

The process of moving files involves updating the parentId of each file to the ID of the destination folder.

1. The service retrieves the workspace data.
2. It iterates through the provided list of itemIds.
3. For each item, it verifies that the requesting user has WRITE access. Access is granted if the user is the workspace admin, the item owner, or has sufficient permissions defined on the item itself.
4. If access is granted, the item's parentId is updated to the toMoveFolderId.
5. The item counts for both the source (fromFolderId) and destination (toMoveFolderId) folders are recursively updated using changeFolderItemCountRecursive.
6. The updated workspace object, including modified files and folders, is saved to Firebase.

This sequence diagram shows the flow for moving files.

Integrations

The system also supports integrations with third-party services like Jira and Trello, allowing users to create issues or cards with file attachments directly from the application.

Jira & Trello Issue Creation

When a user creates a Jira issue or a Trello card from a file:

1. The backend service (AtlassianService) retrieves the file data (image or video).
2. It constructs a request to the respective Atlassian API (Jira or Trello) to create the issue/card with a title and description.
3. If the issue/card is created successfully, the service fetches the file's content as a stream.
4. This stream is then sent as a file attachment to the newly created Jira issue or Trello card.

Conclusion

The File & Folder Management system is a crucial component of the ever-rec platform, providing a robust and flexible way to organize content within collaborative workspaces. By leveraging NestJS for a structured backend and Firebase for a scalable database, it offers essential features like hierarchical folder structures, permission-aware file operations, and recursive updates for maintaining data integrity. The clear separation of concerns between controllers and services makes the system maintainable and extensible for future features.