Web Frontend

Web app frontend (apps/web)

When to use: apps/web UI — routes, @repo/ui, TanStack Start server functions and collections, navigation (Link vs useNavigate), forms (useForm with createFormSubmitHandler + fieldErrorsAsStrings when Zod validation errors should appear on fields), Tailwind layout rules, design-system updates, and useEffect / useMountEffect policy.

Required design context

Before designing or editing any user-facing UI, read the root design.md. It defines the Latitude product UI rules for reuse-first discovery, composition, hierarchy, spacing, actions, responsive behavior, and route versus modal versus drawer decisions.

Treat packages/ui/src/components/, packages/ui/src/tokens/, the live apps/design-system inventory, and adjacent apps/web routes as the implementation source of truth. Search for an existing component and a comparable in-product pattern before creating a component, introducing custom styling, or adding a new token. Follow design.md when deciding whether new UI is justified; follow this skill for the required React, TanStack, route, form, and component APIs.

For project-route UI, use the local -components/section-header.tsx SectionHeader once for the route-level header, matching the Behaviors page's Layout.Header composition. A project overview defaults to the standard variant so its title has the same size and weight as the Behaviors route header; use variant="xl" only when the task and a comparable existing route justify it. Import the existing header and layout rather than recreating their structure or classes locally.

Project overview content has a strict default hierarchy: metric values may use Text.H5; panels use muted Text.H6 labels; repeated row and issue titles use compact Text.H6B; supporting copy uses muted Text.H6. Do not use Text.H3*, Text.H4*, or Text.H5* as panel, row, issue, or block titles. Do not use SectionHeader as a panel heading.

For project overview metrics, first inspect the compact AggregationItem strips in users/-components/users-analytics-panel.tsx, tools/-components/tools-analytics-panel.tsx, and -components/aggregations/general-aggregations.tsx. Preserve that anatomy and keep metrics in one horizontally scrollable row; do not create a grid, separate Card per metric, or a route-local approximation of the existing aggregation item. Detail sections use muted labels plus divide-y rows, not nested cards or dashboard-specific mini-panels. Read the Project Overview Contract in design.md before implementation.

Existing V2 UI reference

• Before building new UI, inspect comparable V2 routes and components in apps/web/src/routes/ and packages/ui/src/components/.
• Reuse the closest V2 interaction and composition pattern when it is solid; preserve consistency across the active product rather than recreating the pattern locally.
• Treat the V2 application and apps/design-system as the visual and behavioral reference. Do not use V1 as a default source of UI guidance.

React 19

The project uses React 19. Follow modern patterns and avoid deprecated APIs:

• No forwardRef — ref is a regular prop in React 19. Declare it in the props type and destructure it directly.
• No ElementRef — use React.ComponentRef<typeof SomeComponent> instead (the ElementRef alias is deprecated).
• No gratuitous useMemo / useCallback / React.memo — the React Compiler (enabled in the build) auto-memoizes. Only add manual memoization when profiling shows a concrete bottleneck; remove existing wrappers when they have no measured benefit.
• Prefer use() for consuming promises and context where appropriate.

// ❌ Deprecated React 18 pattern
const Input = forwardRef<ElementRef<typeof Primitive>, InputProps>(({ className, ...props }, ref) => (
  <Primitive ref={ref} {...props} />
))
Input.displayName = "Input"

// ✅ React 19 — ref is a regular prop
function Input({ className, ref, ...props }: InputProps & { ref?: React.Ref<React.ComponentRef<typeof Primitive>> }) {
  return <Primitive ref={ref} {...props} />
}

Components

• Always use Text from @repo/ui for text content
• Always use Button from @repo/ui for buttons
• Do not nest Text inside Button. Button already sets font size, weight, and color; use plain text (and optional icons) as direct children. Wrapping the label in Text duplicates styles (e.g. avoid <Button><Text.H5>Save</Text.H5></Button>).
• Lucide icons: import from lucide-react and pass the component to @repo/ui’s Icon via the icon prop (e.g. <Icon icon={Pencil} size="sm" />). Prefer that over raw <Pencil /> so shared sizing and color tokens apply. Buttons and other primitives that accept an icon prop follow the same pattern; otherwise wrap with Icon.
• Always use GoogleIcon and GitHubIcon from @repo/ui for OAuth provider icons

Modal: short form vs composition

Default to the short form — <Modal title=… description=… footer=… open dismissible onOpenChange={…}>{children}</Modal>. It auto-wraps children in Modal.Body with the standard px-6 padding and the same scroll behavior every other modal uses, so content inside it can't drift out of the design system. This is the shape RenameProjectModal (the form reference cited above) uses — treat it as the canonical pattern.

<Modal
  open
  dismissible
  onOpenChange={(next) => (!next ? onClose() : undefined)}
  title="Change sampling rate"
  description="Percentage of incoming traces this evaluation runs against."
  footer={
    <>
      <CloseTrigger />
      <Button onClick={() => void form.handleSubmit()}>Save</Button>
    </>
  }
>
  <form onSubmit={…}>{/* fields */}</form>
</Modal>

Reach for the composition form (Modal.Root / Modal.Content / Modal.Header / Modal.Body / Modal.Footer) only when the short form can't express what you need:

