Frontend Architecture

Overview

The web application (apps/web) is built with TanStack Start, a full-stack React framework powered by Vite and Nitro. It provides server-side rendering, file-based routing, and seamless integration with the TanStack ecosystem (Router, Query, Form, Store).

Key architectural decisions:

• SSR by default -- TanStack Start renders pages on the server via Nitro, then hydrates on the client. This gives fast initial loads and SEO support without a separate SSR framework.
• Proxy to API -- In both development and production, API requests (/api/**) are proxied through Nitro to the NestJS backend, avoiding CORS complexity.
• Shared UI package -- Presentational components live in @repo/ui, while app-specific components live in apps/web/src/components/.

SSR and Rendering Pipeline

TanStack Start uses Nitro as its server runtime. The pipeline:

The server entry point (src/server.ts) wraps the default TanStack Start handler with Paraglide middleware for locale-aware URL handling:

// src/server.ts
import handler from '@tanstack/react-start/server-entry'
import { paraglideMiddleware } from './paraglide/server'

export default {
  fetch(req: Request): Promise<Response> {
    return paraglideMiddleware(req, () => handler.fetch(req))
  },
}

Vite Plugin Stack

The Vite configuration (vite.config.ts) chains several plugins in order:

API Proxy

Nitro proxies /api/** requests to the NestJS backend via a runtime server route (server/routes/api/[...path].ts). The target is read from the API_URL environment variable (defaulting to http://localhost:4000):

// apps/web/server/routes/api/[...path].ts
export default defineEventHandler((event) => {
  const apiTarget = process.env.API_URL ?? `http://localhost:${process.env.API_PORT ?? 4000}`
  const path = event.context.params?.path ?? ''
  return proxyRequest(event, `${apiTarget}/api/${path}`)
})

This means the frontend never calls the API directly across origins -- all requests go through the same domain. In preview environments, the server route also injects the x-vercel-protection-bypass header to reach SSO-protected API previews.

File-Based Routing

TanStack Router generates a typed route tree from the file system. Routes live in apps/web/src/routes/ and follow these conventions:

Route File Patterns

Configuration

Route generation is configured in tsr.config.json:

{
  "routeFileIgnorePattern": "\\.test\\.tsx?$"
}

Test files (*.test.tsx) colocated with routes are excluded from route generation.

Route Anatomy

Every route uses createFileRoute with a route path that matches its filesystem position:

// routes/login.tsx
export const Route = createFileRoute('/login')({
  beforeLoad: async () => {
    // Auth guard -- redirect if already logged in
    const { data } = await authClient.getSession()
    if (data) throw redirect({ to: '/' })
  },
  loader: fetchEnabledProviders,
  component: LoginPage,
  head: () => ({
    meta: [{ title: 'Sign In | Roxabi' }],
  }),
})

Key hooks in the route lifecycle:

Layout Routes

A route file without child routes in a matching directory acts as a layout when it renders <Outlet />.

Root Route

The root route (__root.tsx) defines the HTML shell, global providers, and chromeless mode:

export const Route = createRootRouteWithContext<MyRouterContext>()({
  beforeLoad: async () => {
    if (typeof document !== 'undefined') {
      document.documentElement.setAttribute('lang', getLocale())
    }
  },
  head: () => ({ /* charset, viewport, title, stylesheet */ }),
  notFoundComponent: NotFound,
  shellComponent: RootDocument,
})

The AppShell component renders the Header on all routes. The /docs and /talks routes have been removed from apps/web — docs are served by the standalone apps/docs site, and talks were migrated to external repos. CHROMELESS_PREFIXES is now an empty array.

Server API Routes

TanStack Start supports server-only API handlers using the server.handlers property:

// routes/demo/api.tq-todos.ts
export const Route = createFileRoute('/demo/api/tq-todos')({
  server: {
    handlers: {
      GET: () => Response.json(todos),
      POST: async ({ request }) => {
        const name = await request.json()
        todos.push({ id: todos.length + 1, name })
        return Response.json({ id: todos.length, name })
      },
    },
  },
})

These files use the .ts extension (not .tsx) and run exclusively on the server.

State Management

The frontend uses a layered approach to state, matching each concern to the right tool:

TanStack Query

TanStack Query handles all asynchronous server state. It is initialized in src/integrations/tanstack-query/root-provider.tsx and integrated with the router for SSR data dehydration:

// src/router.tsx
const rqContext = TanstackQuery.getContext()

const router = createRouter({
  routeTree,
  context: { ...rqContext },
  defaultPreload: 'intent',
})

setupRouterSsrQueryIntegration({ router, queryClient: rqContext.queryClient })

The setupRouterSsrQueryIntegration call ensures query data fetched during SSR is serialized into the HTML and rehydrated on the client without duplicate requests.

Route loaders prefetch queries, and components consume them with useQuery:

// In a route component
const { data, refetch } = useQuery<Todo[]>({
  queryKey: ['todos'],
  queryFn: () => fetch('/demo/api/tq-todos').then((res) => res.json()),
  initialData: [],
})

TanStack Form

Form state uses @tanstack/react-form with a form hook factory pattern using createFormHook. This creates a useAppForm hook that bundles form field components with validation, enabling a composable API:

const form = useAppForm({
  defaultValues: { title: '', description: '' },
  validators: { onBlur: schema },
  onSubmit: () => {},
})

// In JSX:
<form.AppField name="title">
  {(field) => <field.TextField label="Title" />}
</form.AppField>

Validation integrates with Zod schemas via the validators option.

