How users move between views in oxFlow: primary nav structure, view-to-view transitions, contextual navigation, and breadcrumb conventions.
Related: view-inventory.md · estimator-journey.md
1. Primary navigation
A left sidebar (collapsible) exposes the top-level areas. Always visible when a User is inside the app. The structure is stable — doesn’t shift between roles; items the User can’t access are hidden (not disabled).
┌──────────────────────┐
│ oxFlow │ ← workspace / brand
├──────────────────────┤
│ 🏠 Home │ ← Dashboard
│ │
│ 📋 Tenders │ ← Tenders list
│ │
│ 🧩 Recipes │ ← Recipe Library
│ │
│ 💰 Price Books │ ← Price Books list
│ │
│ ⚠ Anomalies │ ← Cross-Estimate Anomaly Dashboard
│ │
├──────────────────────┤
│ ⚙ Admin │ ← Admin section (Admin-only)
│ · Users & Roles │
│ · Units │
│ · Categorizations │
│ · Flag Catalog │
│ · Modifier Catalog│
│ · Codes │
│ · Reference Rates │
│ · Content Blocks │
│ · Branding │
│ · Integrations │
│ · Audit Log │
└──────────────────────┘
Role-based hiding:
| Role | Sees |
|---|---|
| Admin | All top-level + all Admin sub-items |
| Lead Estimator | Home · Tenders · Recipes · Price Books · Anomalies · Admin (subset: Units · Categorizations · Flag Catalog · Modifier Catalog · Reference Rates · Branding) |
| Estimator | Home · Tenders · Recipes · Price Books · Anomalies |
Admin sub-item visibility reflects the gating in foundation/roles-permissions.md §3.
2. Workspace header
Present above the primary sidebar or at the top of the viewport:
- Workspace switcher (future-proof; single workspace in v1)
- Global search — Tender number, Estimate name, Item description, Resource name, Recipe name, Heading title
- Notifications — lock conflicts, long-running jobs (adjudication imports, file parsing), integration errors
- User menu — profile, sign out
3. Contextual (secondary) navigation
When inside a Tender or an Estimate, a contextual nav strip appears below the header. It surfaces the views that belong to the current object without overloading the primary sidebar.
3.1 Tender context
[Tender ▾ "Acme Refurb"] Overview · Estimates · Program · Settings
- Overview → Tender detail (view 3)
- Estimates → Estimates list (view 4)
- Program → Program linker (view 7) — shown only when a Tender Program is attached or being uploaded
- Settings → a sub-view inside Tender detail for rarer actions (state transitions, archive)
3.2 Estimate context
[Estimate ▾ "Base Case"] Editor · Price Books · Subcontract Packages · Commercials · Publisher · Anomalies
- Editor → Estimate Editor (view 5)
- Price Books → scoped view of Price Books relevant to this Estimate (Project-Specific auto-created books surface here) + Adjudications
- Subcontract Packages → Subcontract Packages list (view 11) + their Adjudications (view 12)
- Commercials → Commercials (view 13)
- Publisher → Publisher (view 14)
- Anomalies → Anomaly Dashboard (view 15), filtered to this Estimate
4. Breadcrumbs
Every view shows a breadcrumb trail back to the root of its chain. Examples:
Home › Tenders › Acme Refurb › Estimates › Base Case › Editor
Home › Tenders › Acme Refurb › Estimates › Base Case › Commercials
Home › Tenders › Acme Refurb › Estimates › Base Case › Subcontract Packages › Electrical
Home › Price Books › In-House Labour Rates Q2 2026
Home › Recipes › Concrete Pump — 8-hour shift
Home › Admin › Codes
Rules:
- Each breadcrumb segment is the entity’s display name + badge where relevant (e.g., state chip on an Estimate).
- Clicking a segment navigates to the corresponding list or detail view.
- Worksheet Editor is a drawer / full-page from within the Estimate Editor, not a breadcrumb level of its own (see §6).
5. View-to-view transition map
Every transition between views in v1. Grouped by source.
From Home
| Action | Target |
|---|---|
| Click active Estimate card | Estimate Editor (view 5) |
| Click Tender with due date | Tender detail (view 3) |
| Click anomaly total | Anomaly Dashboard filtered to my work (view 15) |
| Quick-create Tender | Tender detail in create mode (view 3) |
| Search hit | Target entity’s detail view |
From Tenders list
| Action | Target |
|---|---|
| Click row | Tender detail (view 3) |
| Create Tender | Tender detail in create mode |
From Tender detail
| Action | Target |
|---|---|
| Click Estimate row | Estimate Editor (view 5) |
| Upload / re-upload Program | Program linker (view 7) |
| View parse error | Program linker with error banner |
| Create Estimate | Estimate Editor in create mode |
| State transition → Won / Lost / Archived | Inline confirmation; stays on view 3 with updated state |
From Estimates list (in Tender)
| Action | Target |
|---|---|
| Click row | Estimate Editor (view 5) |
From Estimate Editor
| Action | Target |
|---|---|
| Click Item | Item sidebar (inline); optionally open Worksheet Editor (view 6) |
| Open Worksheet | Worksheet Editor (view 6) — drawer or full-page |
| Open Commercials | Commercials (view 13) |
| Open Publisher | Publisher (view 14) |
| Open Subcontract Packages | Subcontract Packages list (view 11) |
| Open Adjudication (from an Item’s package) | Subcontract Package Adjudication (view 12) |
| Open Price Book Adjudication | Price Book Adjudication (view 10) |
| Run Anomaly Review | Anomaly Dashboard filtered to this Estimate (view 15) |
| Link Program Task on an Item | Program linker (view 7) |
From Worksheet Editor
| Action | Target |
|---|---|
| Close (X / Esc) | Back to Estimate Editor |
| Drag Resource from picker | Stays in view 6 — Resource picker is a sub-panel (modal / side drawer) |
| Drag Recipe from picker | Stays in view 6 — Recipe picker is a sub-panel |
| View anomaly on this Worksheet | Anomaly Dashboard with this Item selected |
| Navigate to parent Item | Stays in view 6 on a different Worksheet (or Estimate Editor if leaving) |
| Fork to new Resource | Worksheet Editor updates; new Resource appears in Project-Specific Price Book (sidebar toast) |
From Price Books list
| Action | Target |
|---|---|
| Click row | Price Book Editor (view 9) |
| Toggle “show system-generated” | Refreshes list in place |
From Price Book Editor
| Action | Target |
|---|---|
| Click source Adjudication badge (system-generated) | Subcontract Package Adjudication (view 12) |
| Archive / unarchive | Stays on view 9 with updated state |
From Price Book Adjudication / Subcontract Package Adjudication
| Action | Target |
|---|---|
| Transfer / Award | Stays on view; status flips to Adjudicated; primary action changes to “Re-open” |
| Re-open | Stays on view; increments round_number; status back to Draft |
| Close | Back to Estimate Editor or Subcontract Packages list |
| Jump to affected Item (from a variance note) | Estimate Editor scrolled to Item with Content Block instance attached |
From Subcontract Packages list
| Action | Target |
|---|---|
| Click row | Subcontract Package Adjudication (view 12) |
| Create Package | Subcontract Package Adjudication (view 12) in Draft state with empty scope |
From Commercials
| Action | Target |
|---|---|
| Jump to Item from Submission Values pane | Estimate Editor scrolled to that Item |
| Open Publisher | Publisher (view 14) |
From Publisher
| Action | Target |
|---|---|
| Publish | Publisher (view 14) with Published banner; side-effect: Estimate → Submitted, Items → Locked; breadcrumb chip updates |
| Download published artifact | Browser download |
| Blocking Item list | Estimate Editor filtered to Unpriced / Plugged Items |
From Anomaly Dashboard
| Action | Target |
|---|---|
| Jump to source | Contextual target — Estimate Editor, Worksheet Editor, Price Book Editor, Program linker |
From Recipe Library
| Action | Target |
|---|---|
| Click row | Recipe Builder (view 17) |
| Create Recipe | Recipe Builder (view 17) in create mode |
From Recipe Builder
| Action | Target |
|---|---|
| Open Worksheet section | Stays on view 17 (Worksheet is embedded, not a separate view) |
| Save / close | Back to Recipe Library |
From Admin views
All admin views navigate to their list view; create / edit uses modals or inline forms. Integrations sub-pages show source-of-truth direction and manual sync triggers.
6. Modal / drawer / full-page conventions
Not every transition is a page change. oxFlow uses three patterns:
| Pattern | When | Examples |
|---|---|---|
| Modal | Short-lived focused task; dismissable without losing context | Create Tender, create Estimate, add Rule, confirm delete, confirm state transition, confirm Lump Sum distribution preview |
| Side drawer | Contextual editing that benefits from parent visibility | Item side-panel from Estimate Editor; Resource picker from Worksheet Editor; Recipe picker from Worksheet Editor |
| Full-page | Substantive work surface | Worksheet Editor, Adjudications, Commercials, Publisher, Recipe Builder, Anomaly Dashboard |
Worksheet Editor specifically may open as a full-page (primary mode) with an option to collapse into a drawer next to the Estimate Editor for rapid jumping between Items. Prototype explores both.
7. Deep-linking
Every view is URL-addressable. Examples:
/tenders
/tenders/:tenderId
/tenders/:tenderId/estimates/:estimateId
/tenders/:tenderId/estimates/:estimateId/worksheet/:itemId
/tenders/:tenderId/estimates/:estimateId/commercials
/tenders/:tenderId/estimates/:estimateId/publisher
/tenders/:tenderId/estimates/:estimateId/adjudications/price-book/:pbaId
/tenders/:tenderId/estimates/:estimateId/subcontract-packages/:packageId/adjudications/:spaId
/price-books
/price-books/:priceBookId
/recipes
/recipes/:recipeId
/anomalies?estimate=:estimateId
/admin/users
/admin/codes
/admin/audit
Lock state, selection, and filter parameters live in query strings so URLs can be shared or bookmarked.
8. Empty, error, and loading states
Conventions that apply across views:
- Empty — actionable prompts (e.g., “No Estimates yet. Create your first Estimate.” with a CTA button)
- Error — inline banners with a retry action where applicable. Parse failures and integration errors link to the Integrations admin page (for Admins) or an explanation + retry (for non-Admins).
- Loading — skeleton rows in tables, spinner for short work, progress bar for known-long work (adjudication import, file parse, Publisher export)
- Locked — Items / Estimates in Submitted / Archived states render with a padlock badge and read-only form fields; actions that would mutate state are hidden or disabled with tooltip explanation
9. Role-based entry points
Where each Role typically begins the day. Drives Home / Dashboard content and default routes post-login.
| Role | Typical entry point |
|---|---|
| Admin | Home → Admin (Integrations / Users) or any Tender needing attention |
| Lead Estimator | Home → the Estimate they’re leading · Tenders list |
| Estimator | Home → the Estimate they’re working on (surfaced via “recently edited” or direct assignment) · Recipes (for curation) |
10. Concurrency affordances
Per-Item locks are visible across navigation:
- Estimate Editor rows — “editing: [User]” inline indicator on an Item being edited by another User
- Worksheet Editor — banner “This Worksheet is currently being edited by [User]. Read-only view.” with a “Take over” action (Admin) and “Notify me when available” (others)
- Anomaly Dashboard — flag resolution actions are disabled with explanation if the Item is locked by another User