# 2ai-cx/budibase architecture

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

- Interactive diagram: https://gitdiagram.com/2ai-cx/budibase
- Repository: https://github.com/2ai-cx/budibase

## Overview

##### Major domains and components
- Frontend – The user‐facing applications:
– The Builder (packages/builder): A client-side Svelte-based application through which developers design and configure apps.
– The Client (packages/client and packages/frontend-core): Runs in the browser to render the final application based on a JSON definition. It holds UI components, theming, and layout functionality.
- Backend – The server side:
– The Server (packages/server): A Koa-based web application that provides the API endpoints for interactions, manages database and file system operations, and serves the builder/client resources.
– The Worker (packages/worker): Handles background tasks such as automation processing, integration calls, and other asynchronous operations (e.g., running automations, webhooks, or processing queued jobs).
- Shared, SDK, and Types:
– Shared-core, SDK, and Types packages (e.g., packages/shared-core, packages/sdk, packages/types, packages/string-templates) that provide common business logic, API interfaces, type definitions, helper utilities, and integration points across the system.
- CLI and Integration Tools:
– The CLI (packages/cli) provides utility scripts and command-line tools.
- DevOps & Hosting:
– The “hosting” directory and Docker/Kubernetes charts contain deployment configurations, Dockerfiles, Helm charts, and infrastructure scripts.

##### Out component interactions and data flow
- The Builder (frontend) communicates with the Server via RESTful API endpoints (and possibly websockets for real-time updates) to store app definitions, manage automated workflows, and deploy changes.
- The Client (runtime application) fetches its JSON definition (that may include API routes, UI configuration, and styling) from the Server and renders the live, responsive app.
- The Server not only serves the web apps but also handles data persistence (integrating with databases like CouchDB and others as suggested by files in packages/server/src/db) and communications with external data sources.
- The Worker processes background automation tasks (as seen from automation steps in packages/server/src/automations, and tests around these modules) and integrates with third-party services.
- Shared libraries, SDKs, and type packages ensure consistency of business logic (e.g., event handling, row actions, licensing) across the builder, client, server, and worker.
- External integrations – For data sources and connectivity (e.g., integrations with MongoDB, Postgres, DynamoDB, REST APIs) – are defined within server integrations and also in the types/SDK modules.

##### Architectural patterns and design principles
- Monorepo organization using Lerna aids in separation of concerns across modular packages while promoting reuse of common modules.
- Clear separation between presentation (builder and client) and logic/data layers (server, worker, integrations).
- Use of middleware patterns in the server (launched by Koa) and in routing among API controllers.
- Asynchronous processing of tasks via the worker, with event emitters and queues connecting with the main server application.
- Integration of a rich type system and shared API contracts (via packages/types and packages/sdk) which ensures consistency between client–server communications.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend"
        Builder["Builder - Svelte SPA"]:::frontend
        subgraph "Client UI"
            Client["Client (packages/client)"]:::frontend
            FrontendCore["Frontend Core (packages/frontend-core)"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend"
        Server["Server - Koa API & Data"]:::backend
        Worker["Worker - Background Tasks"]:::backend
    end

    %% Shared Libraries & SDKs
    subgraph "Shared & SDK"
        SharedCore["Shared Core"]:::shared
        SDK["SDK"]:::shared
        Types["Types"]:::shared
        StringTemplates["String Templates"]:::shared
    end

    %% CLI & Integration Tools
    CLI["CLI Tools"]:::cli

    %% DevOps & Hosting
    subgraph "DevOps & Hosting"
        Hosting["Hosting Scripts"]:::devops
        Charts["Deployment Charts"]:::devops
    end

    %% External Integrations
    External["External Integrations"]:::external

    %% Interactions
    Builder -->|"API-calls"| Server
    Client -->|"FetchJSON"| Server
    FrontendCore -->|"PartOfClient"| Client
    Server -->|"DispatchTasks"| Worker
    Worker -->|"ReturnResults"| Server
    Server -->|"Integrations"| External
    CLI -->|"Manage"| Server
    Hosting -->|"Deploys"| Server
    Charts -->|"Deploys"| Server

    %% Shared libraries connections (dashed lines indicate dependency)
    SharedCore --- Builder
    SharedCore --- Server
    SDK --- Builder
    SDK --- Server
    Types --- Client
    Types --- Worker
    StringTemplates --- Server

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef backend fill:#ffcccc,stroke:#000,stroke-width:2px;
    classDef shared fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef cli fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef devops fill:#ffd700,stroke:#000,stroke-width:2px;
    classDef external fill:#e6e6e6,stroke:#333,stroke-width:2px;

    %% Click Events
    click Builder "https://github.com/2ai-cx/budibase/tree/master/packages/builder"
    click Client "https://github.com/2ai-cx/budibase/tree/master/packages/client"
    click FrontendCore "https://github.com/2ai-cx/budibase/tree/master/packages/frontend-core"
    click Server "https://github.com/2ai-cx/budibase/tree/master/packages/server"
    click Worker "https://github.com/2ai-cx/budibase/tree/master/packages/worker"
    click SharedCore "https://github.com/2ai-cx/budibase/tree/master/packages/shared-core"
    click SDK "https://github.com/2ai-cx/budibase/tree/master/packages/sdk"
    click Types "https://github.com/2ai-cx/budibase/tree/master/packages/types"
    click StringTemplates "https://github.com/2ai-cx/budibase/tree/master/packages/string-templates"
    click CLI "https://github.com/2ai-cx/budibase/tree/master/packages/cli"
    click Hosting "https://github.com/2ai-cx/budibase/tree/master/hosting"
    click Charts "https://github.com/2ai-cx/budibase/tree/master/charts"
```
