docs: add navigation design
This commit is contained in:
lussierj committed
1 parent
4656714837
commit
eeb3c7634e
1 file changed
+407
@@ -0,0 +1,407 @@
|
||||
# MinerOps Navigation
|
||||
|
||||
## Status
|
||||
|
||||
This document is the authoritative baseline for the MinerOps application shell,
|
||||
information architecture, navigation model, URL structure, and
|
||||
context-preserving behavior. It follows the shared experience principles in
|
||||
`docs/design/UX_UI_GUIDE.md`. Focused screen documents may refine individual
|
||||
destinations without weakening these rules.
|
||||
|
||||
MinerOps uses the product identity:
|
||||
|
||||
**MinerOps**
|
||||
**Operational Intelligence for Mining**
|
||||
|
||||
The current interface is rendered by the FastAPI backend and includes working
|
||||
pages and legacy paths. MinerOps has not selected a final frontend framework.
|
||||
Routes identified as proposed in this document are information-architecture
|
||||
targets, not claims of implemented screens or commitments to a particular UI
|
||||
technology.
|
||||
|
||||
## Navigation Goals
|
||||
|
||||
Navigation should help an operator move from fleet awareness to a specific
|
||||
object or safe action without first knowing which backend domain owns the data.
|
||||
It must:
|
||||
|
||||
- keep current scope and location obvious;
|
||||
- expose Mine Map and Repair Center prominently;
|
||||
- keep global search available on every authenticated screen;
|
||||
- preserve operational context across summary, inspection, and detail views;
|
||||
- adapt to permission, role, viewport, and input method;
|
||||
- use durable identifiers in object routes; and
|
||||
- remain shallow enough for frequent technician workflows.
|
||||
|
||||
Primary navigation should expose no more than two visible levels. A common
|
||||
workflow should normally take no more than three meaningful interactions from
|
||||
the user's current context. Permission checks, validation, and consequential
|
||||
confirmations do not count as avoidable navigation depth.
|
||||
|
||||
## Information Architecture
|
||||
|
||||
The primary application areas are:
|
||||
|
||||
1. **Dashboard** - fleet summary, prioritized conditions, and next actions.
|
||||
2. **Operations** - active operational workflows.
|
||||
- Repair Center
|
||||
- Scanner
|
||||
3. **Mine Map** - a persistent direct entry into spatial operations. Mine Map is
|
||||
conceptually part of Monitoring but must not be buried in its submenu.
|
||||
4. **Monitoring** - time-based and comparative operational understanding.
|
||||
- Mine Map
|
||||
- Analytics
|
||||
5. **Assets** - durable records and identity.
|
||||
- Miners
|
||||
- Components
|
||||
6. **Reports** - historical and operational reporting.
|
||||
7. **Administration** - users, roles, and system settings.
|
||||
|
||||
On desktop, the direct Mine Map entry should remain visible beside the other
|
||||
primary destinations. Monitoring may also reference Mine Map to communicate its
|
||||
domain relationship, but that secondary reference must not be the only route to
|
||||
the map. Interfaces with limited space should prioritize Dashboard, Mine Map,
|
||||
Repair Center, Miners, and Search.
|
||||
|
||||
## Application Shell
|
||||
|
||||
Every authenticated screen should use a consistent shell containing:
|
||||
|
||||
- persistent primary navigation appropriate to the viewport;
|
||||
- one global search entry point;
|
||||
- an alerts and notifications area;
|
||||
- current user, role, and session controls;
|
||||
- a page title and breadcrumbs when they clarify hierarchy;
|
||||
- page-level actions related to the current scope;
|
||||
- an optional contextual side panel; and
|
||||
- a stable content region that communicates loading and failure state.
|
||||
|
||||
The shell should distinguish global navigation, page navigation, and object
|
||||
actions. An action such as beginning a repair must not look like a destination,
|
||||
and changing a filter must not look like an authoritative data mutation.
|
||||
|
||||
### Page Titles And Breadcrumbs
|
||||
|
||||
The page title names the current destination or durable object. A human-readable
|
||||
Asset ID, serial, or location label may lead the title, while the durable UUID
|
||||
remains available for disambiguation and links.
|
||||
|
||||
Breadcrumbs are useful on deep object and location pages, for example:
|
||||
|
||||
```text
|
||||
Miners / MINER-042 / Repair 8c2... / Timeline
|
||||
Mine Map / Site A / Room 3 / Rack 12
|
||||
```
|
||||
|
||||
Breadcrumbs must not reproduce the entire primary navigation or imply a false
|
||||
parent relationship. On mobile, they may collapse to a labeled back action and
|
||||
current object.
|
||||
|
||||
### Page-Level Actions
|
||||
|
||||
Page-level actions belong near the title or current-object context. Show the
|
||||
most likely authorized action directly and place less common actions in a
|
||||
clearly labeled menu. Actions must follow the permission-aware and explicit
|
||||
command rules in `docs/design/UX_UI_GUIDE.md`.
|
||||
|
||||
### Contextual Side Panel
|
||||
|
||||
A side panel supports lightweight inspection while preserving the underlying
|
||||
map, table, graph, queue, filter, and selection. It may show current status,
|
||||
identity, location, active repair, alert context, or a small set of safe actions.
|
||||
It must not become the only way to perform deep work.
|
||||
|
||||
On narrow screens, a side panel becomes a full-screen sheet with an obvious
|
||||
close or back control. Closing it restores the prior selection and viewport.
|
||||
|
||||
## Proposed Route Model
|
||||
|
||||
The table below defines proposed canonical UI routes. "Implemented path" refers
|
||||
only to an existing server-rendered page in the current repository. An existing
|
||||
API does not by itself make a proposed UI route implemented.
|
||||
|
||||
| Area | Proposed canonical route | Current implementation |
|
||||
| --- | --- | --- |
|
||||
| Dashboard | `/dashboard` | Implemented at `/dashboard` |
|
||||
| Repair queue | `/operations/repairs` | Repair Center foundation implemented at `/repairs` |
|
||||
| Repair detail | `/operations/repairs/{repair_id}` | Proposed; read APIs exist |
|
||||
| Scanner | `/operations/scanner` | Proposed; scanner APIs and operational controls exist |
|
||||
| Mine Map | `/monitoring/map` | Location Map foundation implemented at `/locations` |
|
||||
| Analytics | `/monitoring/analytics` | Proposed |
|
||||
| Miner list | `/assets/miners` | Proposed; inventory APIs exist |
|
||||
| Miner detail | `/assets/miners/{miner_id}` | Detail foundation implemented at `/miners/{miner_id}/detail` |
|
||||
| Component list | `/assets/components` | Proposed; no list UI route |
|
||||
| Component detail | `/assets/components/{component_id}` | Proposed; read API exists |
|
||||
| Reports | `/reports` | Proposed |
|
||||
| Users | `/administration/users` | Account administration foundation implemented at `/accounts` |
|
||||
| Roles | `/administration/roles` | Proposed; role APIs exist |
|
||||
| Settings | `/administration/settings` | Proposed |
|
||||
|
||||
These canonical routes do not require immediate replacement of working paths.
|
||||
When introduced, existing links may remain compatibility routes or redirect to
|
||||
the canonical destination through a deliberate migration. Route aliases must
|
||||
not produce two independent screen implementations.
|
||||
|
||||
Object routes use durable UUIDs for miners, repairs, components, locations, and
|
||||
alerts. The UI displays recognizable Asset IDs, serials, names, and labels, but
|
||||
must not use mutable human identifiers as authoritative route identity.
|
||||
|
||||
### Deep Links
|
||||
|
||||
Direct links should be available for:
|
||||
|
||||
- miner, repair, component, and location detail;
|
||||
- an alert in its relevant object and time context;
|
||||
- a selected site, room, rack, shelf, position, or miner on Mine Map; and
|
||||
- a chart with its scope, comparison, and time range.
|
||||
|
||||
Stable route segments should hold object identity. Query parameters may hold
|
||||
shareable view state such as filters, selected tabs, time range, comparison,
|
||||
map layer, or map viewport. Sensitive or large transient state must not be
|
||||
embedded in a URL.
|
||||
|
||||
Examples of future deep-link shapes are:
|
||||
|
||||
```text
|
||||
/monitoring/map?room_id={room_id}&rack_id={rack_id}&miner_id={miner_id}
|
||||
/monitoring/analytics?scope=room&scope_id={room_id}&range=24h
|
||||
/assets/miners/{miner_id}?tab=history
|
||||
/operations/repairs/{repair_id}?event_id={event_id}
|
||||
```
|
||||
|
||||
These examples define intent, not a final query vocabulary. Each implemented
|
||||
screen must document and test the parameters it accepts.
|
||||
|
||||
## Context-Preserving Navigation
|
||||
|
||||
Navigation from an operational view must preserve the user's place whenever it
|
||||
is safe and practical. Returning from inspection or detail should restore:
|
||||
|
||||
- active filters, sorting, and saved column choices;
|
||||
- selected objects and multi-selection state;
|
||||
- map site, room, layers, position, pan, and zoom;
|
||||
- table scroll or pagination position;
|
||||
- graph scope, comparisons, and time range; and
|
||||
- the originating queue or search query.
|
||||
|
||||
Use a side panel for quick inspection and a full detail page for deep work,
|
||||
multi-step actions, extensive history, or a directly shareable destination.
|
||||
Opening full detail from a map, alert, or queue should retain an explicit return
|
||||
context. Browser back and forward controls must remain meaningful.
|
||||
|
||||
Where useful, filters and view state should be URL-backed so refresh, bookmarks,
|
||||
and shared links restore the same view. Session state may supplement the URL but
|
||||
must not make a copied deep link misleading.
|
||||
|
||||
Mine Map context deserves particular care. Selecting a miner, rack, or room,
|
||||
opening operational context, inspecting an alert, or opening related analytics
|
||||
should retain the current site, spatial selection, layers, pan, zoom, and time
|
||||
context. A miner detail view should provide a practical return to that map state.
|
||||
|
||||
If navigation would discard unsaved form work, warn the user and name what will
|
||||
be lost. A failed validation or permission response must preserve entered data
|
||||
unless retaining it would expose sensitive information.
|
||||
|
||||
## Global Search Navigation
|
||||
|
||||
Global search is available from every authenticated screen and does not require
|
||||
a category choice before entry. It searches only implemented, authorized
|
||||
sources and groups results by type, such as miners, repairs, components,
|
||||
locations, users, and relevant events.
|
||||
|
||||
Each result should support:
|
||||
|
||||
- keyboard focus, movement, selection, and dismissal;
|
||||
- enough identity and context to distinguish similar records;
|
||||
- a quick preview when lightweight inspection is useful; and
|
||||
- an explicit path to full detail.
|
||||
|
||||
A quick preview should preserve the current page beneath a side panel or sheet.
|
||||
Opening full detail should retain the search query as return context where
|
||||
practical. Search cannot expose restricted objects through result text, counts,
|
||||
group labels, previews, suggestions, or timing-dependent behavior.
|
||||
|
||||
Users do not need to know whether an IP address belongs to Inventory,
|
||||
Monitoring, or Discovery before searching for it. No-results behavior must
|
||||
distinguish a successful search with no authorized matches from a search
|
||||
failure, without confirming that restricted records exist.
|
||||
|
||||
## Role-Aware Navigation
|
||||
|
||||
Navigation is permission-derived. Roles describe common experiences but are not
|
||||
a substitute for checking current permissions.
|
||||
|
||||
### Administrator
|
||||
|
||||
Administrators receive the operational navigation plus Administration areas
|
||||
permitted to them. Administrative destinations should not displace Dashboard,
|
||||
Mine Map, Repair Center, or asset lookup.
|
||||
|
||||
### Manager
|
||||
|
||||
Managers typically need the broad operational, monitoring, asset, and reporting
|
||||
structure with the actions their permissions allow. Administration appears only
|
||||
for capabilities explicitly granted to the current user.
|
||||
|
||||
### Technician
|
||||
|
||||
Technician navigation prioritizes Mine Map, Repair Center, Miners, Scanner where
|
||||
authorized, and direct lookup. It should minimize detours through reporting or
|
||||
configuration areas during floor work.
|
||||
|
||||
### Read Only
|
||||
|
||||
Read Only navigation remains coherent rather than looking broken or empty. It
|
||||
provides authorized Dashboard, Mine Map, repair, asset, history, and reporting
|
||||
views while omitting or clearly disabling mutation commands according to
|
||||
context.
|
||||
|
||||
The backend remains authoritative for authentication and permission
|
||||
enforcement. Hiding a link or control is presentation, not security. Navigation
|
||||
labels, badges, counts, previews, alerts, and search must not reveal data or
|
||||
capabilities the current user cannot access.
|
||||
|
||||
When a permission changes during a session, refresh affected navigation and
|
||||
screen capabilities. If the current destination is no longer authorized,
|
||||
explain that access changed and return the user to the nearest coherent allowed
|
||||
destination.
|
||||
|
||||
## Mobile And Tablet Navigation
|
||||
|
||||
On wide screens, MinerOps may use a persistent navigation rail or sidebar. On
|
||||
tablets and phones, use a compact drawer, sheet, or similarly familiar pattern
|
||||
that preserves content space and exposes a clear current location.
|
||||
|
||||
The compact shell must keep quick access to:
|
||||
|
||||
- global search;
|
||||
- alerts and notifications;
|
||||
- Mine Map;
|
||||
- Repair Center;
|
||||
- miner lookup; and
|
||||
- current user and session controls.
|
||||
|
||||
Touch targets must be large enough for work around equipment. Navigation cannot
|
||||
depend on hover, precision pointing, or desktop-only keyboard shortcuts. Side
|
||||
panels become full-screen sheets where necessary, and closing a sheet restores
|
||||
the prior context.
|
||||
|
||||
No critical workflow may exist only on desktop. Mobile layouts may reduce data
|
||||
density or defer secondary columns, but must preserve identity, status,
|
||||
freshness, consequences, validation, and required actions. Navigation and the
|
||||
current screen should remain usable during delayed responses or intermittent
|
||||
mine Wi-Fi without implying that an unconfirmed command succeeded.
|
||||
|
||||
## Operational Bookmarks And Followed Views
|
||||
|
||||
The following are future capabilities and are not Internal Alpha requirements:
|
||||
|
||||
- saved filters and table views;
|
||||
- followed miners, racks, rooms, or queues;
|
||||
- operational bookmarks; and
|
||||
- personalized start views.
|
||||
|
||||
Before implementation, these capabilities need defined ownership, visibility,
|
||||
permission, stale-reference, and deletion behavior. They must store durable
|
||||
object identities and must not bypass current authorization when restored.
|
||||
|
||||
## Internal Alpha Navigation
|
||||
|
||||
The minimum Internal Alpha navigation target is:
|
||||
|
||||
- Dashboard;
|
||||
- Mine Map;
|
||||
- Repair Center;
|
||||
- Miners;
|
||||
- Global Search; and
|
||||
- user and session controls.
|
||||
|
||||
This is a target subset, not a statement that every destination already has its
|
||||
final screen or canonical route. Analytics may initially appear within
|
||||
Dashboard, Mine Map, and Miner Detail before a complete standalone Analytics
|
||||
area exists. Components and Administration may expose only capabilities that
|
||||
are implemented and authorized; their placement must not imply generic
|
||||
component management or unfinished administration features.
|
||||
|
||||
Scanner, Reports, standalone Analytics, broader Components navigation, and
|
||||
additional Administration destinations can enter the shell as their coherent
|
||||
screens become available. Adding a label before its destination works creates a
|
||||
dead end and is not progressive disclosure.
|
||||
|
||||
## Loading And Failure Behavior
|
||||
|
||||
Navigation state must remain understandable while screens load or fail.
|
||||
|
||||
### Session Expiry
|
||||
|
||||
When a session expires, route the user to login rather than rendering an empty
|
||||
application shell. Preserve a safe return destination when practical, but never
|
||||
retain or expose sensitive form values across authentication boundaries.
|
||||
|
||||
### Missing Or Invalid Objects
|
||||
|
||||
If an object no longer exists, show a not-found state with its requested object
|
||||
type and a route back to the originating collection or context. An invalid deep
|
||||
link must not fall through to an unrelated screen or expose parsing details.
|
||||
|
||||
### Permission Changes
|
||||
|
||||
If access is denied or changes during a session, explain that the destination is
|
||||
unavailable and provide the nearest authorized route. Do not disguise a
|
||||
permission failure as an empty dataset when the distinction is safe to disclose.
|
||||
|
||||
### Backend Or Network Failure
|
||||
|
||||
If the backend is unavailable, keep the shell and last safe navigation context
|
||||
where possible, mark displayed data as stale, and offer a bounded retry. Do not
|
||||
show failed data as empty or current. During network interruption, avoid losing
|
||||
the user's selection, filters, unsaved work, or return context.
|
||||
|
||||
### Partial Page Data
|
||||
|
||||
If only part of a page loads, keep successful sections usable and identify each
|
||||
failed section without replacing the entire page with a generic error. Disable
|
||||
actions that lack required authoritative context and explain why.
|
||||
|
||||
## Accessibility
|
||||
|
||||
The application shell must provide:
|
||||
|
||||
- keyboard-accessible primary, secondary, breadcrumb, search, panel, and user
|
||||
navigation;
|
||||
- visible focus in a logical order;
|
||||
- semantic landmarks for navigation, search, main content, and complementary
|
||||
context;
|
||||
- a skip link to main content;
|
||||
- screen-reader labels for icon-only controls, current location, expanded state,
|
||||
alerts, and result counts;
|
||||
- non-hover-only access to every destination and action; and
|
||||
- responsive zoom without clipped navigation or lost controls.
|
||||
|
||||
Opening a drawer, search overlay, or side panel moves focus into it; closing it
|
||||
returns focus to the control that opened it. Dynamic navigation updates should
|
||||
be announced without repeatedly interrupting screen-reader users.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
A compliant MinerOps application shell:
|
||||
|
||||
1. keeps global search accessible from every authenticated screen;
|
||||
2. makes the current destination, scope, and selected object obvious;
|
||||
3. exposes Mine Map and Repair Center prominently;
|
||||
4. keeps primary navigation to no more than two visible levels;
|
||||
5. preserves filters, selection, spatial position, scroll, and time context when
|
||||
moving between inspection and detail;
|
||||
6. supports direct links based on durable object identity;
|
||||
7. adapts destinations and actions to permission and screen size;
|
||||
8. avoids unauthorized information leakage through navigation or search;
|
||||
9. handles loading, partial failure, invalid links, permission changes, and
|
||||
expired sessions explicitly;
|
||||
10. provides a coherent Read Only experience;
|
||||
11. supports keyboard, touch, assistive technology, and responsive zoom; and
|
||||
12. does not discard unsaved work without warning.
|
||||
|
||||
## Final Principle
|
||||
|
||||
Navigation should preserve the operator's mental and operational context while
|
||||
making the next authorized destination or action clear.
|
||||
Reference in new issue
Block a user