# deriv-com/quill-ui architecture

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

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

## Overview

##### Project Type & Purpose
- This is an open-source UI component library intended to standardize and simplify the creation of user interfaces for Deriv applications.
- Its primary goal is to promote design consistency (via design tokens and integration with the Design System) and facilitate easy usage/development through Storybook demos and thorough testing.

##### Main Components
a. Component Library (lib/components)
– Within each component (for example, “ActionSheet”, “Atom”, “Badge”, etc.), indicate that they follow modular design with support files like SCSS styling, tests, and story files.

b. Core Hooks (lib/hooks)
– Represent hooks (e.g., useTheme, useDropdown, usePaginationRange) as a separate node.
– Highlight that these hooks provide reusable state and UI behavior logic across components.

c. Providers (lib/providers)
– Indicate connections from the providers to both hooks and the component library (they connect at higher levels to manage global state).

d. Utility Functions & Types (lib/utils and lib/types)
– Show a node for utility modules that support common operations (e.g., common-utils, notification-utils, typography-utils).
– Include the types definition files that help maintain type safety across the project.

e. Design Tokens & Styling (data and lib/styles)
– Show design tokens (stored, for example, in data/tokens.json) and the styles folder.
– Emphasize that the style and theming are entirely design token driven for consistency with the Deriv Design System.

f. Development & Demonstration Infrastructure
– Storybook (in the .storybook folder) is a critical component for demonstrating and testing each UI element.
– Include testing frameworks and configuration files (e.g., Jest tests across components; configuration via .eslintrc.cjs, commitlint, and husky for precommit checks).
– Also denote build configuration (vite.config.ts and various tsconfig files) and release pipelines (release.config.cjs, release.utils.cjs, and GitHub workflows).

##### Relationships and Interactions
- The UI components make use of hooks and providers.
- Providers supply themes and global states to the components.
- Utilities and type definitions support both components and hooks.
- The storybook node can be connected to the components as a demonstration and documentation layer.
- The build/configuration tools support the overall project by automating tests, linting, and releases (npm publishing).

##### Architectural Patterns and Design Principles
- Modular design: each component is self-contained with tests, styles, and stories.
- Document design system integration: the styling is token-driven, meaning that changing tokens alters the whole UI, ensuring consistency.
- Best practices such as context providers and custom hooks for state management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Quill UI Component Library"
        comp["Components - Button, Input, Modal, Notification\n(Modular: includes SCSS, tests, stories)"]:::components
        hooks["Hooks - useTheme, useDropdown, usePaginationRange"]:::hooks
        providers["Providers - ThemeProvider, NotificationProvider, BreakpointProvider, SnackbarProvider"]:::providers
        util["Utilities - common-utils, notification-utils, typography-utils"]:::utils
        types["Types - Type definitions"]:::utils
        tokens["Design Tokens"]:::design
        styles["Styles - SCSS files"]:::design
    end

    subgraph "Development & Demonstration Infrastructure"
        storybook["Storybook Demo & Docs"]:::dev
        config["Build_Test_Configs_&_Release_Pipelines"]:::dev
    end

    providers -->|"provides_context"| comp
    hooks -->|"enhances_behavior"| comp
    util -->|"supports"| comp
    types -->|"supports"| comp
    util -->|"supports"| hooks
    tokens -->|"drives_theming"| comp
    styles -->|"applies_styling"| comp
    storybook -->|"demonstrates"| comp
    config -->|"automates"| comp

    click comp "https://github.com/deriv-com/quill-ui/tree/master/lib/components"
    click hooks "https://github.com/deriv-com/quill-ui/tree/master/lib/hooks"
    click providers "https://github.com/deriv-com/quill-ui/tree/master/lib/providers"
    click util "https://github.com/deriv-com/quill-ui/tree/master/lib/utils"
    click types "https://github.com/deriv-com/quill-ui/blob/master/lib/types.ts"
    click tokens "https://github.com/deriv-com/quill-ui/blob/master/data/tokens.json"
    click styles "https://github.com/deriv-com/quill-ui/tree/master/lib/styles"
    click storybook "https://github.com/deriv-com/quill-ui/blob/master/.storybook"
    click config "https://github.com/deriv-com/quill-ui/blob/master/vite.config.ts"

    classDef components fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef hooks fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef providers fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef utils fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef design fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef dev fill:#87CEEB,stroke:#000,stroke-width:1px;
```
