admin/docs/core-modules/file-manager

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	apps/backend/app/base_modules/FileManager/
Backend storage config	apps/backend/config/drive.ts
Backend S3 adapter	apps/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	API routes, services, storage adapter contract, permissions, and extension points.
Frontend	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.
• Create and edit image map zones for supported 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

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:

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	apps/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
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.