# pqina/filepond architecture

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

- Interactive diagram: https://gitdiagram.com/pqina/filepond
- Repository: https://github.com/pqina/filepond

## Overview

##### Main Components
a. Browser Host
- The environment in which FilePond runs; includes the DOM, network layer, clipboard, drag & drop API, and File API.
b. FilePond Core Library (src/js + src/css)
- Entry points: `createApp.js`, `index.js`, `banner.js`
- CSS modules in `src/css` that style drop zones, file items, progress indicators, etc.
- Locale files (`locale/*.js`) for internationalization.
- Type definitions (`types/index.d.ts`) for TS users.
c. Internal Subsystems
1. Frame Engine (`src/js/app/frame`)
- Implements a minimal reactive view‐store framework: `createStore`, `createView`, `mixins`, etc.
2. State Management (`src/js/app/actions.js`, `src/js/app/utils/createInitialState.js`)
- Actions, enumerations, queries, and a unidirectional data‐flow pattern.
3. View Components (`src/js/app/view/*.js`)
- Individual UI components (list, item, drop label, progress, etc.) that render based on the store.
4. Utilities (`src/js/app/utils` & `src/js/utils`)
- Core helpers: file handling, drag & drop, network requests, image resizing, ID generation, etc.
5. API Layer (`src/js/app/utils/createServerAPI.js`, `app/utils/createFetchFunction.js`)
- Abstracts AJAX/chunked uploads, base64 encoding, server calls, and rollback logic.
d. Plugin & Adapter Interfaces
- `createAppPlugin.js`, `createAppAPI.js` define hook points for extending functionality (e.g., image filters, validation).
e. Build & Distribution
- Rollup configs (`rollup.config.js`, `rollup.scripts.js`), Babel (`.babelrc`), Prettier, Jest tests (`src/js/__tests__`), output in `dist/`.

##### Relationships & Data Flows
- User drops/selects files in the DOM → View Component captures event → dispatches Action → Store updates state → View re‐renders file list.
- On upload invocation: Action triggers API Layer → makes HTTP requests → response updates Store → View updates progress/status.
- Utilities are stateless functions called by Frame Engine, Actions, Views, and API Layer whenever file data, DOM operations, or network calls are required.
- Plugins hook into lifecycle events exposed by the Frame Engine (e.g., beforeAddFile, afterProcessFile) to alter behavior or inject UI.

