# swiftlatex/browserfs architecture

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

- Interactive diagram: https://gitdiagram.com/swiftlatex/browserfs
- Repository: https://github.com/swiftlatex/browserfs

## Overview

##### Project Type and Purpose
- BrowserFS is a JavaScript library (UMD module) that implements a Node-style file system API entirely in the browser (and optionally in Node).
- It provides a core file system abstraction, a registry of pluggable backends (IndexedDB, LocalStorage, HTTPRequest, Dropbox, ZipFS, IsoFS, etc.), and integration points for bundlers (Webpack/Browserify) and Emscripten.

##### File-Structure and Architectural Patterns
- src/index.ts: entry point, exports `BrowserFS` API.
- src/core/: core abstractions (FileSystem interface, File, FileFlag, API errors, util, backend registry, global shim).
- src/generic/: generic utilities and polyfills (fetch/XHR, setImmediate, mutex, preload, key-value FS).
- src/backend/: concrete backend implementations (InMemory, IndexedDB, S3 placeholder).
- Bundler configs: rollup.config.js, webpack.config.js, typedoc.ts.
- scripts/: build/test-harness helpers (DB creds, fixture loader, test launcher).
- test/: extensive test harness with backend factories, fixtures, unit tests.

a. Public API Layer (Client Application)
- BrowserFS.configure()
- BrowserFS.install(window) / require('browserfs')
- EmscriptenFS plugin integration
b. Core Abstraction Layer
- FileSystem interface
- File, Stats, Flags, API/Error handling
- Backend registry (backends.ts)
c. Pluggable Backend Layer
- InMemory, IndexedDB, LocalStorage (HTML5FS), HTTPRequest/Fetch, Dropbox, ZipFS, IsoFS, WorkerFS, AsyncMirror, OverlayFS, MountableFileSystem, FolderAdapter, Emscripten
d. Storage / External Service Layer
- Browser storage: localStorage, IndexedDB, HTML5 FileSystem API
- Remote: HTTP servers, Dropbox API, S3 (stub)
- Emscripten’s MEMFS/VFS
- Zip (DEFLATE) engine
e. Bundler & Build Pipeline (Dev/Deployment)
- TypeScript → JavaScript
- Rollup / Webpack / Browserify → dist/browserfs.js, dist/shims/fs.js, etc.
- Test harness via Karma/Mocha/Jasmine

##### Relationships & Data Flows
- Client invokes BrowserFS.configure() → Core creates appropriate FileSystem instances from backend registry → if using MountableFS, mounts multiple child backends at configured paths.
- File API calls (readFile/writeFile/stat/mkdir/etc.) route from Core → Generic utilities → selected Backend → underlying storage or network.
- Emscripten integration: preRun hook mounts BrowserFS via EmscriptenFS adapter into Module.FS.
- Bundler: consumes entry point, aliases Node built-ins to BrowserFS shims, produces UMD bundle.

##### Architectural Patterns & Principles
- Dependency Injection: backends selected/configured at runtime
- Adapter / Bridge: generic FS API wraps disparate storage engines
- Composite Pattern: MountableFileSystem composes multiple backends
- Decorator / Proxy: AsyncMirror, OverlayFS wrap other backends to augment behavior
- Plugin Architecture: new backends can be added by extending BaseFileSystem

## Diagram (Mermaid)

