Information Architecture

Status: v1.0 · Owner: Design Lead + Frontend Lead · Gate input: G1, G2 Defines the navigation model, the full screen inventory, the URL map, and the drill-through graph. The route map here is the contract for the Next.js App Router structure in apps/web/app/ and must stay in sync with the per-phase API surfaces.

Atlas uses a persistent left sidebar (desktop) / bottom nav (mobile) with a global top bar. Navigation is permission-driven — nav.config.ts filters items by the user's permissions (Phase_2.md §5.6), so two users never see entries they cannot use.

Grouped by mental model, not by engineering phase:

┌─ ATLAS ──────────────────┐
│  ⌂  Home / Dashboards    │   ← landing; user + tenant dashboards
│                          │
│  OPERATE                 │
│   ▸ Work Orders          │
│   ▸ Maintenance (cal)    │
│   ▸ Approvals (inbox)    │
│   ▸ Inspections          │
│                          │
│  ASSETS & SPACE          │
│   ▸ Assets               │
│   ▸ Locations / Plans    │
│   ▸ Systems              │
│                          │
│  DATA                    │
│   ▸ Telemetry            │
│   ▸ Connectors/Gateways  │
│   ▸ Imports              │
│   ▸ Tags / Ontology      │
│                          │
│  INTELLIGENCE            │
│   ▸ AI Chat              │
│   ▸ Workflows            │
│   ▸ Reports              │
│                          │
│  ─────────────           │
│  🔍 Search   ⌘K Palette  │
├──────────────────────────┤
│  ⚙ Admin (if permitted)  │
│   Users · Roles · Keys   │
│   Audit · Settings · AI  │
└──────────────────────────┘

The sidebar is collapsible to icons-only. Group headers (OPERATE, ASSETS & SPACE, etc.) are non-clickable labels. Admin is a separate cluster, only visible with admin permissions.

Five slots, optimised for the field personas:

  ⌂ Home    ✓ Tasks    📥 Inbox    🔍 Search    👤 Me

Tasks = the technician's work-order queue (J1). Inbox = approvals (J2/J4). Everything else is reachable via Search and the Me/More sheet. Desktop-only modes (TV, War Room, dashboard editor) show a "best on desktop" message on mobile.

1.3 Global top bar (all viewports)

[≡ collapse]   [Tenant ▾]            [🔍 global search ⌘K]            [🔔]  [◐ theme]  [👤 user ▾]

Tenant switcher — only if the user belongs to >1 tenant.
Global search / Command palette (⌘K) — jump to any page, search any record, run actions.
Notifications drawer — in-app feed + unread count.
Theme toggle — light / dark / brand (+ user accent/density in user menu).
User menu — profile, settings, sessions, sign out.

2. Information hierarchy pattern (applies to every module)

Every module follows the same List → Detail → Drawer → Edit progression so users learn the pattern once:

LIST (table or board)
  ├─ filters, saved views, search, bulk actions
  ├─ row click ──▶ DETAIL (full page)
  │                 ├─ summary header (KPIs, status, primary action)
  │                 ├─ tabs: Overview · History · Related · Documents · Telemetry
  │                 ├─ related-entity links ──▶ (drill-through to other modules)
  │                 └─ Edit ──▶ EDIT (form) or inline DRAWER edit
  └─ secondary actions ──▶ DRAWER (quick view / quick action without leaving list)

This is the progressive-disclosure principle from 00_README.md made concrete. Power is always one level deeper than the calm default.

3. Screen inventory & URL map

Routes live under the authenticated (app) route group. :id denotes a record id. Phase column = when the screen ships.

3.1 Shell & account (P2)

Route	Screen	Persona	Phase
`/`	Home / default dashboard	All	P2→P5
`/login`, `/mfa`, `/accept-invite`, `/reset`	Auth flows	All	P2
`/settings/profile`	Profile	All	P2
`/settings/sessions`	Active sessions + revoke	All	P2
`/settings/notifications`	Notification prefs	All	P4
`/settings/appearance`	Theme / accent / density	All	P2/P5

3.2 Admin (P2/P3/P6) — visible with admin permissions

Route	Screen	Phase
`/admin/users`	Users list + invite + edit	P2
`/admin/roles`	Roles + permission matrix	P2
`/admin/api-keys`	API keys (create/revoke, shown once)	P2
`/admin/audit`	Audit log (filterable)	P2
`/admin/settings`	Tenant settings + branding	P2
`/admin/connectors`	Connectors + gateways + health	P3
`/admin/imports`	Import wizards + jobs	P3
`/admin/tags`	Tags / ontology	P3
`/admin/reconciliation`	Reconciliation reports	P3
`/admin/ai`	AI provider, budgets, no-egress	P6

