# Apache Superset Project Structure: A Complete Guide to the Monorepo Architecture

> Explore the Apache Superset project structure, a Bun-powered monorepo. Understand how apps and packages are organized with centralized tooling for clarity and efficiency.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: architecture
- Published: 2026-03-08

---

**Apache Superset is organized as a Bun-powered Turbo monorepo split into `apps/` (runnable products like the web UI and API) and `packages/` (shared libraries such as `@superset/ui` and `@superset/db`), orchestrated by centralized tooling in `tooling/` and root-level configuration files.**

The Apache Superset project structure follows a modern monorepo architecture designed for scalability and code reuse. Built with Bun and managed by Turborepo, the repository separates standalone applications from shared libraries to ensure consistent TypeScript typings and streamlined development workflows. Understanding this layout is essential for contributors looking to extend the platform or integrate new features.

## Monorepo Architecture Overview

Superset adopts a **Bun + Turbo monorepo** pattern that groups independent applications and reusable packages under a single repository. The top-level layout is deliberately partitioned into three distinct areas:

- **`apps/`** – Standalone runnable applications including the web UI, API server, desktop client, and mobile app.
- **`packages/`** – Shared libraries consumed by multiple apps, including UI components, database schemas, and authentication utilities.
- **`tooling/`** – Build-time configuration for TypeScript, linting, and CI/CD pipelines.

This structure ensures that changes to shared packages propagate consistently across all dependent applications, while the Turbo pipeline defined in `turbo.jsonc` orchestrates builds, tests, and linting across the entire tree.

## The `apps/` Directory: Runnable Applications

The `apps/` directory contains all deployable products in the Superset ecosystem. Each application maintains its own [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json) and entry points while importing shared logic from the `@superset/*` packages.

### Web Application (`apps/web`)

The primary Superset UI is a **Next.js 16** single-page application built with React and Tailwind v4. It serves as the main interface for data exploration and dashboard creation.

Key configuration resides in [`apps/web/next.config.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/next.config.ts), which handles image optimization, API rewrites, and the integration with the shared `@superset/ui` component library.

### API Server (`apps/api`)

The backend API is implemented as a **Next.js serverless** application that exposes tRPC endpoints. It handles authentication, database access via `@superset/db`, and business logic orchestration.

Configuration is defined in [`apps/api/next.config.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/next.config.ts), while the tRPC router initialization leverages shared definitions from `@superset/trpc`.

### Desktop and Mobile Clients

Superset extends beyond the browser with native applications:

