homeio

Purpose

The file manager browses FILES_ROOT, reads and writes text files, streams uploads/downloads, extracts archives, creates folders, copies/moves/renames entries, manages stars and trash, mounts SMB shares, exports local folders, shows USB drives, and integrates Google Drive accounts.

Locations

• Server-side: lib/server/modules/files/
• Client-side: modules/files/
• Routes: app/api/v1/files/

Key Files

File	Role
lib/server/modules/files/service.ts	Main filesystem service and FileServiceError
lib/server/modules/files/path-resolver.ts	resolvePathWithinFilesRoot() path jail
lib/server/modules/files/trash-service.ts	Trash move/restore/delete
lib/server/modules/files/network-storage.ts	SMB mount/discovery
lib/server/modules/files/local-sharing.ts	Local folder sharing
lib/server/modules/files/usb-storage.ts	USB drive list/mount/unmount/eject
lib/server/modules/files/google-drive.ts	Google Drive token/connections
lib/server/modules/files/google-drive-api.ts	Google Drive file API operations
lib/server/modules/files/google-oauth-config.ts	Google OAuth client credential settings
services/upload-server/main.go	Bare-metal upload sidecar for direct-to-disk uploads
modules/files/components/manager/file-manager.tsx	Main file manager container
modules/files/components/panels/google-drive-panel.tsx	Google Drive browser panel
modules/files/components/dialogs/file-manager-dialogs.tsx	File manager modal dialogs, including upload progress
modules/files/components/manager/file-manager-state.ts	Reducer state shape
modules/files/hooks/files-api.ts	Fetch/XHR helpers, including abortable upload
modules/files/hooks/useFiles.ts	Main file query/mutation hook

Public API

• Server: listDirectory(), readFileForViewer(), writeTextFile(), uploadFiles(), pasteEntry(), renameEntry(), toggleStarEntry(), searchFiles(), unzipEntry()
• Client hooks: useFiles(), useNetworkShares(), useLocalFolderShares(), useTrashActions(), useUsbDrives(), useGoogleDrive(), useGoogleDriveFiles(), useUnzipFile()
• Components: FileManager, FileManagerSidebar, FileManagerToolbar, FileManagerView

Contracts

• lib/shared/contracts/files.ts
• lib/shared/contracts/usb.ts
• lib/shared/contracts/google-drive.ts

Database Tables

• files_network_shares
• files_local_shares
• files_google_drive_tokens
• files_trash_entries

API Routes Owned

• GET /api/v1/files
• GET /api/v1/files/root
• GET/PUT /api/v1/files/content
• GET /api/v1/files/asset
• GET /api/v1/files/download
• POST /api/v1/files/upload
• POST /api/v1/files/ops
• GET /api/v1/files/search
• GET /api/v1/files/starred
• GET /api/v1/files/zip
• POST /api/v1/files/trash/*
• GET/POST/DELETE /api/v1/files/network/shares*
• GET/POST /api/v1/files/network/discover/*
• GET/POST/DELETE /api/v1/files/shared/folders*
• GET /api/v1/files/usb
• GET /api/v1/files/usb/stream
• POST /api/v1/files/usb/[driveId]/mount|unmount|eject
• GET/POST/PATCH/DELETE /api/v1/files/google-drive/*
• GET/PUT/DELETE /api/v1/settings/google-oauth

Known Issues

• lib/server/modules/files/service.ts is very large.
• modules/files/components/manager/file-manager-state.ts has a large state shape.
• The audit found getCurrentEntries() in file-manager-derived.ts using unknown[] parameters.
• File routes are protected by requireApiSession(); path jailing remains the main filesystem safety control.
• Large uploads are stream-parsed by the Next route with busboy; bare-metal installs also build the Go upload sidecar at services/upload-server/main.go.
• Large uploads still depend on next.config.mjs experimental.proxyClientMaxBodySize: "10gb" and any external reverse-proxy body-size limits.
• Upload progress is shown in UploadProgressDialog; closing the dialog cancels the active XHR through an AbortController.
• Google Drive needs Settings → Integrations OAuth credentials before the connect flow can start.

How To Extend

To add a new file operation:

1. Add request/response types in lib/shared/contracts/files.ts.
2. Add server logic to lib/server/modules/files/service.ts or a focused file in lib/server/modules/files/.
3. Use resolvePathWithinFilesRoot() for any host path.
4. Add a route under app/api/v1/files/.
5. Add query/mutation support in modules/files/hooks/files-api.ts and useFiles.ts.
6. Wire UI in modules/files/components/manager/ or modules/files/components/dialogs/.
7. For upload changes, preserve AbortSignal cancellation in uploadFilesToPath() and avoid reintroducing full-body buffering.
8. For Google Drive changes, update lib/shared/contracts/google-drive.ts, query keys, and the Drive panel/hooks together.
9. Add server and route tests.