# gkalian/amuzing-file-browser architecture

> Architecture diagram of the GitHub repository gkalian/amuzing-file-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gkalian/amuzing-file-browser
- Repository: https://github.com/gkalian/amuzing-file-browser

## Overview

Amuzing File Browser is a local-first web file manager: users browse and organize a configured directory, upload or download files, and preview images. The React app coordinates navigation, listing, selection, settings, and upload interactions; its API client connects those actions to an Express server. The server exposes filesystem, configuration, health, and public-media routes, with root-constrained path handling and host-based access rules. README capabilities are included where the tree supports them; several client hooks and server route implementations were not sampled, so their internal wiring is shown only at the documented/API boundary.

Main entry points: [`src/client/App.tsx`](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/App.tsx) (App coordinator), [`src/server/paths.ts`](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/paths.ts) (Root path mapping), [`src/server/app.ts`](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/app.ts) (Express app), [`src/server/routes/fsRoutes.ts`](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fsRoutes.ts) (Filesystem routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_ui["Browser interface"]
  node_client_entry["Client mount<br/>[main.tsx]"]
  node_app["App coordinator<br/>[App.tsx]"]
  node_browser_ui["Browser panes"]
  node_table_ui["File table<br/>[FileTable.tsx]"]
  node_modals_ui["Action modals<br/>[ModalLayout.tsx]"]
  node_upload_ui["Upload queue<br/>[UploadQueue.tsx]"]
end

subgraph group_client_state["Client workflows"]
  node_listing["Listing model<br/>[useListingModel.ts]"]
  node_selection["Selection<br/>[useSelection.ts]"]
  node_fs_actions["Filesystem actions<br/>[useFsActions.ts]"]
  node_uploads["Upload workflow<br/>[useUploads.ts]"]
  node_settings["Settings state<br/>[useSettings.ts]"]
  node_api_client["API client<br/>[apiClient.ts]"]
end

subgraph group_server["Server API"]
  node_server_app["Express app<br/>[app.ts]"]
  node_host_gate["Host access gate<br/>[hostGate.ts]"]
  node_fs_routes["Filesystem routes<br/>[fsRoutes.ts]"]
  node_list_routes["List and stat<br/>[listRoutes.ts]"]
  node_preview_routes["Image preview<br/>[previewRoutes.ts]"]
  node_mutation_routes["Filesystem mutations<br/>[mutationRoutes.ts]"]
  node_download_routes["Download routes<br/>[downloadRoutes.ts]"]
  node_config_routes["Config routes<br/>[configRoutes.ts]"]
  node_public_files["Public media files<br/>[files.ts]"]
  node_upload_handler["Multipart upload<br/>[app.ts]"]
end

subgraph group_storage["Filesystem access"]
  node_path_safety["Root and symlink safety<br/>[fsSafe.ts]"]
  node_path_mapping["Root path mapping<br/>[paths.ts]"]
  node_filesystem[("Served files")]
  node_settings_store[("Persisted settings<br/>[settings.ts]")]
end

node_user(("User"))
node_browser(("Web browser"))

node_user -->|"uses"| node_browser
node_browser -->|"loads app"| node_client_entry
node_client_entry -->|"mounts"| node_app
node_app -->|"renders"| node_browser_ui
node_app -->|"builds listing"| node_listing
node_app -->|"manages selection"| node_selection
node_app -->|"invokes actions"| node_fs_actions
node_app -->|"coordinates uploads"| node_uploads
node_app -->|"loads settings"| node_settings
node_app -->|"renders"| node_modals_ui
node_app -->|"renders progress"| node_upload_ui
node_browser_ui -->|"displays items"| node_table_ui
node_listing -->|"loads listings"| node_api_client
node_fs_actions -->|"calls filesystem API"| node_api_client
node_uploads -->|"sends uploads"| node_api_client
node_settings -->|"loads and saves config"| node_api_client
node_api_client -->|"HTTP requests"| node_server_app
node_server_app -->|"checks host"| node_host_gate
node_server_app -->|"registers routes"| node_fs_routes
node_server_app -->|"registers routes"| node_config_routes
node_server_app -->|"handles uploads"| node_upload_handler
node_server_app -->|"registers route"| node_public_files
node_fs_routes -->|"registers"| node_list_routes
node_fs_routes -->|"registers"| node_preview_routes
node_fs_routes -->|"registers"| node_mutation_routes
node_fs_routes -->|"registers"| node_download_routes
node_list_routes -->|"resolves paths"| node_path_mapping
node_list_routes -->|"checks symlinks"| node_path_safety
node_list_routes -->|"reads metadata"| node_filesystem
node_preview_routes -->|"resolves paths"| node_path_mapping
node_preview_routes -->|"streams image"| node_filesystem
node_mutation_routes -->|"resolves paths"| node_path_mapping
node_mutation_routes -->|"checks paths"| node_path_safety
node_mutation_routes -->|"changes entries"| node_filesystem
node_download_routes -->|"resolves paths"| node_path_mapping
node_download_routes -->|"streams file"| node_filesystem
node_upload_handler -->|"writes uploaded files"| node_filesystem
node_upload_handler -->|"maps saved paths"| node_path_mapping
node_public_files -->|"resolves paths"| node_path_mapping
node_public_files -->|"serves files"| node_filesystem
node_config_routes -->|"reads and writes"| node_settings_store
node_path_mapping -->|"constrains access"| node_filesystem

click node_client_entry "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/main.tsx"
click node_app "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/App.tsx"
click node_browser_ui "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/browser/FileBrowserPane.tsx"
click node_table_ui "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/filetable/FileTable.tsx"
click node_modals_ui "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/ModalLayout.tsx"
click node_upload_ui "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/upload/UploadQueue.tsx"
click node_listing "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/browser/useListingModel.ts"
click node_selection "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/selection/useSelection.ts"
click node_fs_actions "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/data/useFsActions.ts"
click node_uploads "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/uploads/useUploads.ts"
click node_settings "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/ui/useSettings.ts"
click node_api_client "https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/services/apiClient.ts"
click node_server_app "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/app.ts"
click node_host_gate "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/middleware/hostGate.ts"
click node_fs_routes "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fsRoutes.ts"
click node_list_routes "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/listRoutes.ts"
click node_preview_routes "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/previewRoutes.ts"
click node_mutation_routes "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/mutationRoutes.ts"
click node_download_routes "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/downloadRoutes.ts"
click node_config_routes "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/configRoutes.ts"
click node_public_files "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/files.ts"
click node_upload_handler "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/app.ts"
click node_path_safety "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/lib/fsSafe.ts"
click node_path_mapping "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/paths.ts"
click node_settings_store "https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/lib/settings.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_entry,node_app,node_browser_ui,node_table_ui,node_modals_ui,node_upload_ui,node_user,node_browser toneBlue
class node_listing,node_selection,node_fs_actions,node_uploads,node_settings,node_api_client toneAmber
class node_server_app,node_host_gate,node_fs_routes,node_list_routes,node_preview_routes,node_mutation_routes,node_download_routes,node_config_routes,node_public_files,node_upload_handler toneMint
class node_path_safety,node_path_mapping,node_filesystem,node_settings_store toneRose
```

## Components

### Browser interface

- [Client mount](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/main.tsx): `src/client/main.tsx`
- [App coordinator](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/App.tsx): `src/client/App.tsx`
- [Browser panes](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/browser/FileBrowserPane.tsx): `src/client/components/browser/FileBrowserPane.tsx`
- [File table](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/filetable/FileTable.tsx): `src/client/components/filetable/FileTable.tsx`
- [Action modals](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/ModalLayout.tsx): `src/client/components/ModalLayout.tsx`
- [Upload queue](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/components/upload/UploadQueue.tsx): `src/client/components/upload/UploadQueue.tsx`

### Client workflows

- [Listing model](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/browser/useListingModel.ts): `src/client/hooks/browser/useListingModel.ts`
- [Selection](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/selection/useSelection.ts): `src/client/hooks/selection/useSelection.ts`
- [Filesystem actions](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/data/useFsActions.ts): `src/client/hooks/data/useFsActions.ts`
- [Upload workflow](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/uploads/useUploads.ts): `src/client/hooks/uploads/useUploads.ts`
- [Settings state](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/hooks/ui/useSettings.ts): `src/client/hooks/ui/useSettings.ts`
- [API client](https://github.com/gkalian/amuzing-file-browser/blob/main/src/client/services/apiClient.ts): `src/client/services/apiClient.ts`

### Server API

- [Express app](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/app.ts): `src/server/app.ts`
- [Host access gate](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/middleware/hostGate.ts): `src/server/middleware/hostGate.ts`
- [Filesystem routes](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fsRoutes.ts): `src/server/routes/fsRoutes.ts`
- [List and stat](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/listRoutes.ts): `src/server/routes/fs/listRoutes.ts`
- [Image preview](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/previewRoutes.ts): `src/server/routes/fs/previewRoutes.ts`
- [Filesystem mutations](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/mutationRoutes.ts): `src/server/routes/fs/mutationRoutes.ts`
- [Download routes](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/fs/downloadRoutes.ts): `src/server/routes/fs/downloadRoutes.ts`
- [Config routes](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/configRoutes.ts): `src/server/routes/configRoutes.ts`
- [Public media files](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/routes/files.ts): `src/server/routes/files.ts`
- [Multipart upload](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/app.ts): `src/server/app.ts`

### Filesystem access

- [Root and symlink safety](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/lib/fsSafe.ts): `src/server/lib/fsSafe.ts`
- [Root path mapping](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/paths.ts): `src/server/paths.ts`
- **Served files**
- [Persisted settings](https://github.com/gkalian/amuzing-file-browser/blob/main/src/server/lib/settings.ts): `src/server/lib/settings.ts`

### Other components

- **User**
- **Web browser**

## Connections

- User → Web browser: uses
- Web browser → Client mount: loads app
- Client mount → App coordinator: mounts
- App coordinator → Browser panes: renders
- App coordinator → Listing model: builds listing
- App coordinator → Selection: manages selection
- App coordinator → Filesystem actions: invokes actions
- App coordinator → Upload workflow: coordinates uploads
- App coordinator → Settings state: loads settings
- App coordinator → Action modals: renders
- App coordinator → Upload queue: renders progress
- Browser panes → File table: displays items
- Listing model → API client: loads listings
- Filesystem actions → API client: calls filesystem API
- Upload workflow → API client: sends uploads
- Settings state → API client: loads and saves config
- API client → Express app: HTTP requests
- Express app → Host access gate: checks host
- Express app → Filesystem routes: registers routes
- Express app → Config routes: registers routes
- Express app → Multipart upload: handles uploads
- Express app → Public media files: registers route
- Filesystem routes → List and stat: registers
- Filesystem routes → Image preview: registers
- Filesystem routes → Filesystem mutations: registers
- Filesystem routes → Download routes: registers
- List and stat → Root path mapping: resolves paths
- List and stat → Root and symlink safety: checks symlinks
- List and stat → Served files: reads metadata
- Image preview → Root path mapping: resolves paths
- Image preview → Served files: streams image
- Filesystem mutations → Root path mapping: resolves paths
- Filesystem mutations → Root and symlink safety: checks paths
- Filesystem mutations → Served files: changes entries
- Download routes → Root path mapping: resolves paths
- Download routes → Served files: streams file
- Multipart upload → Served files: writes uploaded files
- Multipart upload → Root path mapping: maps saved paths
- Public media files → Root path mapping: resolves paths
- Public media files → Served files: serves files
- Config routes → Persisted settings: reads and writes
- Root path mapping → Served files: constrains access