Metabase

# MISSION: Scaffold "Metabase" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Metabase**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Metabase
- **What It Does**: Metabase is a self-hosted business intelligence tool: a Clojure and JVM backend (src/metabase) compiled to a single jar, paired with a TypeScript and React frontend built with Rspack, Mantine, and Redux Toolkit, plus a ClojureScript build and a Python-based SQL transform layer.
- **Domain & Category**: Business Intelligence Platform
- **Production Scale**: 20+ people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Shipping the backend as one Clojure uberjar behind a bare JVM Docker image keeps self-hosting to a single artifact and runtime, while splitting SQL-dialect transform logic into a separate Python package lets that feature reuse an existing SQL-transpilation library instead of reimplementing it in Clojure.
- **Live Website Reference**: https://metabase.com
- **Source Repository**: https://github.com/metabase/metabase
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Clojure, ClojureScript, TypeScript, React, Java, Python, PostgreSQL, MySQL
- **Primary Language(s)**: Clojure, TypeScript, JavaScript
- **License of the reference repo**: NOASSERTION
- **Frontend**: React — Component framework for the web app under frontend/src.; Mantine — UI component library used across the application interface.; Redux Toolkit — Application state management for the frontend.; CodeMirror — Powers the native SQL editor, including SQL-specific language modes.; Rspack — Rust-based bundler that builds the production frontend assets.
- **Backend & APIs**: Clojure — Implements the core application server under src/metabase, compiled to a single uberjar.; Java — JVM runtime; the release image runs the compiled jar on eclipse-temurin:25-jre-alpine.; ClojureScript — Additional frontend logic compiled via shadow-cljs, alongside the TypeScript codebase.; Python — Powers a SQL-transform feature via a separate Python package depending on sqlglot.
- **Data & persistence**: PostgreSQL — One of the most prominently supported data warehouse connections, per repository topics.; MySQL — Also a prominently supported data warehouse connection, per repository topics.
- **Infrastructure & deploy**: Docker — Multi-stage build compiles the backend and frontend; a separate slim image serves the runtime jar.; Bun — Installs and manages frontend JavaScript dependencies during the build.
- **Tooling, testing & ops**: Cypress — Drives the end-to-end test suite against a running instance.; Storybook — Component development and visual review environment for the frontend.; GitHub Actions — Runs the large multi-workflow CI/CD pipeline covering backend, frontend, e2e, and release automation.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/metabase/metabase @ e28ae43)
1. **Backend is a single Clojure/JVM artifact, not microservices**: src/metabase (Clojure) compiles to a single uberjar via bin/build.sh, and the Dockerfile runtime stage is a bare eclipse-temurin:25-jre-alpine image running that jar, so the whole backend ships as one deployable artifact rather than separate services.
2. **Frontend build has moved onto Rspack instead of webpack**: package.json devDependencies include @rspack/core, @rspack/cli, and @rspack/dev-server, a Rust-based webpack-compatible bundler, alongside @storybook/react-webpack5 for component development, so the production build and Storybook currently target different bundler configurations.
3. **Bun manages frontend dependencies instead of npm or yarn**: package.json declares bun >=1.0.0 as a required engine, and the root Dockerfile installs bun globally with npm install -g bun before running bun install --frozen-lockfile, so dependency installation is standardized on Bun even though the built output is ordinary JavaScript.
4. **A Python transform layer sits alongside the Clojure core**: resources/python-sources/pyproject.toml defines a separate Python package depending on sqlglot for SQL dialect parsing and transpilation, exercised by the transforms-python-stress-test.yml workflow, so cross-dialect SQL handling for the transforms feature runs in Python rather than Clojure.
5. **The embedding SDK is tested against real host app frameworks**: e2e/embedding-sdk-host-apps contains separate package.json projects for an Angular 20 app, two Next.js 15 variants (app router and pages router), and a Vite 6 app, each installing the embedding SDK, so compatibility is verified against real framework setups rather than one mocked host.
6. **ClojureScript compiles alongside TypeScript, not instead of it**: shadow-cljs.edn configures a ClojureScript build that coexists with the primary TypeScript and React frontend in frontend/src, so the client is built from two source languages rather than a single one.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Isolate interactive UI state to leaf components. Keep core pages lightweight and performant.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (PostgreSQL, MySQL): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.