---
description: UI shell, route structure, auth flow, API access, and template customization points for the ui/ surface
paths:
  - ui/**
---
<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->


# UI Features

**Status:** Stable

## App Shell Overview

The template frontend is a React 19 + TanStack Router app that composes a local dashboard shell with published System modules from `@elevasis/ui`.

The main join points are:

- `ui/src/main.tsx` -- boots the app with `ElevasisUIProvider`, query client, theme config, WorkOS AuthKit, notifications, and the generated route tree
- `ui/src/routes/__root.tsx` -- composes the authenticated shell with `ElevasisSystemsProvider`, published System modules, app-local dashboard nav, shell runtime dependencies, and `SystemShell`
- `ui/src/config/nav-items.ts` -- keeps the host-local dashboard entry separate from the published feature manifests
- `core/config/organization-model.ts` -- is the template's semantic source of truth, adapting `@elevasis/core/organization-model` into the preserved branding, dashboard label, quick-access, System labels, resource descriptors, and shell helpers

Published System modules mounted by the template shell:

- `lead-gen`
- `crm`
- `delivery` at `/projects`
- `operations`
- `monitoring`
- `settings`

Important distinction:

- shared modules gate on current org-model System keys such as `sales.lead-gen` and `projects`
- template routes and local nav may still use legacy aliases such as `crm`, `lead-gen`, and `projects`
- `core/config/organization-model.ts` and `ui/src/lib/hooks/useFeatureAccess.ts` are the bridge between those two vocabularies

Dashboard remains a host-local route at `/`, not a shared feature manifest.

This template should be treated as the downstream reference implementation for this composition:

- `core/config/organization-model.ts` owns the organization/runtime semantics
- `ui/src/config/nav-items.ts` preserves the host-local dashboard entry instead of pushing that concern into shared manifests
- `ui/src/routes/__root.tsx` threads `canonicalOrganizationModel` from `@core/config/organization-model` into `ElevasisSystemsProvider` so the shared shell/runtime uses the same semantic source of truth as the local template helpers
- host-local customizations still stay local: dashboard remains app-owned nav, branding stays in app config, and quick-access/dashboard UX stays in the template app

## Auth and Initialization

The app uses WorkOS AuthKit through `ElevasisUIProvider`. Authentication is enforced by the local `ProtectedRoute` wrapper in `ui/src/features/auth/ProtectedRoute.tsx`.

**Sign-in flow:**

1. Unauthenticated user hits a protected route -- `ProtectedRoute` redirects to `/login?returnTo=<path>`
2. `/login` renders a sign-in card; user clicks Sign In, triggering `signIn({ returnTo })` from `useAuth()`
3. User authenticates on the WorkOS-hosted sign-in page
4. WorkOS redirects back to `/auth-redirect` -- `ui/src/routes/auth-redirect.tsx` waits for auth to complete, then navigates to the requested path or `/`
5. User lands on the home page, fully authenticated

**Route protection:**

Wrap protected route components with the local `ProtectedRoute` from `@/features/auth`, which adds the full-screen loader and delegates to the shared guard from `@elevasis/ui/auth`:

```tsx
import { ProtectedRoute } from '@/features/auth'

function HomePageGuarded() {
  return (
    <ProtectedRoute>
      <HomePage />
    </ProtectedRoute>
  )
}
```

**Initialization state:**

Use `useInitialization()` from `@elevasis/ui/initialization` anywhere inside the app to read aggregated auth + org readiness:

```ts
const { allReady, userReady, isInitializing, error, retry, profile } = useInitialization()
```

**Organization context:**

Use `useOrganization()` from `@elevasis/ui/organization` to access org-scoped IDs and memberships:

```ts
const { currentWorkOSOrganizationId, currentSupabaseOrganizationId, memberships, switchOrganization } = useOrganization()
```

## API and Streaming

Use `useApiClient()` from `@/lib/hooks/useApiClient` in route components and feature hooks:

```ts
const { apiRequest, isOrganizationReady } = useApiClient()
const data = await apiRequest('/executions', { method: 'GET' })
```

The template also re-exports `useApiClientContext()` and the shared API client types from `@/lib/hooks/useApiClient`.

For real-time updates, feature surfaces use the local singleton wrapper:

```ts
import { sseConnectionManager } from '@/lib/sse/SSEConnectionManager'
```

**WorkOS config:**

WorkOS `clientId`, `redirectUri`, and `signoutUri` are resolved in `ui/src/config/workos.ts` from `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, `VITE_WORKOS_SIGNOUT_URI`, and `VITE_APP_ORIGIN`, with localhost fallbacks so the template runs locally without production env vars. For deployed apps, set the production env vars in the hosting provider and allow the exact redirect and sign-out URLs in the WorkOS application dashboard:

- Redirect URI: `https://your-production-domain/auth-redirect`
- Sign-out redirect: `https://your-production-domain/login`
- Configure CORS origin: `https://your-production-domain`; required for browser AuthKit calls to `api.workos.com`
- App homepage origin: `https://your-production-domain`

The dev server runs on port `4300` with Vite `strictPort: true`, so a second `pnpm -C ui dev` on the same machine fails fast instead of drifting.

The API URL is centralized in `ui/src/lib/constants/api.ts`. In the current template it is hard-coded to `https://api.elevasis.io`, so if the bootstrap is repointed to another API target, that file is the source of truth.

## Route Structure

Current top-level app sections:

- `/` -- host-local dashboard entrypoint with quick links derived from `organizationModel.navigation.quickAccessSurfaceIds`
- `/lead-gen/*` -- lead generation pages (`lists`, `companies`, `contacts`)
- `/crm/*` -- CRM overview, pipeline, and deals
- `/projects/*` -- delivery feature pages (projects, milestones, tasks, notes)
- `/operations/*` -- operations overview, resources, command queue, command view, sessions, task scheduler
- `/monitoring/*` -- execution logs, execution health, activity log, cost analytics, notifications
- `/settings/*` -- account, organization, credentials, API keys, deployments, webhooks, and appearance
- `/login` and `/auth-redirect` -- auth entry/callback routes

Section guards currently follow this pattern:

- `ProtectedRoute` for all authenticated sections
- `SystemGuard` on sections that should hard-stop when a System is disabled: `crm`, `lead-gen`, `projects`, `operations`, and `monitoring`
- provider-level shell gating for shared System nav and sub-shell behavior

The app shell in `__root.tsx` derives visible nav from `shellModel.systems` and `getSidebarLinks()`, filters admin-only entries locally using the signed-in profile, and passes `canonicalOrganizationModel` into `ElevasisSystemsProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same organization-model semantic source.

## Dashboard and Feature Areas

**Dashboard**

`ui/src/features/dashboard/components/Dashboard.tsx` is intentionally lightweight. It acts as the host-owned landing page and renders quick access cards for the most important organization surfaces instead of duplicating the shared operations overview.

**Operations**

The operations area is the richest shared shell in the template. It includes:

- resource inventory and detail pages
- command queue and command view
- sessions screens
- the shared operations overview at `/operations/`

**Monitoring**

Monitoring is scaffolded as a shared feature area with route files for:

- activity log
- cost analytics
- execution health
- execution logs
- notifications

## Customization Points

The main template-owned customization surfaces are:

- `ui/src/config/app-config.ts` -- brand name, logos, and app version
- `ui/src/config/theme.ts` -- theme presets and defaults
- `ui/src/config/background.tsx` -- shared background treatment
- `ui/src/config/loader.tsx` -- global loader element
- `ui/src/config/nav-items.ts` -- app-local nav entries, including the preserved dashboard/home entry
- `core/config/organization-model.ts` -- product labels, System availability, resource descriptors, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
- `ui/src/config/README.md` -- the deeper guide for those config files

## Customizing System Sidebars

The template demonstrates one override pattern in `ui/src/routes/__root.tsx`: it extends `CRM_ITEMS` with a template-owned Reports link and replaces `crmManifest` with `customCrmManifest` in the System module array. The backing route lives at `ui/src/routes/crm/reports.tsx` -- delete both the nav item and the route if you don't need them.

Two customization layers are available for every shared System sidebar:

1. **Nav-item shortcut (`items` prop)** -- when you just need to swap or extend the nav array, spread the published items constant and pass the result to `*SidebarMiddle`. The template's CRM customization uses this path.

   ```tsx
   import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
   import type { NavItem } from '@elevasis/ui/layout'

   const customItems: NavItem[] = [...CRM_ITEMS, { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false }]
   const CustomCrmSidebar = () => <CrmSidebar><CrmSidebarMiddle items={customItems} /></CrmSidebar>
   const customCrmManifest = { ...crmManifest, sidebar: CustomCrmSidebar }
   ```

2. **Compose-primitives (structural changes)** -- when you need to inject panels, reorder sections, or add a new section, drop down to `CrmSidebarTop` + `SubshellNavList` + `SubshellSidebarSection` + published panels (`MyTasksPanel`, `QuickCreateActions`) and compose your own Middle.

`manifest.sidebar` accepts any component, so arbitrary customization is always available. The `items` prop is an abstraction barrier for the common case, not a limit.

See `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree, page-wrapping pattern, and delivery's three-section variant. For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`. For broader lead-gen extension work across pages, hooks, list/member state, artifacts, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`. See `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `SystemModule`, CRM platform primitives, Lead Gen platform primitives, and related TypeScript shapes.

For CRM deal action buttons, read `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before changing `crmActions`, `DealDetailPage`, `DealDrawer`, or custom workflow buttons. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.

## Notes

- `ui/src/routeTree.gen.ts` is generated by TanStack Router tooling. Do not hand-edit it.
- The template ships a broad route surface so downstream projects can trim or reshape features without having to re-derive the shared shell contract from scratch.
- For package-export discovery, glob `node_modules/@elevasis/sdk/reference/` or `node_modules/@repo/ui/dist/` for the current SDK/UI package surface.
