Develop the web app

The UI sends browser requests to same-origin paths:

/api/v1/auth/me
/api/v1/organizations/{organization_id}/agents

The Next.js configuration rewrites /api/:path* to the backend configured by NEXT_PUBLIC_BACKEND_URL, whose local default is http://localhost:8000. You can set it explicitly:

NEXT_PUBLIC_BACKEND_URL=http://localhost:8000 make dev-ui

This arrangement lets the browser use same-origin /api URLs while Next.js resolves the backend location. The API singleton uses an empty base URL deliberately:

const apiClient = createApiClient({ baseURL: "" });

Verify the development path

• Open http://localhost:8000/api/v1/health
• Confirm the response reports a connected database
• Open http://localhost:3000/login and sign in with a local account
• Confirm /dashboard redirects into an available Organization or Platform View
• Check the browser network panel for same-origin /api/v1/... requests

App Router pages are composition points. They choose the feature component and supply route parameters, but the feature workflow stays under ui/src/features/.

For an Organization-scoped resource detail page, use a structure such as:

ui/src/
├── app/
│   └── dashboard/
│       └── [orgId]/
│           └── resources/
│               └── [resourceId]/
│                   └── page.tsx
└── features/
    └── resources/
        ├── schemas.ts
        ├── hooks/
        ├── components/
        │   └── resource-detail-page.tsx
        └── utils.ts

The route itself should stay small, and remains a Server Component:

import { ResourceDetailPage } from "@/features/resources/components/resource-detail-page";

interface PageProps {
  params: Promise<{ resourceId: string }>;
}

export default async function ResourceDetailRoute({ params }: PageProps) {
  const { resourceId } = await params;
  return <ResourceDetailPage resourceId={resourceId} />;
}

The feature component owns the client boundary:

"use client";

import { useResource } from "../hooks/use-resource";

export function ResourceDetailPage({
  resourceId,
}: {
  resourceId: string;
}) {
  const { resource, isLoadingResource, error } = useResource(resourceId);

  // Render the feature state.
}

Choose the component boundary

Do not mark an entire route tree as client-rendered because one nested control needs state. Place the client boundary at the smallest useful feature boundary.

Important responses must be validated with a feature-local Zod schema. The shared client transforms the response before validation, so the schema describes the frontend shape.

{
  "id": "7bc68dad-4f87-47fb-996c-636fc367103c",
  "display_name": "Example resource",
  "organization_id": "1a9650cf-dd44-4ca1-b105-c0cf19f62f56",
  "created_at": "2026-08-29T10:00:00Z"
}

import { z } from "zod";

export const ResourceSchema = z.object({
  id: z.string().uuid(),
  displayName: z.string(),
  organizationId: z.string().uuid(),
  createdAt: z.string(),
});

export type Resource = z.infer<typeof ResourceSchema>;

Export the schema and its inferred type from the same file.

Request transformation

Write ordinary request bodies in frontend camelCase:

await api.patch(
  `${orgApiBase}/resources/${resourceId}`,
  {
    displayName: "Updated resource",
  },
);

The shared request interceptor sends:

{
  "display_name": "Updated resource"
}

Do not pre-convert normal JSON request bodies to snake_case.

Query strings

The body transformer does not rewrite URL query-string names. Use the backend’s wire-format parameter names:

const params = new URLSearchParams();
params.set("page", String(page));
params.set("page_size", String(pageSize));
params.set("search", search);

Use page_size, not pageSize, in the URL unless the backend endpoint explicitly declares otherwise.

Schema validation

Supply the schema to the shared client:

const response = await api.get<Resource>(
  `${orgApiBase}/resources/${resourceId}`,
  {
    schema: ResourceSchema,
  },
);

return response.data;

A contract mismatch then becomes an ApiError with a validation failure, instead of silently entering the UI as malformed data.

When an API response changes, update the backend response DTO, the feature Zod schema, query and mutation hooks, fixtures, intercepted API responses, Playwright expectations, and every component that renders the changed fields.

Server-owned application data belongs in TanStack Query. Three pieces work together:

1. Define the query keys

import { createQueryKeyStructure } from "@/shared/query-keys";

export const resourcesKey = createQueryKeyStructure("resources");

The factory provides list and detail families:

resourcesKey.all
resourcesKey.lists()
resourcesKey.list({ filters })
resourcesKey.details()
resourcesKey.detail(resourceId)

Extend those helpers for nested resources:

export const resourceHistoryKey = (resourceId: string) =>
  [...resourcesKey.detail(resourceId), "history"] as const;

Do not scatter literal arrays such as ["resources", "detail", id] through components.

2. Add an Organization-scoped hook

"use client";

import { useQuery } from "@tanstack/react-query";

