# File Manager Module

The File Manager module provides authenticated file browsing and file operations for the admin app. It has a backend API for storage operations and a frontend UI for browsing, previewing, uploading, renaming, deleting, duplicating, and editing supported files.

## Source Map

| Area                   | Path                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------- |
| Backend module         | `backend/app/base_modules/FileManager/`                                               |
| Backend storage config | `backend/config/drive.ts`                                                             |
| Backend S3 adapter     | `backend/app/base_modules/FileManager/services/storage_service/s3_storage_service.ts` |
| Frontend module        | `apps/admin/src/core/FileManager/`                                                    |
| Frontend file assets   | `apps/admin/public/media/files/`                                                      |
| Frontend routes        | `apps/admin/src/core/FileManager/config/routing.tsx`                                  |

## Documentation

| Page                      | Purpose                                                                            |
| ------------------------- | ---------------------------------------------------------------------------------- |
| [Backend](./backend.md)   | API routes, services, storage adapter contract, permissions, and extension points. |
| [Frontend](./frontend.md) | UI structure, React Query and MobX, cache updates, pages, and widgets.             |

## Main Capabilities

- Browse folders and files.
- Filter, sort, and paginate directory entries.
- Preview file details and text content for supported extensions.
- Stream raw files for preview or download.
- Create folders.
- Upload files with progress and cancellation support.
- Rename, delete, and duplicate entries.
- Search entries.
- Open an image editor for image files.
- Pick files through reusable frontend picker components.
- Insert files into RichText editor through reusable frontend picker components.
- Use local filesystem storage or S3-compatible storage through Adonis Drive.

## High-Level Flow

```txt
Admin route
  -> FileManager frontend page
  -> React Query API hook
  -> /file-manager backend route
  -> FileManagerController
  -> FileManagerService
  -> StorageService adapter
  -> Adonis Drive fs or s3 disk
```

## Data Contract

Backend responses use `Entry` objects:

```ts
type Entry = FileEntry | FolderEntry;

type FileEntry = {
  type: "file";
  name: string;
  path: string;
  url: string;
  size?: number;
  updatedAt?: string;
};

type FolderEntry = {
  type: "folder";
  name: string;
  path: string;
  updatedAt?: string;
};
```

The frontend maps DTOs into frontend entities and adds UI-oriented metadata such as `parent` and `extension`.

## Ownership Rules

- Backend owns storage, validation, authorization, path safety, and API response shape.
- Frontend owns navigation, selection, view settings, operation progress, and user interactions.
- React Query owns server state in the frontend.
- MobX stores own local UI and operation state in the frontend.
- Storage adapters must implement `storage_service_interface.ts`; callers should depend on that interface, not a concrete disk implementation.
- The active storage adapter is selected by `DRIVE_DISK`.

## Common Change Guide

| Change                                        | Start Here                                                                                                                             |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Add or change an API route                    | `backend/app/base_modules/FileManager/routes.ts` and `controller/file_manager_controller.ts`                                           |
| Change path validation or naming rules        | `services/path_service.ts`                                                                                                             |
| Change list filtering, sorting, or pagination | `services/entry_list_service.ts` and frontend query payloads                                                                           |
| Add or change a storage backend               | `services/storage_service/storage_service_interface.ts`, `create_storage_service.ts`, and [Backend storage docs](./backend.md#storage) |
| Add a frontend operation                      | `apps/admin/src/core/FileManager/data/queries/` and relevant store/widget                                                              |
| Add file type icons                           | `apps/admin/public/media/files/` and `shared/file/fileTypeImportMap.ts`                                                                |
| Add preview support                           | Backend `file_preview_service.ts` and frontend `view/ui/FilePreview/`                                                                  |

## Planned Work

- Add more non-filesystem storage adapters such as:
  - Google Cloud Storage
  - Supabase Storage
  - Digital Ocean Spaces
  - Cloudflare R2
- Add testing notes once module-level backend and frontend tests are established.
- Add libs for rendering large lists.