# felixmosh/bull-board architecture

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

- Interactive diagram: https://gitdiagram.com/felixmosh/bull-board
- Repository: https://github.com/felixmosh/bull-board

## Overview

##### Project Overview & Primary Purpose
- The project is an open-source dashboard tool designed to provide a visual interface for monitoring and managing queues (powered by Bull and BullMQ).
- It is a modular, monorepo-based project managed by Lerna, which comprises several packages. These packages include the core API logic, a React-based UI, and a variety of adapters (one for each supported server framework such as Express, Fastify, Koa, Hapi, NestJS, Hono, H3, and Elysia).
- External dependencies include Bull, BullMQ, and Redis; the dashboard relies on these libraries to monitor job statuses without taking over job processing.

##### Analyzing the File Structure
- Top-Level Organization: The repository root contains configuration files (.dockerignore, .gitignore, Dockerfile, lerna.json, etc.) and directories dedicated to examples, packages, and GitHub workflows.
- Packages Directory: Contains subdirectories for each major component:
- packages/api: Contains core API logic for interacting with queues (handlers, providers, routes, etc.) including queue adapters.
- packages/ui: Contains the entire React-based UI, with components (JobCard, QueueCard, forms, modals, etc.), static assets (images, locales), and utility functions.
- Framework-specific adapter packages (e.g., packages/express, packages/fastify, packages/koa, packages/hapi, packages/nestjs, packages/hono, packages/h3, packages/elysia): Each of these provides a mechanism to integrate the dashboard into various Node.js server frameworks.
- Examples Directory: Contains sample projects demonstrating how to integrate the dashboard with different frameworks. This further highlights how the adapters and API interact with various server contexts.

##### Main Components & Their Relationships
A. Core API Service (packages/api):
- Acts as the central engine for handling queue-related requests.
- Implements logic to interact with both Bull and BullMQ.
- Exposes a set of handlers, routes, job operations (add, clean, retry, pause/resume).
B. UI Layer (packages/ui):
- Built using React; consists of multiple UI components for data visualization and user interaction.
- Fetches data (via API calls) to display real-time queue/job details.
C. Server Adapters (packages/express, packages/fastify, etc.):
- Each adapter is tailored to a specific web framework.
- They bridge the gap between the framework’s routing/middleware mechanism and the underlying Bull Dashboard API.
- Typically, these adapters configure a base path for hosting the dashboard, handle HTTP requests, and forward them to the core API.
D. External Dependencies:
- Bull & BullMQ: Libraries that manage the queues.
- Redis: The message and job store that the queues rely on.
E. Configuration & Utility Components:
- Various configuration files (Dockerfiles, ESLint config, etc.) that facilitate development and containerization.
- Utility modules within the various packages to support data formatting and logging.

##### Relationships & Data Flow
- Start at the UI component: When a user navigates to the dashboard route (for example, /admin/queues), the UI (client-side React application) makes RESTful or API calls to the backend.
- The backend is provided by the core API – encapsulated in packages/api – which processes the requests and interfaces with the queue adapters.
- The server adapter (whichever is in use such as @bull-board/express) is responsible for handling HTTP routing and serves as the glue between the frontend and the internal API.
- Finally, interactions from the API connect to the actual Bull or BullMQ instances which interface with Redis. Thus, any actions (retry, pause, etc.) flow from the UI through the API to the external services.

##### Architectural Patterns & Design Principles
- Modular Monorepo: The project is segmented into multiple packages, each handling a discrete responsibility, enhancing maintainability and scalability.
- Adapter Pattern: Use of server-specific adapters allows the core dashboard functionality to remain framework-agnostic.
- Separation of Concerns: The explicit separation between the API layer, UI layer, and server integration layers (adapters) promotes clear responsibility boundaries.
- Extensibility: Multiple examples and configuration options indicate an architecture designed to be extended or customized by users for various server setups.

## Diagram (Mermaid)

```mermaid
graph TD
    UI["React UI (packages/ui)"]:::ui

    subgraph "Server Adapters"
        EA["Express Adapter (packages/express)"]:::adapter
        FA["Fastify Adapter (packages/fastify)"]:::adapter
        KA["Koa Adapter (packages/koa)"]:::adapter
        HA["Hapi Adapter (packages/hapi)"]:::adapter
        NA["NestJS Adapter (packages/nestjs)"]:::adapter
        Hono["Hono Adapter (packages/hono)"]:::adapter
        H3A["H3 Adapter (packages/h3)"]:::adapter
        ElyA["Elysia Adapter (packages/elysia)"]:::adapter
    end

    API["Bull Dashboard Core API (packages/api)"]:::core

    subgraph "External Dependencies"
        Bull["Bull Library"]:::external
        BullMQ["BullMQ Library"]:::external
        Redis["Redis Server"]:::external
    end

    UI -->|"calls"| EA
    UI -->|"calls"| FA
    UI -->|"calls"| KA
    UI -->|"calls"| HA
    UI -->|"calls"| NA
    UI -->|"calls"| Hono
    UI -->|"calls"| H3A
    UI -->|"calls"| ElyA

    EA -->|"forwards_request"| API
    FA -->|"forwards_request"| API
    KA -->|"forwards_request"| API
    HA -->|"forwards_request"| API
    NA -->|"forwards_request"| API
    Hono -->|"forwards_request"| API
    H3A -->|"forwards_request"| API
    ElyA -->|"forwards_request"| API

    API -->|"interacts_with"| Bull
    API -->|"interacts_with"| BullMQ
    API -->|"interacts_with"| Redis
    Bull ---|"feeds_data"| API
    BullMQ ---|"feeds_data"| API
    Redis ---|"feeds_data"| API

    click UI "https://github.com/felixmosh/bull-board/tree/master/packages/ui"
    click API "https://github.com/felixmosh/bull-board/tree/master/packages/api"
    click EA "https://github.com/felixmosh/bull-board/tree/master/packages/express"
    click FA "https://github.com/felixmosh/bull-board/tree/master/packages/fastify"
    click KA "https://github.com/felixmosh/bull-board/tree/master/packages/koa"
    click HA "https://github.com/felixmosh/bull-board/tree/master/packages/hapi"
    click NA "https://github.com/felixmosh/bull-board/tree/master/packages/nestjs"
    click Hono "https://github.com/felixmosh/bull-board/tree/master/packages/hono"
    click H3A "https://github.com/felixmosh/bull-board/tree/master/packages/h3"
    click ElyA "https://github.com/felixmosh/bull-board/tree/master/packages/elysia"

classDef core fill:#bbdefb,stroke:#0d47a1,stroke-width:2px,color:#0d47a1;
classDef ui fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#2e7d32;
classDef adapter fill:#ffe082,stroke:#ff6f00,stroke-width:2px,color:#ff6f00;
classDef external fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#c62828;
```
