Frontend modularization

The module is the unit of blast radius: dependency direction, test selection,
bundle cones, and review scope all follow module boundaries. Every decision
here serves one goal: make the file locations tell the truth about who owns
what and who may depend on whom.

Hard rules (check these before anything else)

• NEVER add an export … from re-export at an old path, and NEVER export *
  from a barrel. Move the code, codemod every call site, delete the old path,
  all in the same PR.
• NEVER import past a module's index.ts when that module has
  enforcePublicApi: true, and never past metabase/ui's index at all. If
  the barrel is heavy, the fix is making the module side-effect free (below),
  not a deep import.
• NEVER rewrite a consumer to a lower-level idiom to make the linter pass. If
  the fix makes the consumer worse, the plan is wrong.
• NEVER give a new module enforceSharedTiers: false; new modules ship
  enforced with enforcePublicApi: true and an explicit index.ts.
• NEVER move code without the consumer-tier check (procedure step 2).
• ALWAYS delete a module's enforceSharedTiers: false line in the PR that
  takes it to zero violations.
• ALWAYS measure bun run module-boundaries before and after, and report the
  numbers.
• ALWAYS import dayjs from metabase/dayjs, routing from metabase/router,
  Mantine from metabase/ui, react-redux hooks from metabase/redux; the
  raw specifiers are lint-forbidden.

Files that are ground truth

what	where
module elements, tiers, enforceSharedTiers, enforcePublicApi	frontend/lint/module-boundaries.mjs
shared sub-tiers and levels, cluster rules	frontend/lint/shared-tiers.mjs
standalone boundaries lint (all violations, incl. grandfathered)	bun run module-boundaries (config eslint.config.module-boundaries.mjs)
PR lint (only enforced modules fail CI)	bun run lint-eslint-pure
side-effect-free directories and their exceptions	frontend/build/shared/rspack/side-effect-free-modules.js (SIDE_EFFECT_FREE_PATHS, SIDE_EFFECT_PATHS)
the lint rules that enforce that promise	metabase/no-module-side-effects, metabase/no-base-api-access in frontend/lint/eslint-plugin-metabase/rules/
public-api enforcement	metabase/enforce-module-public-api rule, driven by getPublicApiModules()

The model

Tiers: lib < basic < shared < feature < app. Imports point downward, never
sideways at feature tier (features may not import features; app and EE may
import anything). The shared tier is subdivided in shared-tiers.mjs into
shared-utils (U0…), shared-platform (P0…), and shared-domain, each ordered
into levels. A module imports only strictly lower levels of its sub-tier
plus the sub-tiers below; same-level peers are deliberately forbidden, which
is what makes cycles structurally impossible. A domain may hold two seats
when consumers demand it: a low core and a high surface (metabase-lib below
questions below query_builder; viz-core below visualizations).

Enforcement is per module: enforceSharedTiers: false on an element exempts
it from the level rules (counted by bun run module-boundaries, invisible to
PR lint). Modules with enforcePublicApi: true may only be imported from
outside via metabase/<module>, and import relatively inside.

Deciding where code lives (apply in order; first decisive test wins)

1. Who owns the concept? Code lives with the module that owns its
   concept, not the module that renders or calls it. A mode encoding dashboard
   click behaviour is dashboard code even if viz executes it. Metabot
   conversation state is metabot state even though the store registers it.
2. Consumer-tier check. The destination must sit at or below the file's
   lowest consumer. A single consumer below the proposed home vetoes the
   move; report it, don't force it.
