# ryftcore/omni-fs architecture

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

- Interactive diagram: https://gitdiagram.com/ryftcore/omni-fs
- Repository: https://github.com/ryftcore/omni-fs

## Overview

omni-fs is a remote-filesystem client, currently delivered as a VS Code extension over a shared, host-independent core and protocol providers. The main workflow is to configure and test a connection, connect to a remote provider, then browse and edit remote files through VS Code; workspace mounts make them available to normal editor features. The README also documents connection management, capability-aware behavior, and transfer tracking. Some host wiring and provider implementations were not sampled, so those links are limited to documented responsibilities; upload/download execution is explicitly still planned.

Main entry points: [`packages/core/src/connection/manager.ts`](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/connection/manager.ts) (Connection manager), [`apps/vscode/src/extension.ts`](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/extension.ts) (Extension entry), [`apps/vscode/src/commands/index.ts`](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/commands/index.ts) (Commands), [`apps/vscode/src/webview/connection-manager-panel.ts`](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/webview/connection-manager-panel.ts) (Connection panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["VS Code host"]
  node_extension["Extension entry<br/>[extension.ts]"]
  node_commands["Commands<br/>[index.ts]"]
  node_fsadapter["Filesystem adapter"]
  node_mounts["Workspace mounts"]
  node_connectionsview["Connections tree"]
  node_transferview["Transfers tree<br/>[transfers-tree.ts]"]
  node_panel["Connection panel"]
end

subgraph group_ui["Connection UI"]
  node_webui["Connection manager UI"]
  node_controller["UI controller"]
  node_backend["UI backend port"]
end

subgraph group_core["Shared core"]
  node_config["Connection settings<br/>[config-store.ts]"]
  node_secrets["Secret storage port<br/>[connection.ts]"]
  node_manager["Connection manager<br/>[manager.ts]"]
  node_registry["Provider registry<br/>[registry.ts]"]
  node_managedfs["Managed filesystem"]
  node_cache["Entry cache<br/>[entry-cache.ts]"]
  node_queue["Transfer queue<br/>[queue.ts]"]
end

subgraph group_providers["Protocol providers"]
  node_s3["S3 provider<br/>[s3-file-system.ts]"]
  node_ftp["FTP provider<br/>[ftp-file-system.ts]"]
  node_sftp["SFTP provider"]
  node_webdav["WebDAV provider"]
end

node_user(("User"))
node_vscode(("VS Code"))
node_remote[("Remote storage")]

node_user -->|"uses"| node_extension
node_vscode -->|"hosts"| node_extension
node_extension -->|"registers"| node_commands
node_extension -->|"registers"| node_fsadapter
node_extension -->|"registers"| node_connectionsview
node_extension -->|"registers"| node_transferview
node_commands -->|"opens"| node_panel
node_panel -->|"renders"| node_webui
node_webui -->|"uses"| node_controller
node_controller -->|"requests"| node_backend
node_panel -->|"reads settings"| node_config
node_panel -->|"reads state"| node_manager
node_panel -->|"reads credentials"| node_secrets
node_commands -->|"connects"| node_manager
node_commands -->|"mounts"| node_mounts
node_mounts -->|"adds workspace"| node_vscode
node_fsadapter -->|"acquires filesystem"| node_manager
node_manager -->|"loads config"| node_config
node_manager -->|"selects provider"| node_registry
node_manager -->|"loads credentials"| node_secrets
node_manager -->|"manages connection"| node_managedfs
node_managedfs -->|"caches entries"| node_cache
node_manager -->|"creates provider"| node_s3
node_manager -->|"creates provider"| node_ftp
node_manager -->|"creates provider"| node_sftp
node_manager -->|"creates provider"| node_webdav
node_s3 -->|"reads and writes"| node_remote
node_ftp -->|"reads and writes"| node_remote
node_sftp -->|"reads and writes"| node_remote
node_webdav -->|"reads and writes"| node_remote
node_transferview -->|"shows tasks"| node_queue
node_commands -->|"manages tasks"| node_queue

click node_extension "https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/extension.ts"
click node_commands "https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/commands/index.ts"
click node_fsadapter "https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/fs/omni-file-system-provider.ts"
click node_mounts "https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/workspace/workspace-mounts.ts"
click node_connectionsview "https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/views/connections-tree.ts"
click node_transferview "https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/views/transfers-tree.ts"
click node_panel "https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/webview/connection-manager-panel.ts"
click node_webui "https://github.com/ryftcore/omni-fs/blob/main/packages/ui/src/components/ConnectionManagerApp.tsx"
click node_controller "https://github.com/ryftcore/omni-fs/blob/main/packages/ui/src/model/use-connection-manager.ts"
click node_backend "https://github.com/ryftcore/omni-fs/blob/main/packages/ui/src/ports/connections-backend.ts"
click node_config "https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/ports/config-store.ts"
click node_secrets "https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/model/connection.ts"
click node_manager "https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/connection/manager.ts"
click node_registry "https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/registry.ts"
click node_managedfs "https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/fs/managed-file-system.ts"
click node_cache "https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/cache/entry-cache.ts"
click node_queue "https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/transfer/queue.ts"
click node_s3 "https://github.com/ryftcore/omni-fs/blob/main/packages/provider-s3/src/s3-file-system.ts"
click node_ftp "https://github.com/ryftcore/omni-fs/blob/main/packages/provider-ftp/src/ftp-file-system.ts"
click node_sftp "https://github.com/ryftcore/omni-fs/blob/main/packages/provider-sftp/src/sftp-file-system.ts"
click node_webdav "https://github.com/ryftcore/omni-fs/blob/main/packages/provider-webdav/src/webdav-file-system.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_extension,node_commands,node_fsadapter,node_mounts,node_connectionsview,node_transferview,node_panel,node_user toneBlue
class node_webui,node_controller,node_backend,node_remote toneAmber
class node_config,node_secrets,node_manager,node_registry,node_managedfs,node_cache,node_queue toneMint
class node_s3,node_ftp,node_sftp,node_webdav toneRose
class node_vscode toneIndigo
```

## Components

### VS Code host

- [Extension entry](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/extension.ts): `apps/vscode/src/extension.ts`
- [Commands](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/commands/index.ts): `apps/vscode/src/commands/index.ts`
- [Filesystem adapter](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/fs/omni-file-system-provider.ts): `apps/vscode/src/fs/omni-file-system-provider.ts`
- [Workspace mounts](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/workspace/workspace-mounts.ts): `apps/vscode/src/workspace/workspace-mounts.ts`
- [Connections tree](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/views/connections-tree.ts): `apps/vscode/src/views/connections-tree.ts`
- [Transfers tree](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/views/transfers-tree.ts): `apps/vscode/src/views/transfers-tree.ts`
- [Connection panel](https://github.com/ryftcore/omni-fs/blob/main/apps/vscode/src/webview/connection-manager-panel.ts): `apps/vscode/src/webview/connection-manager-panel.ts`

### Connection UI

- [Connection manager UI](https://github.com/ryftcore/omni-fs/blob/main/packages/ui/src/components/ConnectionManagerApp.tsx): `packages/ui/src/components/ConnectionManagerApp.tsx`
- [UI controller](https://github.com/ryftcore/omni-fs/blob/main/packages/ui/src/model/use-connection-manager.ts): `packages/ui/src/model/use-connection-manager.ts`
- [UI backend port](https://github.com/ryftcore/omni-fs/blob/main/packages/ui/src/ports/connections-backend.ts): `packages/ui/src/ports/connections-backend.ts`

### Shared core

- [Connection settings](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/ports/config-store.ts): `packages/core/src/ports/config-store.ts`
- [Secret storage port](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/model/connection.ts): `packages/core/src/model/connection.ts`
- [Connection manager](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/connection/manager.ts): `packages/core/src/connection/manager.ts`
- [Provider registry](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/registry.ts): `packages/core/src/registry.ts`
- [Managed filesystem](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/fs/managed-file-system.ts): `packages/core/src/fs/managed-file-system.ts`
- [Entry cache](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/cache/entry-cache.ts): `packages/core/src/cache/entry-cache.ts`
- [Transfer queue](https://github.com/ryftcore/omni-fs/blob/main/packages/core/src/transfer/queue.ts): `packages/core/src/transfer/queue.ts`

### Protocol providers

- [S3 provider](https://github.com/ryftcore/omni-fs/blob/main/packages/provider-s3/src/s3-file-system.ts): `packages/provider-s3/src/s3-file-system.ts`
- [FTP provider](https://github.com/ryftcore/omni-fs/blob/main/packages/provider-ftp/src/ftp-file-system.ts): `packages/provider-ftp/src/ftp-file-system.ts`
- [SFTP provider](https://github.com/ryftcore/omni-fs/blob/main/packages/provider-sftp/src/sftp-file-system.ts): `packages/provider-sftp/src/sftp-file-system.ts`
- [WebDAV provider](https://github.com/ryftcore/omni-fs/blob/main/packages/provider-webdav/src/webdav-file-system.ts): `packages/provider-webdav/src/webdav-file-system.ts`

### Other components

- **User**
- **VS Code**
- **Remote storage**

## Connections

- User → Extension entry: uses
- VS Code → Extension entry: hosts
- Extension entry → Commands: registers
- Extension entry → Filesystem adapter: registers
- Extension entry → Connections tree: registers
- Extension entry → Transfers tree: registers
- Commands → Connection panel: opens
- Connection panel → Connection manager UI: renders
- Connection manager UI → UI controller: uses
- UI controller → UI backend port: requests
- Connection panel → Connection settings: reads settings
- Connection panel → Connection manager: reads state
- Connection panel → Secret storage port: reads credentials
- Commands → Connection manager: connects
- Commands → Workspace mounts: mounts
- Workspace mounts → VS Code: adds workspace
- Filesystem adapter → Connection manager: acquires filesystem
- Connection manager → Connection settings: loads config
- Connection manager → Provider registry: selects provider
- Connection manager → Secret storage port: loads credentials
- Connection manager → Managed filesystem: manages connection
- Managed filesystem → Entry cache: caches entries
- Connection manager → S3 provider: creates provider
- Connection manager → FTP provider: creates provider
- Connection manager → SFTP provider: creates provider
- Connection manager → WebDAV provider: creates provider
- S3 provider → Remote storage: reads and writes
- FTP provider → Remote storage: reads and writes
- SFTP provider → Remote storage: reads and writes
- WebDAV provider → Remote storage: reads and writes
- Transfers tree → Transfer queue: shows tasks
- Commands → Transfer queue: manages tasks