Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

9.2 KB
Raw Blame

This file provides additional guidance to AI coding assistants working under ./frontend/.

Inheritance

  • Follow the repository-wide guidance in ../AGENTS.md.
  • Treat this file as frontend-specific additions, not a replacement for the root instructions.

React

  • All product UI code is React. Use React, Base UI, Tailwind CSS v4, and the shadcn-style component patterns below. There is no Vue runtime.

Localization

  • All user-facing UI text belongs in src/locales/ and is consumed through useTranslation() from react-i18next.
  • Locale files must not contain empty JSON objects; remove them when encountered.
  • The query plan viewer in src/apps/explain-visualizer/ takes its text through a translate prop, which the SQL Editor fills from sql-editor.query-plan-viewer.* in src/locales/; plan-i18n.tsx holds the English defaults. Number formatting there is pinned to en-US.

UX contract

  • Follow ../docs/agents/frontend-ux.md as the canonical source for foundations, page and sheet forms, sticky actions, dialogs, wizards, tables, pagination, selection, and responsive behavior.
  • New shared UI and every UI element directly modified by a change MUST follow the guideline. Do not copy an adjacent legacy pattern merely because it is already present.
  • Product UI must have no scanner violations. Existing code is not a design alternative to copy.
  • Repeated measurements belong in src/components/ui/styles.stylex.ts; semantic colors belong in src/assets/css/tailwind.css; variants belong in the shared primitive's CVA definition.
  • Run node frontend/scripts/check-ui-guideline.mjs after UI work.

Source ownership

Use route ownership as the primary organization axis. Do not add a generic features/ directory.

Location Owns
src/app/ Bootstrap, root providers, layouts, and React Router infrastructure
src/app/router/ Route definitions, navigation helpers, guards, and route handles
src/routes/auth/ Authentication route modules
src/routes/workspace/ Workspace-level route modules, including settings and resource lists
src/routes/project/ Project-scoped route modules; keep page-only components, hooks, and tests beside their route
src/modules/ Cohesive application subsystems reused by routes, such as SQL Editor, agent, AI, CEL, and schema tooling
src/components/ui/ Base UI/shadcn-style primitives
src/components/ Product components genuinely reused by multiple routes or modules
src/stores/ Cross-route Zustand state and compatibility helpers; route-local state stays with its owner
src/api/ ConnectRPC clients, transports, middleware, and API adapters
src/hooks/ and src/lib/ Cross-cutting hooks and framework-neutral helpers only
src/types/ and src/utils/ Existing cross-module contracts and compatibility utilities; prefer owner-local code for new work
src/types/proto-es/ Generated protobuf output; do not edit manually
src/apps/explain-visualizer/ The query plan viewer the SQL Editor result pane renders

Placement and dependency rules

  • Start from the route in src/app/router/routes/, then open the matching subtree under src/routes/.
  • Keep route-only code beside its route. Promote code to components, hooks, or lib only after it has multiple independent consumers.
  • Colocate new types and helpers with their route or module. Do not grow the broad types and utils barrels without a cross-module need.
  • Put a large reusable workflow in src/modules/<name>/; do not spread one subsystem across components and stores.
  • Shared code and modules must not import from src/routes/. Move the shared implementation to its actual owner instead.
  • Prefer direct owner imports such as @/modules/sql-editor/store over broad barrels when the owner is known.
  • Historical migration plans under docs/ describe old paths and are not current architecture guidance.
  • CLAUDE.md files only import their adjacent AGENTS.md; update AGENTS.md as the source of truth.

Tests and checks

  • Name a test after the file it tests and keep it beside that file: Foo.tsx → Foo.test.tsx. One test file per source file — no topic suffixes such as Foo.i18n.test.ts or FooLayout.test.ts, and no __tests__/ directories.
  • Tests import and exercise code. Never read source files as text in a test.
  • Rules about code are checks, not tests. Prefer Biome: noRestrictedImports in biome.json for import boundaries, a GritQL plugin in biome-plugins/ for code patterns. A check Biome cannot express goes in a scripts/check-<name>.mjs, which pnpm test runs automatically; locale rules live in scripts/check-i18n.mjs.
  • Browser flows belong in tests/e2e/.

