docs: add current web dashboard guide
This commit is contained in:
Jason Woltje
@@ -0,0 +1,276 @@
|
||||
---
|
||||
title: Mosaic web dashboard
|
||||
type: guide
|
||||
audience: user
|
||||
status: current
|
||||
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).
|
||||
Reference in New Issue
Block a user