minerops/docs/design/NAVIGATION.md

# 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.