import { useOrganizationApiBase } from "@/features/organizations/hooks/use-organization-api-base";
import { useOrganizationContext } from "@/features/organizations/providers/organization-provider";
import { api } from "@/shared/api";

import { ResourceSchema, type Resource } from "../schemas";
import { resourcesKey } from "../utils";

export function useResource(resourceId: string | null) {
  const orgApiBase = useOrganizationApiBase();
  const { selectedOrganization } = useOrganizationContext();
  const organizationId = selectedOrganization?.id ?? null;

  const query = useQuery({
    queryKey: resourcesKey.detail(
      organizationId && resourceId
        ? `${organizationId}:${resourceId}`
        : "none",
    ),
    enabled: organizationId !== null && resourceId !== null,
    queryFn: async () => {
      const response = await api.get<Resource>(
        `${orgApiBase}/resources/${resourceId}`,
        {
          schema: ResourceSchema,
        },
      );
      return response.data;
    },
  });

  return {
    resource: query.data ?? null,
    isLoadingResource: query.isPending,
    error: query.error,
    refetchResource: query.refetch,
  };
}

Hooks should expose domain-oriented names. Components should not need to understand every internal property of a raw query observer.

3. Decide how Organization identity enters the cache

Including Organization identity directly in the key makes the separation explicit, but you must still make sure components never display a previous Organization’s cached result as placeholder data.

4. Use progressive queries for load-more interfaces

const query = useInfiniteQuery({
  queryKey: resourcesKey.list({
    scope: { organizationId, mode: "infinite" },
    filters: { search, pageSize },
  }),
  queryFn: async ({ pageParam = 1 }) => {
    // Fetch one page.
  },
  initialPageParam: 1,
  getNextPageParam: (lastPage) => {
    const nextPage = lastPage.page + 1;
    const totalPages = Math.ceil(lastPage.total / lastPage.pageSize);
    return nextPage <= totalPages ? nextPage : undefined;
  },
});

Keep follow-up loading local. Loading another page should not replace the entire route with its initial loading fallback.

Mutations own user-triggered server workflows. The normal lifecycle is:

1. Submit A user action in an event handler starts the workflow — never an effect watching state.
2. Validate Client-side validation runs first, usually a Zod form schema through React Hook Form.
3. Mutate The TanStack mutation calls the shared API client, which transforms the body and validates the response.
4. Update or invalidate Set the detail cache directly where the response is authoritative, then invalidate every affected family.
5. Notify Report success or failure concisely, normally through Sonner.
6. Render new state The refreshed cache re-renders the affected views without a manual refetch chain.

A representative update hook is:

"use client";

import { useMutation, useQueryClient } from "@tanstack/react-query";

import { useOrganizationApiBase } from "@/features/organizations/hooks/use-organization-api-base";
import { api } from "@/shared/api";

import { ResourceSchema, type Resource } from "../schemas";
import { resourcesKey } from "../utils";

type ResourceUpdate = {
  resourceId: string;
  displayName?: string;
};

export function useUpdateResource() {
  const queryClient = useQueryClient();
  const orgApiBase = useOrganizationApiBase();

  return useMutation({
    mutationFn: async ({ resourceId, ...body }: ResourceUpdate) => {
      const response = await api.patch<Resource>(
        `${orgApiBase}/resources/${resourceId}`,
        body,
        {
          schema: ResourceSchema,
        },
      );
      return response.data;
    },
    onSuccess: (resource) => {
      queryClient.setQueryData(
        resourcesKey.detail(resource.id),
        resource,
      );

      void queryClient.invalidateQueries({
        queryKey: resourcesKey.lists(),
      });
    },
  });
}

Adapt the cache key to the Organization strategy the feature selected.

Cache behavior by mutation

Do not invalidate only the component currently on screen. Consider every list, detail, summary, selector, and dashboard that represents the changed entity.

Protected application routes are composed through:

AppProvider
  └── UserContextProvider
       └── OrganizationProvider
            └── Dashboard route

Authentication

The shared API client sends credentials, reads access tokens from the authentication store, attaches the bearer header, refreshes near-expiry tokens, coalesces simultaneous refresh attempts, retries one failed authenticated request after refresh, marks the session expired when refresh fails, and normalizes failures as ApiError.

Bypassing the shared client also bypasses token refresh, key transformation, schema validation, and normalized errors. Use skipAuth: true only for deliberately public endpoints — login, forgot password, reset password, invite acceptance, and best-effort logout cleanup.

Public authentication routes bypass UserContextProvider and OrganizationProvider. Protected routes resolve the current user before rendering their children.

Organization View

The active Organization comes from the URL, /dashboard/{orgId}/.... Use useOrganizationApiBase() to build Organization-scoped API paths:

const orgApiBase = useOrganizationApiBase();

