# faraday-fm/faraday architecture

> Architecture diagram of the GitHub repository faraday-fm/faraday, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faraday-fm/faraday
- Repository: https://github.com/faraday-fm/faraday

## Overview

##### Project type and purpose
- This is a monorepo for a single-page web application (“Faraday File Manager”) delivered via apps/faraday-fm.github.io.
- It uses a plugin/extension architecture: core UI (packages/web-ui), a browser-based in-memory file system (packages/memory-fs), a Web Worker–based extension host (packages/extension-host), command infrastructure (packages/commands), and shared SDK utilities (packages/sdk).
- The README describes an interactive, dual-pane file manager with file previews, custom themes, keyboard shortcuts, and built-in tools.

##### File structure
- Top-level “apps” holds the deployed SPA; “extensions” holds example viewer plugins (code, image, text); “packages” holds internal libraries.
- Key packages:
- web-ui: React components, contexts, feature hooks
- commands: command palette, keyboard shortcuts, provider/registry
- extension-host: worker entrypoint, message protocols, extension loading
- memory-fs: in-browser virtual file system
- sdk: file system API wrappers, error types, event types
- Config files: pnpm-workspace.yaml, turbo.json for monorepo orchestration; tsconfig and build configs for each package.

##### README for additional insights
- Faraday is purely client-side, no separate backend. The memory-fs simulates a file system entirely in browser memory or via WebSocket (wsfs.ts).
- Extensions live inside a virtual “.faraday” directory and are loaded into the extension host at runtime.
- The UI interacts with file system services and commands, and offloads extension code execution to a Web Worker.

a. Main components
- Browser / Client
- Faraday SPA (apps/faraday-fm.github.io)
- Web-UI component library (packages/web-ui)
- FS Service (src/services/fs.ts) + optional WSFS Service (wsfs.ts)
- Commands Provider (packages/commands)
- Extension Manager (feature hooks in web-ui)
- Extension Host (Web Worker) (packages/extension-host)
- In-Memory File System (packages/memory-fs)
- SDK Utilities (packages/sdk)
- Extensions (extensions/code-viewer, image-viewer, text-viewer)
b. Relationships & interactions
- SPA imports web-ui and commands libraries, mounts React root.
- FS Service calls into memory-fs API to read/write files; optionally uses WebSocket to a remote FS.
- Commands Provider registers keyboard shortcuts and exposes a command palette to UI.
- On demand, the SPA spins up a Web Worker running extension-host; communicates via postMessage.
- Extension-host loads extensions from the virtual FS, initializes them using sdk, and responds to messages (e.g., “render preview”).
- The SPA receives extension-host messages and renders output in appropriate viewer components.
c. Architectural patterns & principles
- Plugin architecture via extension host in a Web Worker.
- Command pattern for keyboard shortcuts and actions.
- React context providers for global state (file system, theme, settings).
- Monorepo with shared TypeScript configs and build scripts for efficiency.
- Separation of concerns: UI vs. file system vs. extension execution.
d. Key technologies & frameworks
- React + TypeScript + Vite (apps/faraday-fm.github.io)
- Lit-Contexts (web-ui) for lightweight context management
- Web Worker for isolation of untrusted extension code
- pnpm & TurboRepo for monorepo orchestration
- tsup/Rollup for bundling libraries