• Custom header JSX beyond a string title + description — render <Modal.Header>{custom JSX}</Modal.Header> directly.
• Multiple body regions, or content that must opt out of the standard body padding / scroll.
• Conditional rendering of header or footer that can't be driven by passing undefined.

Notes:

• dismissible defaults to false — pass it to show the close X.
• scrollable defaults to true. For short bodies that shouldn't grow to fill height, pass scrollable={false}.
• Do not wrap your children in your own <Modal.Body> while using the short form — children are already wrapped, double-wrapping nests padding.

Route-level component organization

Place React components close to the routes that use them, inside a -components/ subfolder within the route directory. This keeps route files (which TanStack Router auto-discovers) clearly separated from supporting components.

routes/_authenticated/projects/$projectId/datasets/
├── index.tsx                       # route file
├── $datasetId.tsx                  # route file
└── -components/                    # supporting components for these routes
    ├── dataset-table.tsx
    ├── row-detail-panel.tsx
    └── version-badge.tsx

• Route files live directly in the route directory — TanStack Router discovers them
• Supporting UI for those routes lives in the adjacent -components/ folder
• domains/ directories (apps/web/src/domains/) are for state management only: server functions (writes) and collections/queries (reads) — not UI components

Design system showcase

• When adding a new implemented UI component in packages/ui (or replacing a placeholder export with a real implementation), update apps/web/src/routes/design-system.tsx to include a usage example for that component in both light and dark mode previews.
• Treat apps/web/src/routes/design-system.tsx as the canonical visual inventory for @repo/ui components.

State management (TanStack)

The web app uses a server-centric, query-driven architecture built on the TanStack ecosystem. No Zustand, Redux, or global stores.

Server functions — All data fetching and mutations use createServerFn from @tanstack/react-start:

import { Effect } from "effect"
import { ProjectRepository, createProjectUseCase } from "@domain/projects"
import { ProjectRepositoryLive, SqlClientLive } from "@platform/db-postgres"
import { getPostgresClient } from "../../server/clients.ts"

// Query (GET)
export const listProjects = createServerFn({ method: "GET" }).handler(async () => {
  const { organizationId } = await requireSession()
  const client = getPostgresClient()

  return await Effect.runPromise(
    Effect.gen(function* () {
      const repo = yield* ProjectRepository
      return yield* repo.findAll()
    }).pipe(
      Effect.provide(ProjectRepositoryLive),
      Effect.provide(SqlClientLive(client, organizationId)),
    ),
  )
})

// Mutation (POST) with Zod validation
export const createProject = createServerFn({ method: "POST" })
  .inputValidator(createProjectSchema)
  .handler(async ({ data }) => {
    const { userId, organizationId } = await requireSession()
    const client = getPostgresClient()

    return await Effect.runPromise(
      createProjectUseCase({...}).pipe(
        Effect.provide(ProjectRepositoryLive),
        Effect.provide(SqlClientLive(client, organizationId)),
      ),
    )
  })

Server functions live in apps/web/src/domains/*/functions.ts.

Collections — Client-side reactive state uses TanStack React DB + Query via queryCollectionOptions:

const projectsCollection = createCollection(
  queryCollectionOptions({
    queryClient,
    queryKey: ["projects"],
    queryFn: () => listProjects(),
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => { /* optimistic insert */ },
    onUpdate: async ({ transaction }) => { /* optimistic update */ },
    onDelete: async ({ transaction }) => { /* optimistic delete */ },
  }),
)

export const useProjectsCollection = (...) => useLiveQuery(...)

Collection files live in apps/web/src/domains/*/collection.ts.

Route middleware vs route data

• Use beforeLoad for middleware-style checks that should block the route tree early: auth redirects, authorization gates, and other preconditions.
• Use loader for data the route or layout actually renders. This keeps rendered data in TanStack Router's loader lifecycle, so it can use staleTime, useLoaderData({ select }), and avoid unnecessary refetching on same-route search-param navigations.
• If the same lookup is both your guard and your rendered data source, prefer doing that work in loader once instead of duplicating it across beforeLoad and loader.
• When multiple descendant routes need parent loader data, prefer a small route-scoped wrapper around getRouteApi("...") instead of repeating the route id string in every file.

export const Route = createFileRoute("/admin")({
  beforeLoad: async () => {
    const session = await getSession()
    if (!session?.user.isAdmin) throw redirect({ to: "/" })
  },
})

export const Route = createFileRoute("/_authenticated")({
  staleTime: Infinity,
  loader: async () => {
    const session = await getSession()
    if (!session) throw redirect({ to: "/login" })

    const sessionData = session.session as Record<string, unknown>
    const organizationId =
      typeof sessionData.activeOrganizationId === "string" ? sessionData.activeOrganizationId : null
    if (!organizationId) throw redirect({ to: "/welcome" })

    return {
      user: session.user,
      organizationId,
    }
  },
})

const authenticatedRoute = getRouteApi("/_authenticated")

export function useAuthenticatedUser() {
  return authenticatedRoute.useLoaderData({ select: (data) => data.user })
}

Key rules:

• Server functions are the only data-fetching mechanism — no direct REST API calls from the client
• Use collections for reactive, queryable client state with automatic server sync
• Use useState for local UI state (modals, form visibility); no global stores
• Invalidate query cache after mutations: getQueryClient().invalidateQueries({ queryKey: [...] })
• Forms use TanStack React Form (useForm + form.Field)