Server Functions

TanStack Start's createServerFn provides type-safe server-only functions callable from loaders or components. These run on the server during SSR and via RPC on client navigation:

const getPunkSongs = createServerFn({ method: 'GET' })
  .handler(async () => [
    { id: 1, name: 'Teenage Dirtbag', artist: 'Wheatus' },
    // ...
  ])

// Used in a route loader
export const Route = createFileRoute('/demo/start/ssr/full-ssr')({
  loader: async () => await getPunkSongs(),
})

Server functions can also accept validated input:

const addTodo = createServerFn({ method: 'POST' })
  .inputValidator((d: string) => d)
  .handler(async ({ data }) => { /* server-side logic */ })

Documentation Site (apps/docs)

Documentation is served by a standalone Next.js application at apps/docs/, powered by Fumadocs v16. It is deployed separately to docs.app.roxabi.com.

The MDX source files live at docs/ (repo root). apps/docs reads them via source.config.ts and serves them through a Next.js catch-all route.

Run the docs site locally:

bun run docs   # starts apps/docs on port 3002

apps/docs is a separate TurboRepo package (@repo/docs) with its own Next.js build pipeline; it is not part of the apps/web Vite/Nitro build.

Component Architecture

Components are organized in two layers: shared (@repo/ui) and app-specific (apps/web/src/components/).

Directory Structure

apps/web/src/
  components/
    Header.tsx              # App header with nav, auth, locale
    Footer.tsx              # App footer
    AuthLayout.tsx          # Shared layout for auth pages
    UserMenu.tsx            # Authenticated user dropdown
    OrgSwitcher.tsx         # Organization switching dropdown
    ThemeToggle.tsx         # Dark/light mode toggle
    LocaleSwitcher.tsx      # Language selector
    GithubIcon.tsx          # GitHub link icon
    FeatureCard.tsx         # Landing page feature card
    landing/                # Landing page sections
      HeroSection.tsx
      FeaturesSection.tsx
      AiTeamSection.tsx
      DxSection.tsx
      TechStackSection.tsx
      CtaSection.tsx
      SectionHeading.tsx

Component Patterns

Route-specific components live in route directories using the - prefix to exclude them from routing:

routes/design-system/-components/    # Not routed
  ColorPicker.tsx
  ComponentShowcase.tsx
  ThemeEditor.tsx

Page components are defined inline in route files. Each route file exports a Route object and defines its component as a local function -- not as a separate file:

export const Route = createFileRoute('/login')({
  component: LoginPage,
})

function LoginPage() {
  // ...
}

Section components break large pages into focused, testable units. The landing page composes sections:

function LandingPage() {
  return (
    <div>
      <HeroSection />
      <AnimatedSection><FeaturesSection /></AnimatedSection>
      <AnimatedSection><AiTeamSection /></AnimatedSection>
      {/* ... */}
    </div>
  )
}

Auth client usage follows a consistent pattern: authClient.getSession() in beforeLoad for guards, and useSession() hook in components for reactive session state.

Shared UI Package (@repo/ui)

The packages/ui package provides the design system primitives consumed by apps/web.

Architecture

Package Exports

The package exposes three entry points:

{
  ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
  "./styles.css": "./dist/styles.css",
  "./theme.css": "./src/theme.css"
}

• @repo/ui -- All components, hooks, theme utilities, and the cn() helper
• @repo/ui/styles.css -- Compiled component styles
• @repo/ui/theme.css -- CSS custom properties for theming

Component Catalog

The package exports 30+ components, including:

Theme Engine

The theme system uses OKLCH color space for perceptually uniform color manipulation:

import { applyTheme, deriveFullTheme, hexToOklch, meetsWcagAA } from '@repo/ui'

Theme presets (base + color variants) can be composed and applied at runtime. The contrastRatio and meetsWcagAA utilities ensure accessibility compliance.

Integration with apps/web

Components are imported directly from the package:

import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label } from '@repo/ui'

The "use client" banner in the tsup build ensures all UI components are treated as client components in SSR contexts.

Client/Server Boundary

The architecture maintains a clear separation between server-side and client-side code:

Server-Only Code

Client-Only Code

Data Flow Patterns

SSR with loader -- Data is fetched server-side and available immediately on hydration:

SSR with TanStack Query -- Server-fetched queries are dehydrated and rehydrated:

Client-side API call -- Post-hydration data fetching through the Nitro proxy:

Server function RPC -- Type-safe server calls from client components:

Internationalization

The frontend uses Paraglide JS (Inlang) for compile-time i18n with URL-based locale routing.

The router integrates locale-aware URL rewriting:

const router = createRouter({
  routeTree,
  rewrite: {
    input: ({ url }) => deLocalizeUrl(url),
    output: ({ url }) => localizeUrl(url),
  },
})

This means route definitions use unlocalized paths (/login), while the actual URLs include the locale prefix (/fr/login).

Error Handling

Error boundaries are handled by the root error boundary (__root.tsx) — catches unhandled errors in any route and displays a generic error page with a retry button using i18n messages. Uses react-error-boundary with a custom fallback component.

Developer Tooling

In development mode (import.meta.env.DEV), the root route renders a unified TanStack Devtools panel with two plugins:

These are tree-shaken from production builds.

Related Documentation

• Architecture overview -- Monorepo structure and data flow
• Database architecture -- Drizzle ORM and schema conventions
• Frontend patterns -- Coding standards for React and TanStack
• Authentication guide -- Better Auth integration details
• Deployment guide -- Vercel deployment for web and API