stack/docs/USER-GUIDE/product/web-dashboard.md

title, type, audience, status, source_of_truth

title	type	audience	status	source_of_truth
Mosaic web dashboard	guide	user	current	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 and SSO provider runbook.