shadcn Skill

When a shadcn skill is available, use it before writing or modifying React UI. If it is unavailable, inspect src/components/ui/ and follow the component rules below; do not block ordinary frontend work on a missing optional skill.

shadcn Component Guidelines

React UI components live in src/components/ui/ and follow shadcn-style patterns: Base UI primitives wrapped with cva variants and cn() for class merging.

Rules

  • Use existing UI components first — check src/components/ui/ before writing custom markup. Use Badge not styled spans, Alert not custom callout divs, Separator not <hr> or border-t divs
  • Use truncate shorthand — not overflow-hidden text-ellipsis whitespace-nowrap
  • Use cn() for conditional classes — import from @/lib/utils, don't write manual template literal ternaries
  • Overlay layering policy — React overlays use three semantic families: overlay, agent, and critical.
    • Standard app overlays mount into overlay.
    • The shared primitives in src/components/ui/ are the overlay entry points; they are not for agent-owned or critical surfaces.
    • AgentWindow, the minimized launcher, and other agent-owned overlays mount into agent and stay above normal app overlays.
    • Agent-owned surfaces should use the wrappers in src/modules/agent/components/ui/ or other agent-owned code that mounts into getLayerRoot("agent").
    • Forced session-expired / re-login UI mounts into critical and is the only layer allowed above and disabling the agent.
    • critical is reserved for auth/session recovery surfaces such as SessionExpiredSurface; do not introduce new feature-level critical overlays without an explicit policy change.
    • Each family has a dedicated portal root; use getLayerRoot(<family>) to choose the family root, and use LAYER_SURFACE_CLASS / LAYER_BACKDROP_CLASS from src/components/ui/layer.ts for shared intra-family stacking where appropriate.
    • Children inherit the owning family. If a parent mounts into agent or critical, its descendants must not remount into a lower family.
    • Raw global z-index values are forbidden in React feature code for cross-surface stacking. Local component-internal z-index remains allowed when it only affects internal composition.
    • Consumers of overlay primitives must not set their own global z-index.
    • Dropdown-bearing controls inside Sheet, Dialog, or any clipped/stacked container must render their popup through the shared layer. For shared controls that expose a portal prop, such as Combobox and select wrappers built on it, pass portal instead of raising a local dropdown with raw z-index.
    • Menus, popovers, dropdowns, and custom floating panels should use shared DropdownMenu, Popover, Combobox, Select, Dialog, or Sheet primitives rather than ad hoc absolute top-full z-* markup.
    • Do not portal feature UI directly to document.body or a document.body alias. Use the shared overlay primitives, or explicitly mount into the correct semantic root with getLayerRoot(<family>).
    • Do not hide raw global overlay classes in constants, imported helpers, cn() inputs, or interpolated template literals. A value like fixed inset-0 z-50 is still forbidden even when it is not written directly in className.
    • When adding or changing React overlays, run node frontend/scripts/check-layering.mjs before handing off. The scanner is intended to catch raw high-z overlays, forbidden body portals, and policy drift in feature code.
    • The scanner is a guardrail, not proof of policy compliance. It intentionally avoids full static analysis, so imported, dynamic, shadowed, or complex expressions may be unresolved; passing the check does not permit raw global z-index overlays or body portals.

Component Patterns

  • CVA for variants — use class-variance-authority when a component has visual variants (see button.tsx, badge.tsx, alert.tsx for examples)
  • Wrap Base UI primitives — import from @base-ui/react/*, wrap with styled components, export compound parts (Root, Trigger, Content, etc.)
  • Icons — use lucide-react. No sizing classes on icons inside UI components that handle sizing. Prefer size-* shorthand when sizing icons manually
  • Dialog/Sheet must have a Title — required for accessibility. Use className="sr-only" if visually hidden
  • Avatar must have a fallback — for when the image fails to load
  • TabsTrigger must be inside TabsList — never render triggers directly in Tabs