const url = `${orgApiBase}/agents`;

That produces /api/v1/organizations/{organization_id}/agents.

Do not mutate a shared Organization header. The Organization is explicit in both the dashboard URL and the API URL. If the URL contains an inaccessible or stale Organization ID, OrganizationProvider redirects to an available fallback.

Platform View

Platform View lives under /dashboard/platform and has no active Organization. Platform hooks call /api/v1/platform/... directly and must not use useOrganizationApiBase().

Protect platform interfaces with the existing Platform Administrator UI boundary, but remember that the API remains the final authorization authority.

Organization switching and query isolation

Several existing query families do not encode Organization identity in their keys. On a genuine Organization-to-Organization switch, OrganizationProvider removes those known families before child query effects start.

Build new interfaces from existing primitives and design tokens before introducing another abstraction.

State ownership

Use this, avoid this

Forms

For forms with meaningful validation: define a Zod form schema, infer the TypeScript form type, use React Hook Form with the Zod resolver, render accessible labels and field errors, submit through a mutation hook, disable duplicate submission while pending, and show concise success or failure feedback.

Confirmations

Use the shared ConfirmationDialog for every confirmation workflow:

<ConfirmationDialog
  open={isConfirmingDelete}
  onOpenChange={setIsConfirmingDelete}
  title="Delete this resource?"
  description="This action cannot be undone."
  confirmLabel="Delete resource"
  pendingLabel="Deleting…"
  variant="destructive"
  isPending={deleteMutation.isPending}
  onConfirm={handleDelete}
/>

Option selectors

Use the shared shadcn Select primitives, keeping every SelectItem inside a SelectGroup:

<Select value={value} onValueChange={setValue}>
  <SelectTrigger>
    <SelectValue placeholder="Choose an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectItem value="first">First option</SelectItem>
      <SelectItem value="second">Second option</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

Do not add a native <select> for user-facing option selection.

Styling

Use Tailwind utilities, the existing cn() helper, shadcn and Radix primitives, Lucide or existing Agent Barn icons, and Sonner for transient notifications. Reuse the semantic variables:

var(--bg)
var(--bg-elev)
var(--bg-soft)
var(--line)
var(--line-strong)
var(--ink)
var(--ink-3)
var(--accent-ink)
var(--ok)
var(--warn)
var(--err)

And the existing utility classes:

af-page
af-card
af-card-hover
af-btn
af-btn-primary
af-btn-danger
af-input

af-page owns dashboard page width and padding. Do not introduce arbitrary page widths that cause dashboard content to shift between routes.

Accessibility

Use semantic elements, real buttons for actions, labels connected to inputs, accessible dialog titles and descriptions, keyboard-operable controls, visible focus styles, meaningful empty and error states, text in addition to color for status, and accessible names that Playwright can select reliably.

Choose the boundary according to who owns the asynchronous work.

A TanStack Query hook error does not automatically reach an App Router error.tsx. If the component owns the query, it also owns the inline error and retry behavior.

Use the shared error UI where it fits:

<AppErrorState
  error={error}
  title="We couldn't load the resources"
  description="The resource list is unavailable right now."
  onRetry={() => {
    void refetch();
  }}
  retryLabel="Retry"
/>

ApiError statuses

Keep page content mounted during follow-up refetches where possible. A search or load-more operation should not replace a usable page with its first-load skeleton.

UI behavior is verified with Playwright. Test responsibilities are divided across four locations:

ui/tests/e2e/
  Specs describe behavior and contain assertions
          │
          ▼
ui/tests/pages/
  Page objects own selectors and user actions
          │
          ▼
ui/tests/pages/data-support/
  Data support owns API interception
          │
          ▼
ui/tests/fixtures/
  Fixtures own reusable static response data

Selector priority

1. Accessible role and name
2. Label or stable visible text
3. An existing test ID, when semantic selection is insufficient

Data support and fixtures

Keep request interception out of specs when a reusable feature support helper can own it. Mock responses must represent the backend wire format — the shared response interceptor then converts their snake_case fields to the frontend’s camelCase schemas. When inspecting a request body at the network boundary, expect the shared client to have already converted frontend fields to snake_case.

Keep endpoint matching precise. A broad wildcard can accidentally intercept list, detail, draft, version, and mutation endpoints with one response.

When an API schema changes, update fixture fields, response interception, request-body expectations, the feature Zod schema, affected page objects, and spec assertions together.

Run Playwright

From the repository root:

make test-ui

For headed or interactive debugging:

cd ui
pnpm test:watch
pnpm test:ui
pnpm test:debug

The local Playwright server runs on port 3003 and uses a separate .next-e2e output directory, so it does not collide with a normal development server. Playwright retains traces on failure and captures failure screenshots.