---
kind: guide
status: active
title: Mosaic web dashboard
audience: user
source_of_truth: false
---

# Mosaic Web Dashboard

This page documents the current Next.js dashboard: its routes, navigation, visible
views, and the chat persistence behavior supported by the checked-in web and gateway
implementation.

> **Current UI boundary:** Projects and tasks can be displayed in the dashboard, but
> the current dashboard does not provide **New Project** or **New Task** controls.
> Those entities can be created through authenticated gateway API clients; that API
> surface is separate from the views described here.

## Access and routes

The dashboard uses the gateway session. Dashboard routes are protected by the web
`AuthGuard`; the admin route also requires the `admin` role.

| Path                        | Access          | Current behavior                                                                                                                                                                                    |
| --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/`                         | Any             | Redirects to `/chat`. A signed-out visitor is then redirected to `/login`.                                                                                                                          |
| `/login`                    | Signed out      | Email/password sign-in, plus buttons for configured SSO providers. Successful sign-in returns to `/chat`.                                                                                           |
| `/register`                 | Signed out      | Creates an account with name, email, and password, then returns to `/chat`.                                                                                                                         |
| `/auth/provider/[provider]` | SSO handoff     | Looks up the requested provider and starts an OIDC sign-in when that provider is configured and supports OIDC. Unknown, disabled, or incompatible providers show an error and a link back to login. |
| `/chat`                     | Signed in       | Conversation list and streamed assistant chat.                                                                                                                                                      |
| `/projects`                 | Signed in       | Project cards and the Active Mission status section.                                                                                                                                                |
| `/projects/[id]`            | Signed in       | Project detail view with overview, tasks, missions, and an optional read-only PRD tab.                                                                                                              |
| `/tasks`                    | Signed in       | Task data in Kanban or list view.                                                                                                                                                                   |
| `/settings`                 | Signed in       | Profile, appearance, notifications, and provider tabs.                                                                                                                                              |
| `/admin`                    | Signed-in admin | User Management and System Health tabs. Non-admin users are redirected away from the admin page.                                                                                                    |

Settings and admin tabs are client-side tabs; changing a tab does not change the URL.

## Dashboard navigation

The **Workspace** sidebar contains these links, in order:

1. **Chat** — `/chat`
2. **Tasks** — `/tasks`
3. **Projects** — `/projects`
4. **Settings** — `/settings`
5. **Admin** — `/admin`

The active link is highlighted, including the parent link when viewing a project
such as `/projects/<id>`. The Admin link is rendered in the shared sidebar, but the
page itself is still restricted to administrators.

The top bar provides:

- a sidebar toggle (collapse/expand on desktop; open/close an overlay on mobile),
- the light/dark theme toggle,
- the signed-in user's name, and
- **Sign out**, which returns to `/login`.

The applied global theme is stored in browser local storage under `mosaic-theme`.

## Chat

### Starting and managing conversations

Open `/chat` and either select a conversation or choose **Start new conversation**
in the empty state. The conversation sidebar also has **New conversation**. Creating
one calls the gateway and gives the conversation a server-side ID before the first
message is sent.

The sidebar currently supports:

- searching conversation titles,
- selecting a conversation,
- renaming a conversation inline (Enter or leaving the field commits the new title),
- deleting a conversation after confirmation, and
- grouping conversations by project when project data is available.

Archived conversations are filtered out of the sidebar. The current dashboard does
not expose archive/restore controls.

If no conversation is selected when a message is sent, the dashboard creates one
automatically. A new conversation is titled from the first 60 characters of the
first message; an empty placeholder conversation is similarly retitled after its
first message. The active conversation is held in page state, not in the URL: the
route remains `/chat` rather than changing to `/chat/<id>`. After a refresh, select
the stored conversation again from the sidebar.

### Sending and streaming

The chat composer provides:

- a model selector populated from available gateway providers and models,
- a multiline message field,
- character and approximate token counts, and
- a **Send** button.

Use **Cmd/Ctrl+Enter** to send. The composer is disabled while a response is
streaming. The interface displays a **Stop** control during streaming, but the
current `ChatPage` does not pass a stop handler, so cancellation is not a reliable
current dashboard action.

Assistant and user messages render Markdown. Assistant messages can show model and
token metadata when it is present in the returned message, and rendered user/assistant
messages have a copy control.

### What is persisted

Assistant replies are not page-only or memory-only. The current flow is:

1. The browser creates or selects a conversation and optimistically displays the
   user's message.
2. The browser submits the user message to the gateway conversation-message API and
   sends the turn over the authenticated `/chat` WebSocket namespace.
3. The gateway streams the assistant response to the page. At `agent_end`, it saves
   non-empty assistant text to the conversation with model, provider, tool-call, and
   token-usage metadata when available.
4. Selecting the conversation later loads `/api/conversations/<id>/messages`, so
   stored user and assistant messages are shown again. When the gateway has to create
   or resume the agent session for that conversation, it also loads stored conversation
   history as context.

The live page appends the completed response as soon as the stream ends; the gateway
persistence write is asynchronous. Therefore a persistence error can leave a reply
visible in the current page while it is unavailable after a later reload. The gateway
redacts sensitive content before emitting and storing assistant text.

## Projects and missions

### Project list: `/projects`

The project page loads the signed-in user's projects and shows either:

- project cards with name, status, description, and creation date, or
- **No projects yet** with the message that projects appear when created through the
  gateway API.

The page also shows **Active Mission**. It reports the mission ID, phase, task
completion count, and status when coordination data is available; otherwise it
shows **No active mission detected**.

There is no New Project button or project form on this page. The gateway has
project CRUD endpoints, but this dashboard page currently reads project data only.

### Project detail: `/projects/<id>`

A project detail page shows its name, status, description, created/updated dates,
and task summary counts for total, done, in progress, and blocked tasks. Its tabs
are:

- **Overview** — up to five recently updated tasks, a mission summary, and non-empty
  project metadata.
- **Tasks (`n`)** — task status filters and clickable task rows.
- **Missions (`n`)** — a status-ordered mission timeline.
- **PRD** — present only when project metadata contains non-empty `prd` or
  `prdContent` text; the content is displayed read-only.

Selecting a task from the project detail Tasks tab opens a detail dialog with its
status, priority, description, assignee, due date, timestamps, tags, pull-request
links, and notes when those fields exist. The dialog can be closed with its close
button, the backdrop, or Escape. The dashboard does not provide project or task
edit controls in this view.

## Tasks

Open `/tasks` to load the tasks visible to the signed-in user. The default view is
**Kanban**; a toggle switches to **List**.

- Kanban columns are **Not Started**, **In Progress**, **Blocked**, and **Done**.
- Kanban cards show title, priority, optional description, status, and due date.
- List view shows title, status, priority, and due date.
- The supported task status set also includes `cancelled`; it is not a Kanban
  column, but a returned cancelled task can appear in List view.

The top-level Tasks page has no New Task button, form, or working task edit dialog.
Clicking a task in that page does not open the project-detail dialog. The gateway
supports authenticated task CRUD separately, while this dashboard page currently
reads and presents task data.

## Settings

Open `/settings`. The page has four tabs and opens on **Profile**.

### Profile

- **Display Name** can be edited.
- **Email** is displayed but disabled; the page says it cannot be changed there.
- **Avatar URL** can be edited.
- **Save changes** sends the profile update through BetterAuth and reports saving,
  saved, or an error state.

### Appearance

The tab presents **System**, **Light**, and **Dark** theme choices, a **Collapse
sidebar by default** switch, and a **Default Model** text field. **Save changes**
saves these as user preferences.

Current implementation limits are worth noting: the shared sidebar provider starts
expanded and does not read `ui.sidebar_collapsed` on page load; the global applied
theme is controlled by the top-bar theme toggle; and the chat page initially selects
the first available provider model rather than reading `ui.default_model` itself.
Do not treat these preference fields as proof that those defaults are applied across
all dashboard sessions.

### Notifications

The tab presents and saves three email preferences:

- **Agent task completed** — initially off,
- **Mentions** — initially on, and
- **Weekly digest** — initially off.

### Providers

The Providers tab contains SSO discovery and LLM provider discovery/testing areas:

- **SSO Providers** shows configured providers and their protocols, callback path,
  team-sync claim, SAML fallback, and warnings when supplied by the gateway. It does
  not configure SSO from the dashboard.
- **LLM Providers** shows configured providers as Active or Inactive. A provider can
  be tested for reachability; the result may include latency, an error, and the
  number of discovered models. Expanding a provider shows model capabilities,
  context size, cost, and the default-model marker.

When no LLM providers are configured, the page displays setup guidance mentioning
`OLLAMA_BASE_URL` and `MOSAIC_CUSTOM_PROVIDERS`. Provider credentials and provider
configuration are not editable in this dashboard tab.

## Admin panel

The `/admin` page is wrapped in an admin-role guard. It opens on **User Management**
and provides **System Health** as the second tab.

### User Management

The page loads the user list and provides:

- a user count,
- **+ New User**, with name, email, password, and `member`/`admin` role fields,
- role promotion/demotion,
- ban/unban,
- deletion after confirmation, and
- a retry action when loading fails.

The table shows name/email, role, active or banned status, creation date, and
available actions.

### System Health

The health tab loads the gateway's overall `ok` or `degraded` status and provides a
**Refresh** action. Its cards cover:

- PostgreSQL database status and latency/error,
- Valkey cache status and latency/error,
- active agent-session count, and
- configured LLM providers and model counts.

## Evidence used for this page

The behavior above was checked against the current implementation and focused tests,
not copied forward as-is from the historical mixed guide. The main evidence files
are:

- `apps/web/src/app/(dashboard)/` route pages and `apps/web/src/app/page.tsx`,
- `apps/web/src/components/layout/`, `apps/web/src/components/chat/`,
  `apps/web/src/components/projects/`, and `apps/web/src/components/tasks/`,
- `apps/web/e2e/navigation.spec.ts`, `chat.spec.ts`, `projects.spec.ts`,
  `settings.spec.ts`, and `admin.spec.ts`,
- `apps/gateway/src/chat/chat.gateway.ts` and
  `apps/gateway/src/__tests__/conversation-persistence.test.ts`,
- `apps/gateway/src/chat/chat.gateway-redaction.spec.ts`, and
- the authenticated gateway controllers under `apps/gateway/src/conversations/`,
  `projects/`, `tasks/`, and `admin/`.

Related: [User Guide index](../README.md) and [SSO provider runbook](../../ADMIN-GUIDE/security/sso-providers.md).