3.3 Operate (P4/P7)

Route	Screen	Phase
`/work-orders`	WO list (table ⇄ Kanban)	P4
`/work-orders/new`	Create WO	P4
`/work-orders/:id`	WO detail (timeline, checklist, costs)	P4
`/work-orders/calendar`	Maintenance calendar	P4
`/maintenance-plans`	Planned maintenance (RRULE)	P4
`/inbox`	Approvals inbox	P7
`/inspections/:id`	Mobile inspection execution	P8

3.4 Assets & space (P4)

Route	Screen	Phase
`/assets`	Asset list + saved views	P4
`/assets/:id`	Asset detail (overview/telemetry/WOs/docs/history)	P4
`/locations`	Location hierarchy	P4
`/locations/:id`	Location + ceiling-plan overlay	P4
`/systems`	Systems hierarchy	P4

3.5 Data (P3)

Route	Screen	Phase
`/telemetry`	Telemetry explorer (query + live)	P3
`/documents`	Document library	P4

3.6 Intelligence (P5/P6/P7) & developer (P2)

Route	Screen	Phase
`/dashboards`	Dashboards list + templates	P5
`/dashboards/:id`	Dashboard view	P5
`/dashboards/:id/edit`	Dashboard editor (palette/canvas/inspector)	P5
`/dashboards/:id/tv`	TV mode (chrome-free)	P5
`/war-room`	War Room multi-pane	P5
`/ai`	AI chat (threaded, citations)	P6
`/workflows`	Workflow list	P7
`/workflows/:id/edit`	Workflow designer canvas	P7
`/workflow-runs/:id`	Run timeline + replay	P7
`/reports`	Report templates + runs	P4
`/search`	Global search results	P4
`/api/docs`, `/api/docs/scalar`	Developer portal	P2

4. Drill-through graph (the connective tissue)

The product's value is that everything links to everything. These drill paths are required, not optional:

KPI card  ──────────────▶  underlying record list (filtered)
Work Order ──────────────▶  Asset · Location · Assignee · Workflow that owns it · Documents
Asset      ──────────────▶  Telemetry (live) · Work Orders · Location on plan · Documents · History
Location   ──────────────▶  Ceiling plan → marker → Asset detail
Alert      ──────────────▶  DataPoint · Asset · AI explanation · Workflow run · resulting WO
Telemetry  ──────────────▶  DataPoint · Asset · add-to-dashboard
AI answer  ──────────────▶  cited source (document / record / help)
Workflow run ────────────▶  each node's input/output · created entities · approver
Dashboard widget value ──▶  its canonical record (the universal click-through rule)

Universal rule: any value rendered from a record is clickable to that record. No "look but can't touch" numbers.

5. Breadcrumbs, deep-linking & state

Breadcrumbs reflect the IA hierarchy, e.g. Assets / Chiller CH-01 / Telemetry. Every breadcrumb segment is a link.
Deep-linkable state: list filters, saved views, selected tab, and time ranges live in the URL query so a view can be shared/bookmarked (and embedded for dashboards).
Back is sacred: drawers and modals don't break the back button; closing a drawer returns to list state intact.
Tenant in context, not in URL: tenantId comes from session, never the path (multi-tenancy security model, Phase_1.md §5.3). Switching tenant resets navigation to that tenant's Home.

6. Empty-state IA (first-run experience)

A new tenant must never see a blank product (J3). Each top-level surface ships a designed empty state with a clear next action:

Surface	Empty state CTA
Home	"Create your first dashboard" / start from a template
Work Orders	"Create a work order" + import history
Assets	"Import your asset ledger" (→ wizard)
Connectors	"Connect a gateway" (→ guided connect)
Workflows	"Start from a template"
AI Chat	Suggested starter prompts

Empty states are first-class screens in the design system (UX_patterns.md State Matrix), not throwaway placeholders.

7. Responsive IA collapse rules

Breakpoint	Sidebar	Top bar	Tables	Dashboards
`≥1280` (desktop)	Full sidebar	Full	Full table	Grid as authored
`768–1279` (tablet)	Collapsed-to-icons	Full	Table, fewer columns	Grid, fewer columns
`<768` (mobile)	Hidden → bottom nav	Compact	Card list (no h-scroll)	Vertical stack by `layout.y`

TV and War Room are explicitly desktop/kiosk only and surface a friendly redirect on mobile (Phase_8.md §6.3).