17 KiB
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:
- Dashboard - fleet summary, prioritized conditions, and next actions.
- Operations - active operational workflows.
- Repair Center
- Scanner
- Mine Map - a persistent direct entry into spatial operations. Mine Map is conceptually part of Monitoring but must not be buried in its submenu.
- Monitoring - time-based and comparative operational understanding.
- Mine Map
- Analytics
- Assets - durable records and identity.
- Miners
- Components
- Reports - historical and operational reporting.
- 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:
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:
/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:
- keeps global search accessible from every authenticated screen;
- makes the current destination, scope, and selected object obvious;
- exposes Mine Map and Repair Center prominently;
- keeps primary navigation to no more than two visible levels;
- preserves filters, selection, spatial position, scroll, and time context when moving between inspection and detail;
- supports direct links based on durable object identity;
- adapts destinations and actions to permission and screen size;
- avoids unauthorized information leakage through navigation or search;
- handles loading, partial failure, invalid links, permission changes, and expired sessions explicitly;
- provides a coherent Read Only experience;
- supports keyboard, touch, assistive technology, and responsive zoom; and
- 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.