```mermaid
graph TB
    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        PublicAPI["Public API Layer"]:::public
        BrowserFS_config["BrowserFS.configure()"]:::public
        BrowserFS_install["BrowserFS.install()/require()"]:::public
        PublicAPI --> BrowserFS_config
        PublicAPI --> BrowserFS_install
    end

    %% Core Abstraction Layer
    subgraph "Core Abstraction Layer"
        direction TB
        FileSystem["FileSystem Interface"]:::core
        FileRep["File Representation"]:::core
        FileFlag["File Flags"]:::core
        NodeStats["Stats & NodeFSStats"]:::core
        APIError["API Error Handling"]:::core
        GlobalUtil["Global Shim & Utilities"]:::core
        BackendRegistry["Backend Registry"]:::core
    end

    %% Generic Utilities Layer
    subgraph "Generic Utilities"
        direction TB
        FetchHTTP["Fetch / HTTPRequest"]:::generic
        Mutex["Mutex / Locked FS"]:::generic
        SetImmediate["setImmediate Polyfill"]:::generic
        PreloadFile["Preload File"]:::generic
        KeyValueFS["Key-Value Filesystem Base"]:::generic
    end

    %% Pluggable Backend Layer
    subgraph "Pluggable Backend Layer"
        direction TB
        InMemory["InMemory Backend"]:::backend
        IndexedDB["IndexedDB Backend"]:::backend
        S3Stub["S3 (Stub) Backend"]:::backend
    end

    %% Storage / External Service Layer
    subgraph "Storage / External"
        direction TB
        LocalStorage["localStorage"]:::storage
        IndexedDBStore["IndexedDB"]:::storage
        HTML5FS["HTML5 FileSystem API"]:::storage
        HTTPServer["HTTP Server"]:::storage
        DropboxAPI["Dropbox API"]:::storage
        EMFS["Emscripten MEMFS/VFS"]:::storage
        ZipEngine["Zip Engine (DEFLATE)"]:::storage
    end

    %% Bundler & Build Pipeline
    subgraph "Bundler & Build Pipeline"
        direction TB
        Rollup["Rollup Config"]:::bundler
        Webpack["Webpack Config"]:::bundler
        Typedoc["Typedoc Config"]:::bundler
        MakeDist["make_dist.ts"]:::bundler
        GetDBCreds["get_db_credentials.ts"]:::bundler
        HTTPIndex["make_http_index.ts"]:::bundler
        FixtureLoader["make_fixture_loader.ts"]:::bundler
        Karma["Karma Config"]:::bundler
    end

    %% Interactions
    BrowserFS_config -->|configures| BackendRegistry
    BrowserFS_install -->|installs shim| GlobalUtil
    FileSystem --> FileRep
    FileSystem --> FileFlag
    FileSystem --> NodeStats
    FileSystem --> APIError
    FileSystem --> GlobalUtil
    BackendRegistry --> InMemory
    BackendRegistry --> IndexedDB
    BackendRegistry --> S3Stub
    InMemory --> LocalStorage
    IndexedDB --> IndexedDBStore
    S3Stub --> DropboxAPI
    FetchHTTP --> HTTPServer
    KeyValueFS --> LocalStorage
    Mutex --> InMemory
    PreloadFile --> InMemory
    BrowserFS_config --> FetchHTTP
    BrowserFS_config --> Mutex
    BrowserFS_config --> SetImmediate
    BrowserFS_config --> PreloadFile
    BrowserFS_config --> KeyValueFS

    Rollup --> PublicAPI
    Webpack --> PublicAPI
    Typedoc --> PublicAPI
    MakeDist --> PublicAPI
    GetDBCreds --> PublicAPI
    HTTPIndex --> PublicAPI
    FixtureLoader --> PublicAPI
    Karma --> PublicAPI

    %% Click Events
    click PublicAPI "https://github.com/swiftlatex/browserfs/blob/master/src/index.ts"
    click BackendRegistry "https://github.com/swiftlatex/browserfs/blob/master/src/core/backends.ts"
    click FileSystem "https://github.com/swiftlatex/browserfs/blob/master/src/core/file_system.ts"
    click FileRep "https://github.com/swiftlatex/browserfs/blob/master/src/core/file.ts"
    click FileFlag "https://github.com/swiftlatex/browserfs/blob/master/src/core/file_flag.ts"
    click NodeStats "https://github.com/swiftlatex/browserfs/blob/master/src/core/node_fs_stats.ts"
    click APIError "https://github.com/swiftlatex/browserfs/blob/master/src/core/api_error.ts"
    click GlobalUtil "https://github.com/swiftlatex/browserfs/blob/master/src/core/global.ts"
    click GlobalUtil "https://github.com/swiftlatex/browserfs/blob/master/src/core/util.ts"
    click InMemory "https://github.com/swiftlatex/browserfs/blob/master/src/backend/InMemory.ts"
    click IndexedDB "https://github.com/swiftlatex/browserfs/blob/master/src/backend/IndexedDB.ts"
    click S3Stub "https://github.com/swiftlatex/browserfs/blob/master/src/backend/S3.ts"
    click FetchHTTP "https://github.com/swiftlatex/browserfs/blob/master/src/generic/fetch.ts"
    click FetchHTTP "https://github.com/swiftlatex/browserfs/blob/master/src/generic/xhr.ts"
    click Mutex "https://github.com/swiftlatex/browserfs/blob/master/src/generic/mutex.ts"
    click Mutex "https://github.com/swiftlatex/browserfs/blob/master/src/generic/locked_fs.ts"
    click SetImmediate "https://github.com/swiftlatex/browserfs/blob/master/src/generic/setImmediate.ts"
    click PreloadFile "https://github.com/swiftlatex/browserfs/blob/master/src/generic/preload_file.ts"
    click KeyValueFS "https://github.com/swiftlatex/browserfs/blob/master/src/generic/key_value_filesystem.ts"
    click Rollup "https://github.com/swiftlatex/browserfs/blob/master/src/rollup.config.js"
    click Webpack "https://github.com/swiftlatex/browserfs/blob/master/src/webpack.config.js"
    click Typedoc "https://github.com/swiftlatex/browserfs/blob/master/src/typedoc.ts"
    click MakeDist "https://github.com/swiftlatex/browserfs/blob/master/scripts/make_dist.ts"
    click GetDBCreds "https://github.com/swiftlatex/browserfs/blob/master/scripts/get_db_credentials.ts"
    click HTTPIndex "https://github.com/swiftlatex/browserfs/blob/master/scripts/make_http_index.ts"
    click FixtureLoader "https://github.com/swiftlatex/browserfs/blob/master/scripts/make_fixture_loader.ts"
    click Karma "https://github.com/swiftlatex/browserfs/blob/master/karma.config.js"

    %% Styles
    classDef public fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef generic fill:#AFEEEE,stroke:#333,stroke-width:1px
    classDef backend fill:#98FB98,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef bundler fill:#FFFACD,stroke:#333,stroke-width:1px
```
