# frappe/frappe-ui architecture

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

- Interactive diagram: https://gitdiagram.com/frappe/frappe-ui
- Repository: https://github.com/frappe/frappe-ui

## Overview

##### Project Type and Purpose
- Frappe UI is an open-source Vue 3 component library + utility toolkit built on TailwindCSS.
- It’s designed to be consumed by other Vue applications (e.g., Frappe Cloud, Gameplan) and provides:
– A plugin layer to auto-register components
– A catalog of reusable UI components
– Utility modules (data-fetching composables, directives, helper functions)
– A TailwindCSS preset for theming
– Rich-text editor extensions (TipTap)

##### High-Level File Structure Analysis
- Top-level:
– src/ – source code (components, composables, directives, utilities, data-fetching, tailwind config)
– vite/ – build and code-generation scripts for types and dev server proxy
– docs/ – Markdown + Storybook stories for documentation site
– .github/workflows/ – CI for tests, builds, publishing to NPM
– package.json & tsconfig/vite.config – build, test, lint configuration
- Key layers inside src/:
a. components/ – individual Vue component folders, each with .vue, index.ts, types
b. data-fetching/ – composables for REST calls, real-time, local store
c. directives/ – Vue directives (e.g., onOutsideClick)
d. utils/ – helper functions (date handling, socket, upload, markdown, tailwind config)

##### README Insights
- Under-the-Hood tech stack: Vue 3 plugin, TailwindCSS, Headless UI, TipTap, dayjs
- Usage pattern: consumer imports FrappeUI plugin → app.use(FrappeUI) → Tailwind preset in consumer tailwind.config.js
- Continuous enrichment via vite scripts (type generation, proxy) and docs driven by Histoire/Storybook

##### Components
A. Core Plugin Layer
– FrappeUI (Vue plugin entrypoint) registers all components, directives, provides theme and utilities.
B. Component Modules
– UI Components (Button, Dialog, DatePicker, etc.)
C. Utility Layer
– Data-fetching composables (useCall, useDoc, useList, useNewDoc)
– Directives (onOutsideClick, visibility)
– Shared utils (debounce, markdown, socketio, dayjs wrappers)
D. Tailwind Preset Layer
E. Build & Distribution
– Vite build scripts (bundle to ESM/CJS, type generation)
– Vitest for unit tests
– GitHub Actions for CI/CD and NPM publish
F. Documentation Site
– docs/ driven by Histoire/Storybook, sources from components/**/*.story.*

##### Relationships and Data Flows
- “FrappeUI Plugin” → “Component Modules” for auto-registration
- “Component Modules” → “Utility Layer” for composables/directives
- “Components” → “Tailwind Preset” for styling
- “Build & Distribution” processes “src/” and “vite/” → publishes to NPM
- “Documentation Site” reads from “src/” + “docs/” via Histoire pipeline

##### Architectural Patterns & Design Principles
- Modular design: each component lives in its own folder with isolated types
- Plugin pattern: single entrypoint auto-wires all modules
- Composable API: data-fetching layers expose reactive hooks
- Utility-first CSS: Tailwind preset integrated with component classes
- Code generation: Vite scripts generate types and proxies for Frappe REST APIs

