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

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 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, 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, 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.
• apps/mobile – A React Native application built with Expo, providing a native mobile experience. Entry points are defined in 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 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 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 and related migration files.
• packages/auth – Handles session management, OAuth providers, and JWT utilities. Configuration is centralized in 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.
• 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 – Global Bun configuration specifying Node version and package manager settings.
• tooling/typescript/ – Shared TypeScript compiler options (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:

// 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}