##### Detail without clutter
- Break the system into: Client App, UI Library, FS Subsystem, Extension Host, Extensions.
- Interface/interaction: React→Context→Command Registry→Worker.
- Don’t forget build/dev tools (pnpm, turbo.json, tsconfig) as an ancillary layer if desired.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application Layer
    subgraph "Client App"
        Main["main.tsx"]:::frontend
        AppComp["App.tsx"]:::frontend
    end

    %% UI Library Layer
    subgraph "Web-UI Component Library"
        UIIndex["index.tsx"]:::frontend
        FrdyApp["FrdyApp.ts"]:::frontend
    end

    %% Commands Infrastructure
    subgraph "Commands Infrastructure"
        CommandsProvider["CommandsProvider.ts"]:::shared
        CommandsRegistry["CommandsRegistry.ts"]:::shared
        KeyBindings["KeyBindingsController.ts"]:::shared
    end

    %% Filesystem Subsystem
    subgraph "FS Subsystem"
        FS["fs.ts"]:::service
        WSFS["wsfs.ts"]:::service
        subgraph "In-Memory File System"
            MemoryFsCore["MemoryFs.ts"]:::service
            MemoryFsIndex["index.ts"]:::service
        end
    end

    %% Shared SDK Utilities
    subgraph "Shared SDK Utilities"
        SDKFS["fs.ts"]:::shared
        SDKError["FileSystemError.ts"]:::shared
        SDKEvents["events.ts"]:::shared
    end

    %% Extension Management in UI
    subgraph "Extension Manager"
        ExtWorker["_extWorker.ts"]:::frontend
        ExtHooks["_hooks.ts"]:::frontend
    end

    %% Extension Host Worker
    subgraph "Extension Host Worker"
        WorkerEntry["worker.ts"]:::worker
        WorkerIndex["index.ts"]:::worker
    end

    %% Extensions
    subgraph "Extensions"
        subgraph "Code Viewer Extension"
            CVIndex["index.tsx"]:::extension
            CVApp["App.tsx"]:::extension
        end
        ImageIndex["index.tsx"]:::extension
        subgraph "Text Viewer Extension"
            TVIndex["index.tsx"]:::extension
            TVComp["TextViewer.tsx"]:::extension
        end
    end

    %% Connections
    Main -->|imports| UIIndex
    Main -->|imports| FrdyApp
    Main -->|uses| CommandsProvider
    CommandsProvider -->|registers| CommandsRegistry
    CommandsProvider -->|controls| KeyBindings
    Main -->|calls| FS
    FS -->|reads/writes| MemoryFsCore
    FS -->|optional ws| WSFS
    AppComp -->|uses hooks| ExtWorker
    AppComp -->|uses hooks| ExtHooks
    AppComp -->|spawns| WorkerEntry
    WorkerEntry <-->|postMessage| AppComp
    WorkerEntry -->|uses sdk| SDKFS
    WorkerEntry -->|handles errors| SDKError
    WorkerEntry -->|listens events| SDKEvents
    WorkerEntry -->|access| MemoryFsCore
    WorkerEntry -->|loads| CVIndex
    WorkerEntry -->|initializes| CVApp
    WorkerEntry -->|loads| ImageIndex
    WorkerEntry -->|loads| TVIndex
    WorkerEntry -->|uses| TVComp
    CVApp -->|renders in| AppComp
    ImageIndex -->|renders in| AppComp
    TVComp -->|renders in| AppComp

    %% Click Events
    click Main "https://github.com/faraday-fm/faraday/blob/main/apps/faraday-fm.github.io/src/main.tsx"
    click AppComp "https://github.com/faraday-fm/faraday/blob/main/apps/faraday-fm.github.io/src/App.tsx"
    click UIIndex "https://github.com/faraday-fm/faraday/blob/main/packages/web-ui/src/index.tsx"
    click FrdyApp "https://github.com/faraday-fm/faraday/blob/main/packages/web-ui/src/components/FrdyApp.ts"
    click FS "https://github.com/faraday-fm/faraday/blob/main/apps/faraday-fm.github.io/src/services/fs.ts"
    click WSFS "https://github.com/faraday-fm/faraday/blob/main/apps/faraday-fm.github.io/src/services/wsfs.ts"
    click CommandsProvider "https://github.com/faraday-fm/faraday/blob/main/packages/commands/src/CommandsProvider.ts"
    click CommandsRegistry "https://github.com/faraday-fm/faraday/blob/main/packages/commands/src/CommandsRegistry.ts"
    click KeyBindings "https://github.com/faraday-fm/faraday/blob/main/packages/commands/src/KeyBindingsController.ts"
    click ExtWorker "https://github.com/faraday-fm/faraday/blob/main/packages/web-ui/src/features/_extensions/_extWorker.ts"
    click ExtHooks "https://github.com/faraday-fm/faraday/blob/main/packages/web-ui/src/features/_extensions/_hooks.ts"
    click WorkerEntry "https://github.com/faraday-fm/faraday/blob/main/packages/extension-host/src/worker.ts"
    click WorkerIndex "https://github.com/faraday-fm/faraday/blob/main/packages/extension-host/src/index.ts"
    click MemoryFsCore "https://github.com/faraday-fm/faraday/blob/main/packages/memory-fs/src/MemoryFs.ts"
    click MemoryFsIndex "https://github.com/faraday-fm/faraday/blob/main/packages/memory-fs/src/index.ts"
    click SDKFS "https://github.com/faraday-fm/faraday/blob/main/packages/sdk/src/fs.ts"
    click SDKError "https://github.com/faraday-fm/faraday/blob/main/packages/sdk/src/FileSystemError.ts"
    click SDKEvents "https://github.com/faraday-fm/faraday/blob/main/packages/sdk/src/events.ts"
    click CVIndex "https://github.com/faraday-fm/faraday/blob/main/extensions/code-viewer/src/index.tsx"
    click CVApp "https://github.com/faraday-fm/faraday/blob/main/extensions/code-viewer/src/App.tsx"
    click ImageIndex "https://github.com/faraday-fm/faraday/blob/main/extensions/image-viewer/src/index.tsx"
    click TVIndex "https://github.com/faraday-fm/faraday/blob/main/extensions/text-viewer/src/index.tsx"
    click TVComp "https://github.com/faraday-fm/faraday/blob/main/extensions/text-viewer/src/TextViewer.tsx"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef service fill:#E2F0D9,stroke:#228B22,color:#228B22;
    classDef worker fill:#FFE5CC,stroke:#FF8C00,color:#FF8C00;
    classDef shared fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef extension fill:#F8E1F4,stroke:#C71585,color:#C71585;
```
