112 lines
5.5 KiB
Markdown
112 lines
5.5 KiB
Markdown
# 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](./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.
|
|
- 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
|
|
|
|
```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 | `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](./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.
|