##### Technologies and Frameworks to Annotate
- Vue 3 Plugin System, Composition API
- TailwindCSS + Headless UI
- TipTap (ProseMirror) for rich-text
- Vite (build), Vitest (testing), Histoire/Storybook (docs)
- GitHub Actions (CI/CD), NPM registry

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Layer
    Consumer["Consumer Vue App"]:::external

    %% Plugin Layer
    subgraph "Plugin Layer"
        direction TB
        FUI["FrappeUI Plugin\n(src/index.ts)"]:::plugin
        Provider["Component Registration Provider\n(FrappeUIProvider.vue)"]:::plugin
    end

    %% Component Layer
    subgraph "Component Modules"
        direction TB
        Alert["Alert Component"]:::components
        Button["Button Component"]:::components
        DatePicker["DatePicker Component"]:::components
        Dialog["Dialog Component"]:::components
        TextEditor["TextEditor Component"]:::components
        subgraph "TextEditor Extensions"
            direction TB
            ColorExt["Color Extension"]:::components
            EmojiExt["Emoji Extension"]:::components
            SlashExt["Slash Commands Extension"]:::components
            ImageExt["Image Extension"]:::components
        end
    end

    %% Utility Layer
    subgraph "Utility Composables & Directives"
        direction TB
        subgraph "Data-Fetching Composables"
            useCall["useCall"]:::utils
            useDoc["useDoc"]:::utils
            useList["useList"]:::utils
            useNewDoc["useNewDoc"]:::utils
            DocStore["Shared Store Utilities"]:::utils
        end
        subgraph "Directives"
            Outside["onOutsideClick"]:::utils
            Visibility["visibility"]:::utils
        end
        subgraph "Shared Utils"
            Debounce["debounce"]:::utils
            Markdown["markdown parser"]:::utils
            SocketIO["socket.io wrapper"]:::utils
            DayJS["dayjs wrapper"]:::utils
            FileUpload["file upload handler"]:::utils
            PluginUtils["Vue Plugin Utilities"]:::utils
        end
    end

    %% Styling Layer
    subgraph "TailwindCSS Preset Layer"
        direction TB
        Preset["Tailwind Preset"]:::styling
        TWPlugin["Tailwind Plugin"]:::styling
        ColorPalette["Color Palette Utilities"]:::styling
    end

    %% Build & Distribution
    subgraph "Build & Distribution"
        direction TB
        ViteBuild["Vite Build Scripts"]:::build
        ViteConfig["Vite Configuration"]:::build
        TSConfig["TypeScript Config"]:::build
        CI["GitHub Actions CI/CD"]:::build
        Vitest["Vitest Tests"]:::build
        NPM["Published NPM Package"]:::artifact
    end

    %% Documentation Site
    subgraph "Documentation Site"
        direction TB
        MDStories["Markdown Stories"]:::docs
        Histoire["Histoire Config"]:::docs
        StoryFiles["Component Story Files"]:::docs
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Vue3["Vue 3"]:::external
        TailwindCSS["TailwindCSS"]:::external
        HeadlessUI["Headless UI"]:::external
        TipTap["TipTap"]:::external
        DayJSLib["dayjs"]:::external
    end

    %% Relationships
    Consumer -->|"uses"| FUI
    FUI -->|registers| Provider
    Provider -->|auto-registers| Alert
    Provider -->|auto-registers| Button
    Provider -->|auto-registers| DatePicker
    Provider -->|auto-registers| Dialog
    Provider -->|auto-registers| TextEditor
    TextEditor -->|includes| ColorExt
    TextEditor -->|includes| EmojiExt
    TextEditor -->|includes| SlashExt
    TextEditor -->|includes| ImageExt

    Alert -->|"calls"| useCall
    Button -->|"calls"| useDoc
    DatePicker -->|"calls"| useList
    Dialog -->|"calls"| useNewDoc
    TextEditor -->|"uses"| Markdown
    TextEditor -->|"uses"| PluginUtils

    useCall -->|"stores"| DocStore
    useDoc -->|"stores"| DocStore
    useList -->|"stores"| DocStore
    useNewDoc -->|"stores"| DocStore

    Preset -->|provides| Alert
    Preset -->|provides| Button
    Preset -->|provides| DatePicker
    Preset -->|provides| Dialog
    Preset -->|provides| TextEditor

    ViteBuild -->|bundles| NPM
    ViteConfig -->|configures| ViteBuild
    TSConfig -->|supports| ViteBuild
    CI -->|runs| Vitest
    CI -->|publishes| NPM

    MDStories -->|sources| Alert
    MDStories -->|sources| Button
    MDStories -->|sources| DatePicker
    MDStories -->|sources| Dialog
    MDStories -->|sources| TextEditor
    Histoire -->|builds| StoryFiles

    Vue3 -->|framework| FUI
    TailwindCSS -->|framework| Preset
    HeadlessUI -->|components| Alert
    TipTap -->|editor| TextEditor
    DayJSLib -->|date utils| DayJS

    %% Click Events
    click FUI "https://github.com/frappe/frappe-ui/blob/main/src/index.ts"
    click PluginUtils "https://github.com/frappe/frappe-ui/blob/main/src/utils/plugin.js"
    click Provider "https://github.com/frappe/frappe-ui/blob/main/src/components/Provider/FrappeUIProvider.vue"
    click Alert "https://github.com/frappe/frappe-ui/blob/main/src/components/Alert/Alert.vue"
    click Button "https://github.com/frappe/frappe-ui/blob/main/src/components/Button/Button.vue"
    click DatePicker "https://github.com/frappe/frappe-ui/blob/main/src/components/DatePicker/DatePicker.vue"
    click Dialog "https://github.com/frappe/frappe-ui/blob/main/src/components/Dialog/Dialog.vue"
    click TextEditor "https://github.com/frappe/frappe-ui/blob/main/src/components/TextEditor/TextEditor.vue"
    click ColorExt "https://github.com/frappe/frappe-ui/blob/main/src/components/TextEditor/extensions/color/index.ts"
    click EmojiExt "https://github.com/frappe/frappe-ui/blob/main/src/components/TextEditor/extensions/emoji/emoji-extension.ts"
    click SlashExt "https://github.com/frappe/frappe-ui/blob/main/src/components/TextEditor/extensions/slash-commands/slash-commands-extension.ts"
    click ImageExt "https://github.com/frappe/frappe-ui/blob/main/src/components/TextEditor/extensions/image/index.ts"
    click useCall "https://github.com/frappe/frappe-ui/blob/main/src/data-fetching/useCall/useCall.ts"
    click useDoc "https://github.com/frappe/frappe-ui/blob/main/src/data-fetching/useDoc/useDoc.ts"
    click useList "https://github.com/frappe/frappe-ui/blob/main/src/data-fetching/useList/useList.ts"
    click useNewDoc "https://github.com/frappe/frappe-ui/blob/main/src/data-fetching/useNewDoc/useNewDoc.ts"
    click DocStore "https://github.com/frappe/frappe-ui/blob/main/src/data-fetching/docStore.ts"
    click Outside "https://github.com/frappe/frappe-ui/blob/main/src/directives/onOutsideClick.ts"
    click Visibility "https://github.com/frappe/frappe-ui/blob/main/src/directives/visibility.ts"
    click Debounce "https://github.com/frappe/frappe-ui/blob/main/src/utils/debounce.ts"
    click Markdown "https://github.com/frappe/frappe-ui/blob/main/src/utils/markdown.ts"
    click SocketIO "https://github.com/frappe/frappe-ui/blob/main/src/utils/socketio.js"
    click DayJS "https://github.com/frappe/frappe-ui/blob/main/src/utils/dayjs.ts"
    click FileUpload "https://github.com/frappe/frappe-ui/blob/main/src/utils/fileUploadHandler.ts"
    click Preset "https://github.com/frappe/frappe-ui/blob/main/src/tailwind/preset.js"
    click TWPlugin "https://github.com/frappe/frappe-ui/blob/main/src/tailwind/plugin.js"
    click ColorPalette "https://github.com/frappe/frappe-ui/blob/main/src/tailwind/colorPalette.js"
    click ViteBuild "https://github.com/frappe/frappe-ui/blob/main/vite/buildConfig.js"
    click ViteConfig "https://github.com/frappe/frappe-ui/blob/main/vite.config.ts"
    click TSConfig "https://github.com/frappe/frappe-ui/blob/main/tsconfig.json"
    click CI "https://github.com/frappe/frappe-ui/blob/main/.github/workflows/publish.yml"
    click Vitest "https://github.com/frappe/frappe-ui/blob/main/.github/workflows/vitest.yml"
    click MDStories "https://github.com/frappe/frappe-ui/tree/main/docs/components"
    click Histoire "https://github.com/frappe/frappe-ui/blob/main/histoire.config.ts"
    click StoryFiles "https://github.com/frappe/frappe-ui/tree/main/src/components"
    
    %% Styles
    classDef plugin fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef components fill:#d4edda,stroke:#333,stroke-width:1px
    classDef utils fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef styling fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef build fill:#e2d5f5,stroke:#333,stroke-width:1px
    classDef docs fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
    class artifact fill:#cfe2ff,stroke:#333,stroke-width:1px
```
