diff --git a/docs/design/NAVIGATION.md b/docs/design/NAVIGATION.md new file mode 100644 index 0000000..ae5e765 --- /dev/null +++ b/docs/design/NAVIGATION.md @@ -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.