Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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 throughuseTranslation()fromreact-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 atranslateprop, which the SQL Editor fills fromsql-editor.query-plan-viewer.*insrc/locales/;plan-i18n.tsxholds the English defaults. Number formatting there is pinned toen-US.
UX contract
- Follow
../docs/agents/frontend-ux.mdas 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 insrc/assets/css/tailwind.css; variants belong in the shared primitive's CVA definition. - Run
node frontend/scripts/check-ui-guideline.mjsafter 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 undersrc/routes/. - Keep route-only code beside its route. Promote code to
components,hooks, orlibonly after it has multiple independent consumers. - Colocate new types and helpers with their route or module. Do not grow the broad
typesandutilsbarrels without a cross-module need. - Put a large reusable workflow in
src/modules/<name>/; do not spread one subsystem acrosscomponentsandstores. - 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/storeover broad barrels when the owner is known. - Historical migration plans under
docs/describe old paths and are not current architecture guidance. CLAUDE.mdfiles only import their adjacentAGENTS.md; updateAGENTS.mdas 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 asFoo.i18n.test.tsorFooLayout.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:
noRestrictedImportsinbiome.jsonfor import boundaries, a GritQL plugin inbiome-plugins/for code patterns. A check Biome cannot express goes in ascripts/check-<name>.mjs, whichpnpm testruns automatically; locale rules live inscripts/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. UseBadgenot styled spans,Alertnot custom callout divs,Separatornot<hr>orborder-tdivs - Use
truncateshorthand — notoverflow-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, andcritical.- Standard app overlays mount into
overlay. - The shared primitives in
src/components/ui/are theoverlayentry points; they are not for agent-owned or critical surfaces. AgentWindow, the minimized launcher, and other agent-owned overlays mount intoagentand 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 intogetLayerRoot("agent"). - Forced session-expired / re-login UI mounts into
criticaland is the only layer allowed above and disabling the agent. criticalis reserved for auth/session recovery surfaces such asSessionExpiredSurface; 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 useLAYER_SURFACE_CLASS/LAYER_BACKDROP_CLASSfromsrc/components/ui/layer.tsfor shared intra-family stacking where appropriate. - Children inherit the owning family. If a parent mounts into
agentorcritical, its descendants must not remount into a lower family. - Raw global
z-indexvalues are forbidden in React feature code for cross-surface stacking. Local component-internalz-indexremains 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 aportalprop, such asComboboxand select wrappers built on it, passportalinstead of raising a local dropdown with rawz-index. - Menus, popovers, dropdowns, and custom floating panels should use shared
DropdownMenu,Popover,Combobox,Select,Dialog, orSheetprimitives rather than ad hocabsolute top-full z-*markup. - Do not portal feature UI directly to
document.bodyor adocument.bodyalias. Use the shared overlay primitives, or explicitly mount into the correct semantic root withgetLayerRoot(<family>). - Do not hide raw global overlay classes in constants, imported helpers,
cn()inputs, or interpolated template literals. A value likefixed inset-0 z-50is still forbidden even when it is not written directly inclassName. - When adding or changing React overlays, run
node frontend/scripts/check-layering.mjsbefore 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.
- Standard app overlays mount into
Component Patterns
- CVA for variants — use
class-variance-authoritywhen a component has visual variants (seebutton.tsx,badge.tsx,alert.tsxfor 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. Prefersize-*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