##### Architectural Patterns & Design Principles
- Unidirectional Data Flow (inspired by Flux/Redux): Actions → Store → Views.
- Componentized UI: each UI piece is a self‐contained “view” that subscribes to the store.
- Modular utilities: pure functions for isolation and testability.
- Plugin architecture: hooks and extension points allow external modules to augment core behavior without modifying core code.
- Build pipeline: source ES modules → Babel transpilation → Rollup bundling → UMD/ESM/CSS output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Title
    subgraph "FilePond Architecture"
    end

    %% Browser Host
    Browser["Browser Host<br/>(DOM, Network, DnD, File API)"]:::runtime

    %% Core Library
    subgraph "FilePond Core Library" 
        FrameEngine["Frame Engine"]:::runtime
        StateMgmt["Store & Actions"]:::runtime
        ViewComps["View Components"]:::runtime
        APILayer["API Layer"]:::api
        Utils["Utilities"]:::utils
    end

    %% Plugin Interface
    Plugin["Plugin Interface"]:::plugin

    %% Locale Module
    Locale["Locale Module"]:::locale

    %% Build & Distribution
    subgraph "Build & Distribution" 
        Rollup["Rollup Configs"]:::build
        Babel["Babel (.babelrc)"]:::build
        Dist["dist artifacts"]:::build
    end

    %% Test Suite
    Test["Jest Tests"]:::test

    %% Data Flows
    User["User<br/>(drag/drop, select)"]:::external
    User -->|"addFile event"| ViewComps
    ViewComps -->|"dispatch action"| StateMgmt
    StateMgmt -->|"state update"| ViewComps
    StateMgmt -->|"upload()/revert()"| APILayer
    APILayer -->|"response"| StateMgmt

    FrameEngine --> StateMgmt
    FrameEngine --> ViewComps
    StateMgmt --> ViewComps
    Utils --> FrameEngine
    Utils --> StateMgmt
    Utils --> ViewComps
    Utils --> APILayer
    Plugin --> FrameEngine
    Locale -->|"setOptions()"| FrameEngine

    Rollup --> Dist
    Babel --> Dist
    Test --> Utils
    Test --> StateMgmt
    Test --> APILayer

    %% Core entry point mapping
    FrameEngine --> CreateApp["createApp.js"]:::runtime
    click CreateApp "https://github.com/pqina/filepond/blob/master/src/js/createApp.js"
    FrameEngine --> IndexJS["index.js"]:::runtime
    click IndexJS "https://github.com/pqina/filepond/blob/master/src/js/index.js"
    FrameEngine --> Banner["banner.js"]:::runtime
    click Banner "https://github.com/pqina/filepond/blob/master/banner.js"

    %% Core Styles and types and locale
    subgraph "Styles & Types & Locale"
        CSS["CSS modules"]:::build
        Types["Type Definitions"]:::build
        LocFiles["Locale Files"]:::locale
    end
    click CSS "https://github.com/pqina/filepond/tree/master/src/css/"
    click Types "https://github.com/pqina/filepond/blob/master/types/index.d.ts"
    click LocFiles "https://github.com/pqina/filepond/tree/master/locale/"

    %% Frame Engine mapping
    subgraph "Frame Engine Files"
        FEIndex["index.js"]:::runtime
        CreateStore["createStore.js"]:::runtime
        CreateView["createView.js"]:::runtime
        CreatePainter["createPainter.js"]:::runtime
        CreateRoute["createRoute.js"]:::runtime
        Mixins["mixins/"]:::runtime
        FEUtils["utils/"]:::runtime
    end
    click FEIndex "https://github.com/pqina/filepond/blob/master/src/js/app/frame/index.js"
    click CreateStore "https://github.com/pqina/filepond/blob/master/src/js/app/frame/createStore.js"
    click CreateView "https://github.com/pqina/filepond/blob/master/src/js/app/frame/createView.js"
    click CreatePainter "https://github.com/pqina/filepond/blob/master/src/js/app/frame/createPainter.js"
    click CreateRoute "https://github.com/pqina/filepond/blob/master/src/js/app/frame/createRoute.js"
    click Mixins "https://github.com/pqina/filepond/tree/master/src/js/app/frame/mixins/"
    click FEUtils "https://github.com/pqina/filepond/tree/master/src/js/app/frame/utils/"

    FrameEngine --> FEIndex

    %% State Management mapping
    StateMgmt --> Actions["actions.js"]:::runtime
    StateMgmt --> Queries["queries.js"]:::runtime
    StateMgmt --> InitState["createInitialState.js"]:::runtime
    StateMgmt --> Enums["enum/"]:::runtime
    click Actions "https://github.com/pqina/filepond/blob/master/src/js/app/actions.js"
    click Queries "https://github.com/pqina/filepond/blob/master/src/js/app/queries.js"
    click InitState "https://github.com/pqina/filepond/blob/master/src/js/app/utils/createInitialState.js"
    click Enums "https://github.com/pqina/filepond/tree/master/src/js/app/enum/"

    %% View Components mapping
    ViewComps --> ViewFiles["view/*.js"]:::runtime
    click ViewFiles "https://github.com/pqina/filepond/tree/master/src/js/app/view/"

    %% Utilities mapping
    Utils --> AppUtils["app/utils/"]:::utils
    Utils --> GenUtils["utils/"]:::utils
    click AppUtils "https://github.com/pqina/filepond/tree/master/src/js/app/utils/"
    click GenUtils "https://github.com/pqina/filepond/tree/master/src/js/utils/"

    %% API Layer mapping
    APILayer --> ServerAPI["createServerAPI.js"]:::api
    APILayer --> FetchFn["createFetchFunction.js"]:::api
    APILayer --> NetHelpers["processFileChunked.js"]:::api
    APILayer --> ToAPI["toServerAPI.js"]:::api
    click ServerAPI "https://github.com/pqina/filepond/blob/master/src/js/app/utils/createServerAPI.js"
    click FetchFn "https://github.com/pqina/filepond/blob/master/src/js/app/utils/createFetchFunction.js"
    click NetHelpers "https://github.com/pqina/filepond/blob/master/src/js/app/utils/processFileChunked.js"
    click ToAPI "https://github.com/pqina/filepond/blob/master/src/js/app/utils/toServerAPI.js"

    %% Plugin Interfaces mapping
    Plugin --> AppPlugin["createAppPlugin.js"]:::plugin
    Plugin --> AppAPI["createAppAPI.js"]:::plugin
    click AppPlugin "https://github.com/pqina/filepond/blob/master/src/js/createAppPlugin.js"
    click AppAPI "https://github.com/pqina/filepond/blob/master/src/js/createAppAPI.js"

    %% Build & Distribution mapping
    Rollup --> RollupConfig["rollup.config.js"]:::build
    Rollup --> RollupScripts["rollup.scripts.js"]:::build
    click RollupConfig "https://github.com/pqina/filepond/blob/master/rollup.config.js"
    click RollupScripts "https://github.com/pqina/filepond/blob/master/rollup.scripts.js"

    Dist --> DistJS1["dist/filepond.js"]:::build
    Dist --> DistJS2["dist/filepond.esm.js"]:::build
    Dist --> DistCSS["dist/filepond.css"]:::build

    %% Test mapping
    Test --> TestsDir["__tests__"]:::test
    Test --> JestConfig["jest.config.js"]:::test
    click TestsDir "https://github.com/pqina/filepond/tree/master/src/js/__tests__"
    click JestConfig "https://github.com/pqina/filepond/blob/master/jest.config.js"

    %% Styles
    classDef runtime fill:#E0F0FF,stroke:#024;
    classDef utils fill:#E0FFE0,stroke:#080;
    classDef api fill:#FFF4E0,stroke:#F60;
    classDef build fill:#F0F0F0,stroke:#888;
    classDef test fill:#F8E0FF,stroke:#808;
    classDef plugin fill:#FFE0F0,stroke:#C08;
    classDef locale fill:#FFFFE0,stroke:#CC0;
    classDef external fill:#FFF,stroke:#666,stroke-dasharray: 2 2;
```