3. Only four legitimate fixes for a bad edge: move the code to its
   terminal home; invert through a designed extension point (a prop, an
   injected component, a contract type owned by the socket); fix the tier
   placement when the declared level is wrong; delete a thin wrapper (a rename
   with no derivation isn't an abstraction — deleting it is the migration).
4. A bridge lives above the lower endpoint. Code that needs both sides of
   a boundary belongs in or above the higher module.
5. "Genuinely shared" is proven by consumers. A shared address needs two
   or more consumers the tier rules can't serve another way. One consumer
   pretending to be shared is a feature module at the wrong address.

Extension points

The socket's owner defines the contract; every plug lives with its extender.
Visualization owns the mode prop and click interfaces, each surface supplies
its mode; the editor owns its extension contract, metabot supplies tiptap
extensions; querying owns TemplateTagsSidebarProps, parameters implements
it.

• Prefer plain props/injection at composition sites. PLUGIN_* registries are
  for edition gating; single-reader slots move out to their reading module;
  slots with many readers live in the module that owns the concept (every
  slot the whitelabel plugin fills lives in whitelabel), tier permitting.
  Keep contracts type-light so implementations can load lazily.
• Identical injection at every callsite is acceptable until a fourth consumer
  or second slot appears; then the composition deserves its own module above
  both parts. Don't pre-build the wrapper.

Store shape

A module that has redux state owns it:

• store/ is private: reducer, plain creators/action types, and selectors,
  typed against the module's own state (QueryBuilderStoreState), never the
  global State. Thunks live in actions/ and import store/, never the
  reverse.
• The barrel is the state API: selectors for reads, creators/thunks for
  writes.
• Store roots (reducers-main, reducers-public, the SDK store) import each
  slice from its module barrel and derive their own state type; no slice
  registry, no declare module merging.
• Cross-module writes: a callback prop when a composition point exists;
  otherwise dispatch the owner's exported creator; an event only when the
  emitter must not know its listeners. Raw dispatch({ type: "…" }) strings
  are banned. A reducer or listener matching another module's internal
  action is the coupling to remove.
• Slices that mirror one endpoint get deleted (the RTK cache is the state); a
  fold over many sources with one writer (the metadata store) is kept as a
  module-private slice behind the barrel.

Endpoints

Endpoints migrate to their owning module via Api.injectEndpoints from the
module's api/ file (settings, metabot, transforms precedents); metabase/api
trends toward the client only. There is one Api object per backend because
tag invalidation only works within one instance. Consumers reach endpoints
only through the owner's exports (useGetCardQuery, cardApi.endpoints.…),
never by name through the base object; metabase/no-base-api-access allows
injection only in metabase/api and **/api/** / **/api.ts, and reaching by
name only in metabase/api and test support (invalidateTags /
resetApiState are fine anywhere). Each endpoint move carries its
metadata-store hookup: the owner calls entitiesFetched from its own
onQueryStarted.

Import-time side effects

Directories in SIDE_EFFECT_FREE_PATHS are marked sideEffects: false for
rspack, so importing one export from their barrel no longer drags the whole
barrel into a bundle. The price: nothing in those directories may do work at
import time, or production silently drops it. metabase/no-module-side-effects
enforces this over every listed directory (module-scope calls, writes to
imported objects or globals, bare imports, control flow at import; escape
hatches are /* #__PURE__ */ and the rule's pure-callee list). Files that
must run at import are listed in SIDE_EFFECT_PATHS (files or directories).

• A library the app configures gets a facade module owning the vendor
  import, the registrations, and the types, with the raw specifier
  lint-forbidden outside it: metabase/router, metabase/ui,
  metabase/redux, metabase/dayjs. Facades are the effect, so they never
  enter SIDE_EFFECT_FREE_PATHS. Never re-register a vendor plugin locally
  (dayjs.extend, echarts use).
• A patch a component needs is an explicit registration module,
  bare-imported by the provider that needs it and listed in
  SIDE_EFFECT_PATHS (Mantine's Popover.Dropdown replacement, imported by
  ThemeProvider).
• Effects with no value to import (global CSS, polyfills, the CSP nonce,
  EE plugin bootstrap) live in the entry's side-effects file and nowhere else.
• Registries are filled from the composition root at boot
  (initializePlugins, registerVisualizations), never by a module
  registering itself at import.
• RTK injection stays at import; when a module with an api/ folder is
  declared side-effect free, list <module>/api/ in SIDE_EFFECT_PATHS.

Naming

The feature keeps the plain product-surface name; a shared carve is named for
what the shared part actually is: the concept when the concept is the shared
thing (settings, current-user, whitelabel, dayjs), or a qualified
capability when the plain noun is taken (search-ui, metrics-ui,
viz-core, data-studio-ui). Never two modules distinguished only by tier
prefix; never generic -shared / -feature suffixes.

Procedure for a move

1. Enumerate consumers honestly (hook-name greps miss the last three):

   grep -rn "metabase/<module>" frontend/src enterprise/frontend/src frontend/test e2e
   grep -rn "jest.mock(\"metabase/<module>" frontend enterprise/frontend
   grep -rn "addMatcher(.*<endpoint>" frontend/src enterprise/frontend/src

   plus sibling files importing the moved file relatively. Classify each by
   module and tier from module-boundaries.mjs / shared-tiers.mjs.
2. Consumer-tier check: destination at or below the lowest consumer. If
   not, stop and report the blocking consumer.
3. Measure before: bun run module-boundaries 2>&1 | tail -1 on the base
   (write the number down).
4. Move: git mv; codemod every importer to metabase/<module> (outside)
   or a relative path (inside); add named exports to the destination barrel
   for every symbol an outside consumer needs (each must have a real
   consumer). Delete the old path. If the module didn't exist: add its element
   in module-boundaries.mjs (ordered before any element it's carved from,
   first match wins), its level in shared-tiers.mjs, enforcePublicApi: true, an index.ts. If the move empties a module's violations, delete
   its enforceSharedTiers: false line. If the module has an api/ folder
   and is side-effect free, list <module>/api/ in SIDE_EFFECT_PATHS.
5. Verify (all of these, report the numbers):

   grep -rn "<old path>" frontend enterprise/frontend e2e        # must be empty
   bunx eslint --no-warn-ignored <touched files>
   bun run lint-eslint-pure                                       # enforce-module-public-api included
   bun run type-check-pure
   bun run test-unit-keep-cljs <touched folders' specs>
   bun run module-boundaries 2>&1 | tail -1                       # after; no violation may name the new files
   bun run build-release:static-viz                               # only if viz/static-viz/ui/dayjs touched; hard 3.5 MiB budget

6. Report: count before/after (state count-neutral explicitly), the edges
   removed by file, flags/rules deleted, barrel exports added, anything you
   skipped and why, and any consumer you found that vetoed part of the move.

Traps (each has bitten at least once)

• Late binding. A bare function reference in a createSelector input
  array, a component identity captured for comparison, a PLUGIN_* object
  read at module scope: all capture at import time and dodge jest spies, EE
  overrides, and lazy loading. Read at call time ((_state) => fn()), or
  inject.
• Plans go stale. Verify every recipe against current code before
  executing; things get merged, renamed, or turn out never to have existed.
  Skip-and-report beats force.
• The linter's blind spots: export … from re-exports, bare-specifier
  packages (custom-viz), pre-seeded caches that never register tags. A grep
  for the old path is the stronger claim than a green lint run.
• Path-keyed baselines reset on rename: a generated per-file ledger
  silently loses a file's history when it moves.
• A heavy barrel is a bundle hazard until its module is side-effect free.
  One constant imported from the metabase/ui barrel pulled Mantine into the
  static-viz bundle and broke its budget; the fix was SIDE_EFFECT_FREE_PATHS,
  never a deep import.
• Type augmentation is program-wide. declare module "dayjs" (and
  similar) makes plugin types available to any file in the same tsconfig, so
  a passing type-check never proves the setup ran; only importing the facade
  does.
• Environment before diagnosis: after a dependency-touching merge,
  bun install before declaring a failure real; worktrees share staleness
  through the node_modules symlink, and a stale target/cljs_dev makes
  type-check-pure fail on metabase-lib/metric/core.ts (rebuild cljs in the
  worktree).

PR shape

One logical change per PR; the body names the specific edges removed (files,
imports, before/after count) and gives each move's ownership reason in plain
language a reviewer outside the effort can follow, without campaign labels.
Stack only for semantic dependency or same-hot-file serialisation, and say
so. Consider codeowner surface when chunking. Open as a draft until measured
and green.