Initial commit

2026-06-25 15:53:49 +03:00
commit 1bb0b7e68a
1517 changed files with 218469 additions and 0 deletions
@@ -0,0 +1,106 @@
+# 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.