- **`apps/desktop`** – An **Electron-based** desktop client that wraps the web UI for offline use. Configuration is managed in [`apps/desktop/package.json`](https://github.com/superset-sh/superset/blob/main/apps/desktop/package.json).
- **`apps/mobile`** – A **React Native** application built with Expo, providing a native mobile experience. Entry points are defined in [`apps/mobile/package.json`](https://github.com/superset-sh/superset/blob/main/apps/mobile/package.json).

### Supporting Applications

The monorepo includes several specialized applications:

- **`apps/admin`** – Internal tools for managing users and system settings, utilizing [`apps/admin/src/trpc/server.tsx`](https://github.com/superset-sh/superset/blob/main/apps/admin/src/trpc/server.tsx) for server-side tRPC integration.
- **`apps/docs`** – Static documentation site built with Next.js.
- **`apps/marketing`** – Landing pages and promotional content.
- **`apps/electric-proxy`** – A Cloudflare Workers proxy for authentication flows.
- **`apps/streams`** – Experimental real-time data pipeline demonstrations.

## The `packages/` Directory: Shared Libraries

The `packages/` directory contains the reusable building blocks that power all applications. Each package is published under the `@superset/` scope and can be imported across the monorepo.

### UI Components (`@superset/ui`)

The `packages/ui` library provides a **Shadcn-styled** React component collection including buttons, tables, charts, and form elements. It serves as the visual foundation for all Superset interfaces.

Key files include [`packages/ui/package.json`](https://github.com/superset-sh/superset/blob/main/packages/ui/package.json) and component definitions in `packages/ui/src/components/`.

### Database and Authentication

- **`packages/db`** – Contains **Drizzle ORM** schemas for PostgreSQL (Neon) and SQLite (local development). Schema definitions reside in [`packages/db/package.json`](https://github.com/superset-sh/superset/blob/main/packages/db/package.json) and related migration files.
- **`packages/auth`** – Handles session management, OAuth providers, and JWT utilities. Configuration is centralized in [`packages/auth/package.json`](https://github.com/superset-sh/superset/blob/main/packages/auth/package.json).

### tRPC and Shared Utilities

- **`packages/trpc`** – Defines the shared tRPC router and client definitions used by both `apps/web` and `apps/api`. This ensures type-safe API contracts across the stack. See [`packages/trpc/package.json`](https://github.com/superset-sh/superset/blob/main/packages/trpc/package.json).
- **`packages/shared`** – Miscellaneous utilities including date helpers, enums, and error types that do not belong to a specific domain.
- **`packages/email`** – Tailwind-styled email templates and a simple send-mail wrapper for transactional communications.

### Specialized Packages

The monorepo includes several domain-specific packages:

- **`packages/mcp`** and **`packages/desktop-mcp`** – Implement the Multi-Channel Protocol for real-time messaging between desktop, web, and mobile clients.
- **`packages/local-db`** – SQLite-based persistence specifically for the desktop client.
- **`packages/agent`**, **`packages/chat`**, **`packages/chat-mastra`** – AI-assistant services powering the "agents" feature in Superset.
- **`packages/scripts`** – CLI utilities for repository maintenance, database migrations, and code generation.

## Tooling and Configuration

Root-level configuration files provide the monorepo's single source of truth for building, testing, and releasing:

- **`turbo.jsonc`** – Defines the Turborepo pipeline orchestrating builds, linting, and testing across all workspaces.
- **`biome.jsonc`** – Central lint-and-format configuration using Biome (replacing ESLint and Prettier).
- **[`bunfig.toml`](https://github.com/superset-sh/superset/blob/main/bunfig.toml)** – Global Bun configuration specifying Node version and package manager settings.
- **`tooling/typescript/`** – Shared TypeScript compiler options ([`tsconfig.json`](https://github.com/superset-sh/superset/blob/main/tsconfig.json) extensions) inherited by each workspace.
- **`.github/workflows/`** – CI pipelines for linting, type-checking, Docker builds, and releases.

## Cross-Package Integration Example

The following example demonstrates how the web application consumes shared packages to create a type-safe, component-based page:

```tsx
// src/app/dashboard/DashboardPage.tsx (inside apps/web)
import { useQuery } from '@superset/trpc/react';
import { Card, Button } from '@superset/ui';

export default function DashboardPage() {
  const { data, isLoading } = useQuery(['app.ping']);

  return (
    <Card className="p-4">
      {isLoading ? (
        <span>Loading…</span>
      ) : (
        <div>
          <h2 className="text-xl font-bold">Server says:</h2>
          <p>{data}</p>
          <Button onClick={() => alert('Clicked!')}>Do something</Button>
        </div>
      )}
    </Card>
  );
}

```

Under the hood, `@superset/trpc/react` generates a client hook based on the router defined in `packages/trpc`, while `@superset/ui` provides the Tailwind-styled primitives. This architecture allows the same tRPC router to be consumed by the API server, desktop Electron shell, or mobile React Native app without code duplication.

## Summary

- Apache Superset uses a **Bun + Turbo monorepo** architecture dividing code into `apps/` (runnable products) and `packages/` (shared libraries).
- The **`apps/`** directory contains the Next.js web UI, API server, Electron desktop client, React Native mobile app, and supporting services like documentation and admin tools.
- The **`packages/`** directory publishes scoped modules like `@superset/ui`, `@superset/db`, and `@superset/trpc` that enforce type safety and visual consistency across all applications.
- **Root-level tooling** including `turbo.jsonc`, `biome.jsonc`, and `tooling/typescript/` provides a single source of truth for builds, linting, and CI/CD.

## Frequently Asked Questions

### What is the difference between the `apps` and `packages` directories in Superset?

The `apps/` directory contains standalone, deployable applications such as the Next.js web interface (`apps/web`), the API server (`apps/api`), and the Electron desktop client (`apps/desktop`). In contrast, the `packages/` directory contains reusable libraries published under the `@superset/` scope—like `@superset/ui` for components and `@superset/db` for database schemas—that are imported by multiple apps to ensure consistency.

### How does Apache Superset manage dependencies across the monorepo?

Superset uses **Bun** as the package manager alongside **Turborepo** to orchestrate the dependency graph. The root [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json) defines workspaces that include all `apps/*` and `packages/*` directories, while `turbo.jsonc` configures the build pipeline to cache and parallelize tasks across the repository. This setup ensures that changes to a shared package trigger rebuilds only in the dependent applications.

### Where are the database schemas and ORM definitions located?

Database schemas are centralized in the **`packages/db`** package, which uses **Drizzle ORM** to define tables and relationships for PostgreSQL (Neon) and SQLite (local development). This package is imported by the API server (`apps/api`) and any other service requiring database access, ensuring that schema changes propagate consistently across the entire stack.

### How can I add a new application to the Superset monorepo?

To add a new application, create a new directory inside `apps/` (for example, `apps/my-service`) and initialize it with a [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json) that references the shared packages you need (such as `@superset/trpc` or `@superset/ui`). Ensure the new app inherits the base TypeScript configuration from `tooling/typescript/` and register its build tasks in `turbo.jsonc` so that Turborepo can orchestrate it alongside the existing web, API, and desktop applications.