diff --git a/ui-docs/Frontend-implementation-phase-1.md b/ui-docs/Frontend-implementation-phase-1.md new file mode 100644 index 0000000..32675da --- /dev/null +++ b/ui-docs/Frontend-implementation-phase-1.md @@ -0,0 +1,1723 @@ +# MDU UI - Frontend Implementation Plan + +## 1. Purpose + +This document defines how to implement the mock MDU UI frontend from the completed design documents. + +It is the bridge between design planning and code generation. + +Source design documents: + +```text +docs/ + mdu-ui-spec.md + workflows.md + figma-navigation-model.md + screen-inventory.md + screen-definitions.md + layout-system.md + wireframe-plan.md +``` + +This document answers: + +```text +How should the MDU UI be built in code? +Which stack should be used? +How should folders, routes, stores, mock APIs, RBAC, and components be organized? +How should an LLM generate code safely module by module? +``` + +Use this document as the main guide for frontend code generation. + +--- + +## 2. Target Stack + +Use the following frontend stack: + +```text +Next.js latest +TypeScript +Tailwind CSS +shadcn/ui +React Flow +TanStack Query +Zustand +``` + +## 2.1 Stack responsibilities + +| Tool | Responsibility | +|---|---| +| Next.js latest | App Router, routing, layouts, pages, frontend app structure. | +| TypeScript | Strict typing for hierarchy, RBAC, devices, billing, users, configs, and states. | +| Tailwind CSS | Utility-first styling and responsive layout. | +| shadcn/ui | Base UI components: buttons, cards, dialogs, tables, tabs, inputs, badges, sheets. | +| React Flow | Topology canvas and device connectivity graph. | +| TanStack Query | Mock API data fetching, loading states, errors, cache, refetch. | +| Zustand | Client state for auth, selected scope, UI shell state, and mock runtime flags. | + +--- + +## 3. Implementation Goal + +The first implementation target is a browser-based mock UI prototype. + +The mock UI should: + +```text +Run without backend APIs +Use realistic mock data +Support selected hierarchy scope +Support mock RBAC behavior +Show loading, empty, error, no-permission, and backend-unavailable states +Show first-phase modules only +Be easy to later connect to real backend APIs +``` + +The mock UI should not attempt to implement full production backend behavior. + +--- + +## 4. Phase Scope + +## 4.1 In-scope modules + +Implement these first-phase modules: + +```text +Global Shell +Authentication +Dashboard +Hierarchy +Topology +Devices +Configuration +Customers / Sub-Operators +Billing +Users +Administration +``` + +## 4.2 Deferred modules + +Do not implement these modules in this phase: + +```text +Clients +Rollouts +Maps +Metrics +AI Agent +``` + +They may appear only as disabled/future labels in docs or comments if needed. + +--- + +## 5. Core Product Rules + +## 5.1 Navigation model + +The application must follow this model: + +```text +Top App Header = GLOBAL product controls +Sidebar = WHAT the user wants to do +Scope Breadcrumb Bar = WHERE the user is working +Workspace Tabs = HOW the user works inside the selected scope +``` + +## 5.2 Top App Header + +The Top App Header contains: + +```text +Logo +Global search +Notifications +Help +User profile +``` + +It must not control hierarchy scope. + +## 5.3 Scope Breadcrumb Bar + +The Scope Breadcrumb Bar controls selected hierarchy scope: + +```text +Operator > Customer > Sub-Operator > Site > Building > Floor > Venue +``` + +Changing selected scope must refresh scoped module data. + +## 5.4 Sidebar + +Sidebar contains first-phase operational modules: + +```text +Dashboard +Customers +Hierarchy +Devices +Configuration +Billing +Users +Administration +``` + +Important: + +```text +Topology must NOT be a root sidebar module. +``` + +Correct topology paths: + +```text +Hierarchy -> Selected Node -> Topology Tab +Devices -> Connectivity View +``` + +## 5.5 RBAC + +Frontend RBAC behavior: + +```text +Unauthorized module = hidden +Unauthorized action = hidden +Read-only permission = visible but non-editable +Backend 403 = no-permission state +``` + +Backend authorization is still required later. Mock frontend RBAC is only for prototype behavior. + +## 5.6 System states + +Every important screen must support: + +```text +Loading +Empty +Error +No Permission +Backend Unavailable +Partial Data +Success +Confirmation Required +Read-only +``` + +--- + +## 6. Project Setup + +## 6.1 Create project + +Preferred package manager: + +```text +npm +``` + +Create the app: + +```bash +npm create next-app@latest mdu-ui --yes +cd mdu-ui +``` + +Important version rule: + +```text +The project target is Next.js latest. +If create-next-app installs a newer major version, pin Next.js to 15.x in package.json before continuing. +``` + +## 6.2 Install dependencies + +```bash +npm add zustand @tanstack/react-query @xyflow/react lucide-react +``` + +Initialize shadcn/ui: + +```bash +npm dlx shadcn@latest init +``` + +Add first shadcn/ui components: + +```bash +npm dlx shadcn@latest add button card badge input dropdown-menu sheet dialog tabs table separator breadcrumb skeleton alert select textarea tooltip scroll-area command +``` + +## 6.3 Required package expectations + +The project should support: + +```text +App Router +TypeScript +Tailwind CSS +ESLint +@/* import alias +``` + +## 6.4 Development command + +```bash +npm dev +``` + +--- + +## 7. Folder Structure + +Use this structure: + +```text +src/ + app/ + layout.tsx + page.tsx + providers.tsx + + (auth)/ + login/ + page.tsx + + (app)/ + layout.tsx + dashboard/ + page.tsx + hierarchy/ + page.tsx + devices/ + page.tsx + [deviceId]/ + page.tsx + configurations/ + page.tsx + [configId]/ + page.tsx + customers/ + page.tsx + [customerId]/ + page.tsx + billing/ + page.tsx + users/ + page.tsx + [userId]/ + page.tsx + administration/ + page.tsx + + components/ + shell/ + app-shell.tsx + top-app-header.tsx + sidebar.tsx + scope-breadcrumb-bar.tsx + global-search-overlay.tsx + user-profile-menu.tsx + + states/ + loading-state.tsx + empty-state.tsx + error-state.tsx + no-permission-state.tsx + backend-unavailable-state.tsx + partial-data-state.tsx + confirmation-dialog.tsx + + dashboard/ + hierarchy/ + topology/ + devices/ + configurations/ + customers/ + billing/ + users/ + administration/ + common/ + + ui/ + shadcn generated components + + lib/ + mock-api/ + client.ts + dashboard.ts + hierarchy.ts + devices.ts + configurations.ts + customers.ts + billing.ts + users.ts + administration.ts + + mock-data/ + hierarchy.ts + devices.ts + configurations.ts + customers.ts + billing.ts + users.ts + alerts.ts + + rbac/ + permissions.ts + can.ts + module-access.ts + + constants/ + modules.ts + routes.ts + roles.ts + + utils.ts + + stores/ + auth-store.ts + scope-store.ts + ui-store.ts + mock-runtime-store.ts + + types/ + common.ts + hierarchy.ts + rbac.ts + device.ts + billing.ts + user.ts + config.ts + customer.ts + dashboard.ts + system.ts +``` + +--- + +## 8. Routing Plan + +Use Next.js App Router. + +## 8.1 Public routes + +```text +/login +``` + +## 8.2 Authenticated routes + +```text +/dashboard +/hierarchy +/devices +/devices/[deviceId] +/configurations +/configurations/[configId] +/customers +/customers/[customerId] +/billing +/users +/users/[userId] +/administration +``` + +## 8.3 Redirect behavior + +Root route: + +```text +/ +``` + +should redirect to: + +```text +/dashboard +``` + +if authenticated, otherwise: + +```text +/login +``` + +For mock phase, authentication may default to a mock logged-in user. + +--- + +## 9. Rendering Strategy + +## 9.1 Server vs client components + +Use this rule: + +```text +Route pages may be thin server components. +Interactive feature components should be client components. +``` + +Client components are required for: + +```text +Zustand stores +TanStack Query hooks +Scope switching +Sidebar state +Dialogs +Tabs +React Flow topology +Mock runtime toggles +``` + +## 9.2 Recommended pattern + +Page file: + +```text +src/app/(app)/dashboard/page.tsx +``` + +should render: + +```text + +``` + +The actual logic lives in: + +```text +src/components/dashboard/dashboard-page.tsx +``` + +--- + +## 10. State Management + +## 10.1 Zustand stores + +Use Zustand for browser/client state. + +### auth-store.ts + +Responsible for: + +```text +current user +current role +mock login +mock logout +role switching for testing +``` + +### scope-store.ts + +Responsible for: + +```text +selected scope ID +selected scope path +selected node +scope switching +recent scopes +``` + +### ui-store.ts + +Responsible for: + +```text +sidebar collapsed +mobile drawer open +global search open +active module +active workspace tab +``` + +### mock-runtime-store.ts + +Responsible for testing system states: + +```text +force backend unavailable +force empty state +force no permission +force partial data +force error state +``` + +This store helps simulate UX states without backend APIs. + +--- + +## 11. Data Fetching Strategy + +Use TanStack Query for all mock API reads. + +## 11.1 Query key rules + +Use stable query keys: + +```text +['dashboard', scopeId] +['hierarchy', role, rootScopeId] +['devices', scopeId, filters] +['device', deviceId] +['billing', scopeId] +['customers', scopeId] +['users', scopeId] +['configurations', scopeId] +``` + +## 11.2 Mock API behavior + +Mock API functions should: + +```text +Return Promises +Use artificial delay +Accept selected scope ID +Respect mock RBAC where useful +Support empty/error/backend-unavailable simulation +Never call real backend +``` + +Example mock API shape: + +```text +getDashboardSummary(scopeId) +getHierarchyTree(userId, role) +getDevices(scopeId) +getDeviceById(deviceId) +getBillingOverview(scopeId) +getUsers(scopeId) +``` + +## 11.3 Mutation behavior + +For mock phase, mutations may: + +```text +Update local mock data in memory +Show success toast +Invalidate relevant TanStack Query keys +Do not persist after page refresh unless localStorage is intentionally used +``` + +--- + +## 12. Type System Plan + +Create reusable TypeScript types before UI components. + +Required type files: + +```text +src/types/common.ts +src/types/hierarchy.ts +src/types/rbac.ts +src/types/device.ts +src/types/billing.ts +src/types/user.ts +src/types/config.ts +src/types/customer.ts +src/types/dashboard.ts +src/types/system.ts +``` + +## 12.1 Core types + +Define: + +```text +HierarchyNode +HierarchyNodeType +ScopePathItem +SelectedScope +UserRole +PermissionAction +ModuleKey +RbacDecision +Device +DeviceType +DeviceStatus +BillingPlan +Subscription +ConfigurationSet +Customer +SystemState +``` + +## 12.2 Role model + +Use these roles: + +```text +Root Operator +Operator Admin +Customer Admin +NOC/Support +Installer +Billing/Admin +Read-only +``` + +Use stable code values, for example: + +```text +root_operator +operator_admin +customer_admin +noc_support +installer +billing_admin +read_only +``` + +--- + +## 13. Mock Data Plan + +Create mock data for: + +```text +hierarchy +users +customers +devices +billing plans +subscriptions +configurations +alerts +activity events +``` + +## 13.1 Mock hierarchy + +Must support variable depth: + +```text +Operator +-> Customer + -> Sub-Operator + -> Site + -> Building + -> Tower + -> Floor + -> Venue +``` + +Also include shorter paths: + +```text +Customer -> Venue +Customer -> Site -> Venue +Customer -> Site -> Building -> Floor +``` + +## 13.2 Mock devices + +Include infrastructure devices only: + +```text +Gateways +Switches +Access Points +``` + +Do not include clients as Devices. + +## 13.3 Mock billing + +Include: + +```text +fixed_device plans +connection_based plans +active subscription +no active subscription state +billing conflict state +no available plans state +``` + +## 13.4 Mock users + +Include users for each role: + +```text +Operator Admin +Customer Admin +NOC/Support +Installer +Billing/Admin +Read-only +``` + +--- + +## 14. RBAC Implementation Plan + +## 14.1 Permission helpers + +Create: + +```text +src/lib/rbac/permissions.ts +src/lib/rbac/can.ts +src/lib/rbac/module-access.ts +``` + +## 14.2 can helper + +Required helper: + +```text +can(user, action, resource, scope): RbacDecision +``` + +Return shape: + +```text +{ + allowed: boolean + reason?: string + mode?: 'hidden' | 'disabled' | 'read-only' | 'visible' +} +``` + +## 14.3 Module access + +Create helper: + +```text +getVisibleModules(user, selectedScope) +``` + +It should hide unauthorized modules from sidebar. + +## 14.4 Action behavior + +Use these rules: + +```text +Unauthorized action = hidden +State-unavailable action = disabled +Read-only action = hidden or visible disabled, depending on context +No-permission backend result = no-permission state +``` + +## 14.5 RBAC test cases + +The mock app should make it easy to switch role and validate: + +```text +Operator Admin sees customer, billing, users, hierarchy, devices +Customer Admin sees own subtree and available billing plans +NOC/Support sees operational health and diagnostics, not billing management +Installer sees deployment/device assignment actions only if permitted +Billing/Admin sees billing workflows +Read-only sees data but no write actions +``` + +--- + +## 15. Scope Context Plan + +## 15.1 Scope source of truth + +The selected scope lives in: + +```text +scope-store.ts +``` + +## 15.2 Scope changes + +When selected scope changes: + +```text +Scope Breadcrumb Bar updates +Hierarchy tree selection updates +Current route remains unless invalid +TanStack Query refetches scoped data +Unauthorized screen/action state recalculates +``` + +## 15.3 Scope Breadcrumb Bar behavior + +It must show: + +```text +Operator > Customer > Sub-Operator > Site > Building > Floor > Venue +``` + +Each segment can open a dropdown for allowed alternatives at that level. + +Only permitted nodes should appear. + +--- + +## 16. Component Architecture + +## 16.1 Shell components + +```text +AppShell +TopAppHeader +Sidebar +ScopeBreadcrumbBar +GlobalSearchOverlay +UserProfileMenu +``` + +## 16.2 State components + +```text +LoadingState +EmptyState +ErrorState +NoPermissionState +BackendUnavailableState +PartialDataState +ConfirmationDialog +``` + +## 16.3 Common components + +```text +PageHeader +KpiCard +StatusBadge +MetadataList +ActivityList +DataTable +FilterBar +RowActions +SectionCard +``` + +## 16.4 Feature components + +Each module should keep feature-specific components inside its own folder: + +```text +components/dashboard/ +components/hierarchy/ +components/topology/ +components/devices/ +components/billing/ +``` + +Do not place feature logic inside generic components. + +--- + +## 17. shadcn/ui Component Plan + +Use shadcn/ui for base components. + +Initial components: + +```text +button +card +badge +input +dropdown-menu +sheet +dialog +tabs +table +separator +breadcrumb +skeleton +alert +select +textarea +tooltip +scroll-area +command +``` + +Usage rules: + +```text +Use shadcn/ui as base building blocks. +Do not over-customize early. +Keep low-fidelity but clean. +Wrap common patterns into MDU-specific components. +``` + +--- + +## 18. Module Implementation Plan + +Use this order. + +## 18.1 Foundation + +Generate first: + +```text +providers +routes +constants +types +mock data +RBAC +stores +mock API client +system states +``` + +Do not start feature screens until this foundation compiles. + +## 18.2 Shell + +Generate: + +```text +AppShell +TopAppHeader +Sidebar +ScopeBreadcrumbBar +GlobalSearchOverlay +UserProfileMenu +``` + +Acceptance: + +```text +Authenticated pages share shell. +Sidebar respects visible modules. +Scope Breadcrumb Bar reads/writes selected scope. +Role switcher can be available in user menu for mock testing. +``` + +## 18.3 Dashboard + +Generate: + +```text +DashboardPage +KpiCard +HealthSummaryPanel +RecentAlertsPanel +BillingSummaryPanel +QuickActionsPanel +``` + +Acceptance: + +```text +Uses selected scope. +Uses TanStack Query. +Handles loading, partial data, no permission, backend unavailable. +Hides billing summary if role lacks billing access. +``` + +## 18.4 Hierarchy + +Generate: + +```text +HierarchyPage +HierarchyTree +NodeWorkspace +NodeOverviewTab +NodeDevicesTab +NodeConfigurationsTab +CreateNodeDialog +MoveNodeDialog +DeleteNodeConfirmation +``` + +Acceptance: + +```text +Recursive tree works. +Selecting node updates selected scope. +Workspace tabs are Overview, Topology, Devices, Configurations. +Deferred tabs are not active. +RBAC hides node actions. +``` + +## 18.5 Topology + +Generate with React Flow: + +```text +TopologyTab +TopologyCanvas +TopologyNode +TopologyOverlayControls +TopologyDeviceDrawer +ConnectivityView +``` + +Acceptance: + +```text +Topology appears under Hierarchy workspace. +Connectivity View appears under Devices. +React Flow renders nodes and links. +Unauthorized devices/links hidden. +No topology / partial data / backend unavailable states exist. +``` + +## 18.6 Devices + +Generate: + +```text +DeviceInventoryPage +DeviceList +DeviceDetailPage +DeviceDiagnostics +DeviceActionConfirmation +AddDeviceDialog +AssignDeviceDialog +ConnectivityView entry +``` + +Acceptance: + +```text +Devices include only gateways, switches, APs. +Device list is scoped. +Device detail supports diagnostics and role-aware actions. +Read-only has no write actions. +``` + +## 18.7 Configuration + +Generate: + +```text +ConfigurationListPage +ConfigurationDetail +CreateConfigurationForm +AssignConfigurationDialog +EffectiveConfigurationPreview +ConfigurationValidationErrors +``` + +Acceptance: + +```text +Configurations are scoped. +Assignments target permitted nodes/devices only. +Effective configuration shows inherited/assigned/overridden values. +``` + +## 18.8 Customers + +Generate: + +```text +CustomerListPage +CreateCustomerWizard +CustomerDetail +CustomerWorkspace +CustomerBillingTab +CustomerUsersTab +SuspendCustomerDialog +DeleteCustomerDialog +``` + +Acceptance: + +```text +Customers are tenant/sub-operator management. +Create customer includes first admin user. +Billing assignment is optional. +Delete/suspend require confirmation. +``` + +## 18.9 Billing + +Generate: + +```text +BillingOverview +BillingPlanList +CreateBillingPlanWizard +BillingPlanDetail +AssignPlanToCustomer +AvailablePlans +SelectPlanConfirmation +CurrentSubscriptionDetail +BillingConflictState +NoAvailablePlansState +NoActiveSubscriptionState +``` + +Acceptance: + +```text +Parent operator manages plans. +Customer sees eligible active parent-offered plans. +Customer cannot edit parent-created plans. +Only one active subscription is allowed. +Sibling subscriptions are never visible. +``` + +## 18.10 Users + +Generate: + +```text +UserListPage +CreateUserForm +UserDetail +AssignRoleProfileDialog +ResetPasswordConfirmation +SuspendUserConfirmation +UserScopeAssignmentSummary +``` + +Acceptance: + +```text +Users are scoped. +Assignable roles are limited by actor authority. +Read-only cannot create/edit/suspend. +``` + +## 18.11 Administration + +Generate: + +```text +AdministrationOverview +RolesAndPolicies +EditRolePolicy +AuditLogs +AuditEventDetail +PermissionChangeImpactWarning +NoAdminPermissionState +``` + +Acceptance: + +```text +Administration hidden without permission. +Roles and policies are business-friendly. +Raw OWPROV internals are not exposed. +Permission changes show impact warning. +``` + +--- + +## 19. React Flow Plan + +Use React Flow only for topology and connectivity. + +Package: + +```text +@xyflow/react +``` + +Required usage: + +```text +import '@xyflow/react/dist/style.css' +``` + +React Flow screens: + +```text +Hierarchy -> Node Workspace -> Topology Tab +Devices -> Connectivity View +``` + +Required graph features: + +```text +nodes +edges +controls +mini map optional +background grid optional +custom device nodes +detail drawer on node click +overlay controls +``` + +Topology data should be generated from mock hierarchy and devices. + +--- + +## 20. System State Plan + +Create reusable state components before feature modules. + +Required states: + +```text +LoadingState +EmptyState +ErrorState +NoPermissionState +BackendUnavailableState +PartialDataState +ConfirmationDialog +``` + +Rules: + +```text +Keep App Shell visible where possible. +Do not flash unauthorized actions before RBAC resolves. +Empty-state CTAs appear only if permitted. +No-permission state must not reveal hidden resource names. +Backend-unavailable state includes retry. +``` + +--- + +## 21. Mock Runtime Controls + +For development and demos, include a hidden or admin-only mock control panel. + +It should allow switching: + +```text +current role +selected scope +backend unavailable on/off +empty data on/off +partial data on/off +error state on/off +``` + +Recommended location: + +```text +User Profile Menu -> Mock Runtime Controls +``` + +This is for development only and should be easy to remove later. + +--- + +## 22. LLM Code Generation Rules + +Use LLM code generation one layer at a time. + +Never prompt: + +```text +Generate the full MDU UI app. +``` + +Instead, use: + +```text +Generate only [specific layer/module]. +Do not generate unrelated modules. +Use existing files and types. +Keep code compiling. +``` + +## 22.1 Source docs rule + +Put all docs in: + +```text +/docs +``` + +For the first coding prompt, tell the LLM: + +```text +Read /docs/frontend-implementation-plan.md first. +Use the other /docs files as source of truth. +``` + +For later prompts, reference only the relevant docs: + +| Task | Main docs | +|---|---| +| Foundation | frontend-implementation-plan.md | +| Routes | frontend-implementation-plan.md, screen-inventory.md | +| Shell | frontend-implementation-plan.md, figma-navigation-model.md, layout-system.md | +| Dashboard | screen-definitions.md, wireframe-plan.md | +| Hierarchy | workflows.md, screen-definitions.md, layout-system.md | +| Topology | mdu-ui-spec.md, screen-definitions.md, wireframe-plan.md | +| Billing | workflows.md, screen-definitions.md, wireframe-plan.md | +| RBAC | workflows.md, screen-definitions.md, frontend-implementation-plan.md | +| System states | screen-definitions.md, layout-system.md, wireframe-plan.md | + +## 22.2 Prompt format + +Use this prompt structure: + +```text +Read /docs/frontend-implementation-plan.md. +Also use: +- [relevant doc 1] +- [relevant doc 2] + +Task: +Generate only [specific module/layer]. + +Requirements: +- [specific requirements] +- Use Next.js latest App Router. +- Use TypeScript. +- Use Tailwind and shadcn/ui. +- Use Zustand where client state is needed. +- Use TanStack Query for data loading. +- Use React Flow only for topology/connectivity. +- Keep RBAC and selected-scope behavior consistent. + +Output: +- file paths +- complete code for changed files +- no unrelated modules +``` + +--- + +## 23. Recommended LLM Generation Sequence + +Use this sequence exactly. + +## Prompt 1 - Foundation + +```text +Generate project foundation: +- src/app/layout.tsx +- src/app/page.tsx +- src/app/providers.tsx +- src/lib/utils.ts +- src/lib/constants/routes.ts +- src/lib/constants/modules.ts + +Do not generate feature screens yet. +``` + +## Prompt 2 - Types + +```text +Generate all TypeScript types in src/types. +Do not generate UI components. +``` + +## Prompt 3 - Mock hierarchy and RBAC + +```text +Generate mock hierarchy data and RBAC helpers. +Do not generate screens. +``` + +## Prompt 4 - Stores + +```text +Generate Zustand stores: +- auth-store +- scope-store +- ui-store +- mock-runtime-store +``` + +## Prompt 5 - Mock APIs + +```text +Generate mock API functions using Promises and artificial delay. +Support scope, RBAC, loading/error/empty/backend-unavailable simulation. +``` + +## Prompt 6 - System states + +```text +Generate reusable state components. +Use shadcn/ui. +``` + +## Prompt 7 - App shell + +```text +Generate AppShell, TopAppHeader, Sidebar, ScopeBreadcrumbBar, GlobalSearchOverlay, UserProfileMenu. +``` + +## Prompt 8 - Dashboard + +```text +Generate dashboard page and dashboard components. +``` + +## Prompt 9 - Hierarchy + +```text +Generate hierarchy workspace and recursive tree. +``` + +## Prompt 10 - Topology + +```text +Generate React Flow topology tab and device connectivity view. +``` + +## Prompt 11 - Devices + +```text +Generate devices list, detail, diagnostics, and actions. +``` + +## Prompt 12 - Configuration + +```text +Generate configuration list, detail, assignment, effective preview. +``` + +## Prompt 13 - Customers + +```text +Generate customers list, create wizard, detail, workspace. +``` + +## Prompt 14 - Billing + +```text +Generate billing plan management, available plans, subscription detail, conflict states. +``` + +## Prompt 15 - Users + +```text +Generate users list, create user, role assignment, user detail. +``` + +## Prompt 16 - Administration + +```text +Generate administration overview, roles/policies, audit logs, impact warning. +``` + +## Prompt 17 - Responsive polish + +```text +Improve responsive behavior for shell, dashboard, hierarchy, tables, details, billing. +``` + +## Prompt 18 - QA pass + +```text +Run through all routes, fix TypeScript errors, fix import issues, verify RBAC and system states. +``` + +--- + +## 24. Quality Rules + +## 24.1 Code quality + +Generated code must be: + +```text +typed +modular +readable +consistent +easy to replace with real APIs later +``` + +Avoid: + +```text +large single files +hardcoded UI logic inside route pages +duplicated RBAC logic +duplicated mock data inside components +feature code inside generic components +``` + +## 24.2 Component rules + +Components should be: + +```text +small +typed +composable +role-aware when needed +scope-aware when needed +``` + +## 24.3 Mock API rules + +Mock APIs should be: + +```text +centralized in src/lib/mock-api +called through TanStack Query +easy to replace with real fetch clients later +``` + +## 24.4 RBAC rules + +RBAC should be: + +```text +centralized in src/lib/rbac +used by sidebar, actions, tabs, and screens +not duplicated per component +``` + +## 24.5 Scope rules + +Scope should be: + +```text +centralized in scope-store +visible in Scope Breadcrumb Bar +passed to query keys +used by mock API filters +``` + +--- + +## 25. Testing and Validation + +## 25.1 Manual validation routes + +Check these routes: + +```text +/login +/dashboard +/hierarchy +/devices +/devices/[deviceId] +/configurations +/customers +/billing +/users +/administration +``` + +## 25.2 Manual validation workflows + +Validate: + +```text +Login -> Dashboard +Change scope -> Dashboard refreshes +Hierarchy tree -> Node workspace +Node workspace -> Topology tab +Topology -> Device drawer +Devices -> Device detail -> Diagnostics +Billing -> Available plans -> Select plan +Customers -> Create customer +Users -> Create user +Administration -> Role impact warning +``` + +## 25.3 State validation + +Use mock runtime controls to validate: + +```text +Loading +Empty +No Permission +Backend Unavailable +Partial Data +Error +Read-only +Confirmation +``` + +## 25.4 RBAC validation + +Switch roles and verify: + +```text +Sidebar modules change +Actions hide or show +Read-only cannot mutate +Billing hidden for non-billing users +Administration hidden for unauthorized users +Topology hides unauthorized overlays +``` + +--- + +## 26. Backend Integration Later + +This mock UI should be structured so real APIs can replace mock APIs later. + +Future backend integration steps: + +```text +Replace src/lib/mock-api with real API clients +Keep TanStack Query hooks and query keys +Keep TypeScript DTOs aligned with backend +Keep RBAC backend-enforced +Replace mock auth with OWSEC/session integration +Replace mock hierarchy with real hierarchy APIs +``` + +Do not tightly couple UI components to mock data. + +--- + +## 27. Acceptance Checklist + +The frontend implementation plan is complete when: + +```text +Tech stack is defined. +Folder structure is defined. +Routes are defined. +State strategy is defined. +Mock API strategy is defined. +RBAC strategy is defined. +Scope strategy is defined. +Component architecture is defined. +Module implementation order is defined. +LLM prompt rules are defined. +Quality rules are defined. +Testing and validation rules are defined. +Backend integration path is defined. +``` + +--- + +## 28. Final Summary + +Use this document as the primary coding guide for the mock MDU UI. + +Recommended execution: + +```text +1. Create Next.js latest project +2. Add dependencies +3. Add shadcn/ui components +4. Add all docs into /docs +5. Generate foundation +6. Generate types +7. Generate mock data, RBAC, stores, mock APIs +8. Generate shell +9. Generate modules one by one +10. Validate workflows and states +11. Later replace mock APIs with real APIs +``` + +Important rule: + +```text +One LLM prompt = one layer or one module. +Never generate the whole app in one prompt. +``` + diff --git a/ui-docs/mdu-ui-spec.md b/ui-docs/mdu-ui-spec.md new file mode 100644 index 0000000..93b4b5a --- /dev/null +++ b/ui-docs/mdu-ui-spec.md @@ -0,0 +1,2794 @@ +# MDU UI Specification and Design Flow + +## 1. Purpose + +This document defines the architecture, design flow, information architecture, navigation model, UI modules, authentication model, RBAC behavior, entity hierarchy, backend integration model, and frontend behavior for the MDU UI platform. + +The goal of the MDU UI is to provide a unified multi-tenant management platform for: + +* Operators +* Customers/Sub-Operators +* Entities +* Nodes +* Sites +* Venues +* Infrastructure devices +* Clients +* Configurations +* Rollouts +* Billing plans +* Subscriptions +* Maps +* Topology views +* Metrics +* Contacts +* Locations +* Users +* AI-assisted operations +* RBAC-controlled administration + +This document also defines how the MDU UI interacts with: + +* OWSEC (Authentication and Security Service) +* OWPROV (Hierarchy, Resource, and RBAC Service) +* MDU Backend APIs + +The design intentionally separates frontend business concepts from OWPROV internal implementation details. The frontend should expose a clear operational UX while the backend remains responsible for orchestration, hierarchy resolution, and access enforcement. + +--- + +# 2. Glossary and Naming Model + +## 2.1 Customer/Sub-Operator + +Customer/Sub-Operator represents a recursive child tenant inside the MDU hierarchy. + +In UI-facing language, this may be shown as **Customer** because business users commonly understand that term. In technical architecture, backend flow, and permission logic, the same object should be treated as a **Sub-Operator / Child Tenant**. + +Meaning: + +```text +Customer = Sub-Operator = Child Tenant +``` + +A Customer/Sub-Operator is not only a final leaf customer. It can also act like an operator for its own subtree when its permissions allow. + +A customer/sub-operator: + +* Owns its own subtree +* Can create child customers/sub-operators if its policy allows +* Can manage users, devices, clients, configurations, maps, contacts, locations, nodes, sites, and venues within its subtree +* Can view/select eligible billing plans offered by its parent operator +* Can view current subscription and billing status according to permissions +* Can delegate access to users inside its own subtree +* Cannot modify parent-created billing plans +* Cannot view sibling billing plans or subscriptions +* Cannot access sibling subtrees +* Cannot access parent resources unless explicitly allowed +* Cannot create or manage resources outside its assigned subtree + +--- + +## 2.2 Entity + +Entity is an OWPROV internal hierarchy object. + +Frontend behavior: + +```text +Entity should not be a first-class business object in normal UI flows. +``` + +Entity may be exposed only in: + +* Advanced admin pages +* Debug/admin tooling +* Internal troubleshooting views + +Normal frontend flows should use: + +* Customer/Sub-Operator +* Node +* Venue +* Site + +instead of raw entity terminology. + +--- + +## 2.3 Node + +Node is the generic hierarchy abstraction used by the frontend. + +A node may represent: + +* Customer scope +* Site +* Building +* Tower +* Floor +* Venue +* Grouping hierarchy + +Nodes form the recursive frontend tree structure. + +Nodes internally map to: + +* OWPROV Entity +* OWPROV Venue + +through backend mapping/orchestration. + +--- + +## 2.4 Site + +Site represents a logical or physical deployment grouping. + +Examples: + +* Apartment complex +* Hotel +* Campus +* Office building +* Retail branch + +A site may contain: + +* Multiple nodes +* Multiple venues +* Multiple floor maps +* Infrastructure devices +* Clients +* Configurations +* Metrics + +--- + +## 2.5 Venue + +Venue represents the physical deployment location. + +Examples: + +* Floor +* Hall +* Wing +* Building area +* Room cluster + +Venues are the primary physical scope for: + +* Device placement +* Maps +* Topology overlays +* Wireless coverage +* Client density visualization +* Client/device contextualization + +--- + +## 2.6 Infrastructure Device + +Infrastructure devices are managed network assets. + +Examples: + +* Gateways +* Switches +* Access Points + +Infrastructure devices are persistent inventory objects, can participate in configuration rollouts, and can appear in topology and connectivity views. + +--- + +## 2.7 Client + +Client represents an end-user/mobile/endpoint device connected to the network. + +Examples: + +* Phones +* Laptops +* Tablets +* IoT endpoints +* Printers +* TVs + +Clients are transient, session-oriented, high-volume, analytics-focused objects. They should be treated as a separate operational domain from infrastructure devices. + +--- + +# 3. High-Level Architecture + +## 3.1 Architecture Overview + +```text +MDU UI + ├── Directly calls OWSEC + │ ├── Login + │ ├── Logout + │ ├── Token refresh + │ ├── Session validation + │ ├── Forgot password + │ └── Change password + │ + └── Calls MDU Backend APIs + ├── Customers/Sub-Operators + ├── Hierarchy/Nodes + ├── Sites + ├── Venues + ├── Devices + ├── Clients + ├── Users + ├── Configurations + ├── Rollouts + ├── Billing Plans + ├── Subscriptions + ├── Maps + ├── Metrics + ├── AI Agent / AI Actions + └── Administration + +MDU Backend + ├── Calls OWSEC for user lifecycle operations + ├── Calls OWPROV for hierarchy, RBAC, and resource operations + ├── Resolves selected hierarchy scope + ├── Enforces subtree isolation + ├── Enforces billing/subscription visibility + ├── Builds contextual topology responses + └── Provides AI workflow orchestration interfaces when enabled + +OWSEC + ├── Authentication + ├── Token management + ├── Session handling + ├── Password management + └── User account management + +OWPROV + ├── Operator hierarchy + ├── Customer/Sub-Operator hierarchy + ├── Entity tree + ├── Venue tree + ├── Inventory/devices + ├── Configuration + ├── Maps + ├── Contacts + ├── Locations + ├── ManagementRole + ├── ManagementPolicy + └── RBAC enforcement +``` + +--- + +## 3.2 UI Architecture Principle + +The UI architecture must separate: + +```text +Operational Navigation +``` + +from: + +```text +Hierarchy Scope Navigation +``` + +Operational navigation answers: + +```text +What work does the user want to do? +``` + +Hierarchy scope navigation answers: + +```text +Where in the customer/operator hierarchy is the user working? +``` + +This separation is required because the MDU hierarchy is recursive and may be shallow or deeply nested depending on deployment. + +--- + +# 4. Core Design Principles + +## 4.1 Frontend Must Not Understand OWPROV Internals + +The frontend must not directly expose or depend on internal OWPROV concepts such as: + +* managementRole +* managementPolicy +* policy inheritance +* scope chains +* entity attachment internals +* venue attachment internals +* raw RBAC resolution + +The frontend should operate using business-oriented concepts: + +* Customer +* Sub-Operator +* Node +* Site +* Venue +* Gateway +* Switch +* Access Point +* Client +* User +* Configuration Set +* Rollout +* Billing Plan +* Subscription +* Map +* Topology View +* AI Agent + +--- + +## 4.2 Direct Authentication Through OWSEC + +The frontend directly integrates with OWSEC for authentication and session handling. + +Reason: + +```text +MDU UI authentication should continue functioning even if the MDU backend is unavailable. +``` + +This allows: + +* Login while backend is down +* Session refresh while backend is down +* Logout while backend is down +* UI shell rendering during backend outage + +Business/resource operations still depend on the MDU backend. + +--- + +## 4.3 MDU Backend Acts as Orchestrator + +The MDU backend acts as a wrapper/orchestrator layer. + +The UI calls: + +```text +/api/v1/mdu/* +``` + +The backend internally: + +* Validates requests +* Resolves hierarchy/scope +* Calls OWSEC +* Calls OWPROV +* Builds composed responses +* Applies orchestration logic +* Enforces tenant scope for billing plans and subscriptions +* Enforces device/client visibility boundaries +* Builds contextual topology and workspace responses +* Converts canonical responses into MDU response shapes + +--- + +## 4.4 UX Must Hide Backend Complexity + +The frontend should avoid exposing backend hierarchy complexity directly to users. + +The user should not need to understand whether an item is internally represented as an entity, venue, role, policy, or scope chain. The UI should present a clear operational model using customers, hierarchy, devices, clients, maps, billing, and contextual workspaces. + +--- + +# 5. Information Architecture and Navigation Model + +## 5.1 Information Architecture Philosophy + +The MDU platform is a recursive multi-tenant operational system. + +The UI architecture must optimize for: + +* Operational simplicity +* Recursive hierarchy scalability +* Contextual workflows +* RBAC-aware visibility +* AI-native operational assistance +* Topology contextualization +* Subtree isolation + +The Information Architecture (IA) is not a replacement for this specification. It is the UX/navigation layer that defines how users move through the platform and how operational modules behave inside the selected hierarchy scope. + +--- + +## 5.2 Operational Navigation vs Hierarchy Scope Navigation + +The platform must clearly separate: + +```text +Operational Navigation +``` + +from: + +```text +Hierarchy Scope Navigation +``` + +Operational navigation should be stable regardless of hierarchy depth. + +Hierarchy scope navigation should be contextual and should represent the current working scope. + +Example: + +```text +Selected scope: +Operator A / Customer B / Sunrise Towers / Floor 12 +``` + +When the selected scope changes, each operational module should automatically load data within that scope. + +--- + +## 5.3 Left Sidebar Navigation + +The left sidebar should expose operational modules only. + +Recommended top-level navigation: + +```text +Dashboard +Customers +Hierarchy +Devices +Clients +Configurations +Rollouts +Maps +Billing +Users +Metrics +AI Agent +Administration +``` + +Design rules: + +* Navigation modules represent operational domains. +* Recursive hierarchy navigation remains contextual. +* Topology is not a standalone root sidebar module. +* AI is available as a module and as contextual actions. +* Modules remain stable regardless of hierarchy depth. +* Sidebar items must be RBAC-aware and hidden when unauthorized. + +--- + +## 5.4 Top Context Bar + +The top context bar represents the currently selected subtree scope. + +Example: + +```text +Operator A / Customer B / Sunrise Towers / Floor 12 +``` + +The following UI components must remain synchronized: + +* Hierarchy tree +* Breadcrumbs +* Selected subtree +* Route context +* Operational workspace context +* Scoped API query parameters +* RBAC visibility state + +If the user changes the selected subtree, all module data should refresh within the new scope. + +--- + +## 5.5 Hierarchy-First Navigation + +The platform should use: + +```text +Hierarchy-first navigation +``` + +instead of: + +```text +Dedicated topology navigation +``` + +Users should first navigate to the appropriate hierarchy node. Once the correct hierarchy node is selected, the workspace context changes automatically. + +Example hierarchy: + +```text +Customer + └── Site + └── Building + └── Tower + └── Floor + └── Venue +``` + +The hierarchy depth may vary across deployments. + +Valid examples: + +```text +Customer → Venue +``` + +```text +Customer → Site → Building → Tower → Floor → Venue +``` + +The UI architecture must support variable recursive hierarchy depth. + +--- + +## 5.6 Hierarchy Workspace Model + +Once a hierarchy node is selected, the platform should expose contextual operational tabs. + +Example: + +```text +Selected Node: +Sunrise Towers / Floor 12 +``` + +Contextual workspace tabs: + +```text +Overview +Topology +Devices +Clients +Maps +Configurations +Metrics +AI Insights +``` + +The workspace context should dynamically adapt based on: + +* Selected hierarchy node +* Node type +* Available deployment data +* RBAC scope +* Enabled platform capabilities + +Unauthorized tabs must be hidden. + +--- + +## 5.7 Topology as a Contextual View + +Topology should not be modeled as a standalone root navigation object. + +Correct UX: + +```text +Hierarchy → Select Floor 12 → Topology tab +``` + +Not ideal: + +```text +Sidebar → Topology +``` + +Topology is a contextual view of the selected hierarchy node. + +This allows topology to scale across: + +* Sites +* Buildings +* Towers +* Floors +* Venues + +without coupling topology behavior to a single hierarchy type. + +--- + +## 5.8 Venue Topology vs Device Connectivity Topology + +The platform should distinguish between venue topology and device connectivity topology. + +### Venue Topology + +Venue topology is the primary operational visualization. + +Focus: + +* Maps +* Floor visualization +* AP placement +* Wireless coverage +* Client density +* Wireless quality +* Venue hierarchy +* Spatial visualization + +Venue topology should be the default topology experience for most users. + +Examples: + +```text +Floor 12 topology +Building topology +Tower topology +Campus topology +``` + +### Device Connectivity Topology + +Device connectivity topology is a secondary engineering-focused topology. + +Focus: + +* Switch uplinks +* Gateway uplinks +* AP uplinks +* Mesh links +* WAN connectivity +* L2/L3 relationships +* Port connectivity +* Logical network graph + +Recommended navigation: + +```text +Devices → Connectivity View +``` + +This experience is intended primarily for: + +* NOC +* Engineering +* Advanced troubleshooting + +The platform should avoid exposing complex network graphs as the default topology experience. + +--- + +## 5.9 Recommended Topology Behavior Per Hierarchy Level + +### Site Level + +Recommended topology content: + +* Building summaries +* Aggregate health +* Deployment overview +* Regional metrics + +### Building Level + +Recommended topology content: + +* Floor structure +* Distribution switches +* AP density +* Backbone connectivity + +### Tower Level + +Recommended topology content: + +* Floor relationships +* AP distribution +* Tower-level health +* Aggregation links + +### Floor Level + +Recommended topology content: + +* Floor maps +* AP placement +* Wireless overlays +* Client density +* Wireless quality +* Roaming visualization + +### Venue Level + +Recommended topology content: + +* Detailed operational topology +* Overlays +* Client relationships +* AP/client behavior +* Coverage visualization +* Wireless experience metrics + +--- + +## 5.10 Devices vs Clients Separation + +Infrastructure devices and end-user clients must be separate operational domains. + +Devices are managed assets: + +```text +Devices + ├── Gateways + ├── Switches + ├── Access Points + ├── Inventory + ├── Firmware + ├── Assignments + └── Connectivity View +``` + +Clients are transient/session-oriented endpoints: + +```text +Clients + ├── Active Clients + ├── Historical Clients + ├── Client Sessions + ├── Wireless Experience + ├── Roaming + ├── Client Analytics + └── Troubleshooting +``` + +Clients should appear in topology primarily as: + +* Counts +* Overlays +* Heatmaps +* Density visualization +* Roaming visualization + +Clients should not appear as default topology graph nodes. + +--- + +## 5.11 AI-Native Operational Model + +The platform should be designed as an AI-native operational system. + +AI functionality should exist in two forms: + +```text +A. Centralized AI Agent Module +B. Contextual AI Actions Across Operational Workflows +``` + +Recommended AI Agent module structure: + +```text +AI Agent + ├── Ask Anything + ├── Investigations + ├── Recommendations + ├── Automations + ├── Playbooks + └── Agent Activity +``` + +The AI system should support: + +* Diagnostics +* Anomaly detection +* Rollout planning +* Wireless optimization +* Customer health analysis +* Subscription risk analysis +* Topology analysis +* AP placement recommendations +* Congestion analysis + +--- + +## 5.12 Contextual AI Workflows + +AI capabilities should appear contextually throughout the platform. + +Examples: + +### Hierarchy Node + +```text +Ask AI About This Floor +Ask AI About This Building +Analyze Wireless Health +``` + +### Device + +```text +Diagnose This AP +Analyze Uplink Stability +``` + +### Rollout + +```text +Explain Rollout Failure +Create Staged Rollout +``` + +### Billing + +```text +Summarize Subscription Risk +``` + +### Customer + +```text +Generate Customer Health Summary +``` + +Recommended operational workflow: + +```text +AI Suggestion + → Review Plan + → Approve Action + → Execute Workflow + → Track Result +``` + +AI-generated operational plans should remain editable before execution. + +--- + +## 5.13 AI RBAC and Scope Rules + +AI should: + +* Augment operators +* Provide explainable recommendations +* Remain scope-aware +* Obey RBAC +* Respect subtree isolation + +AI should not: + +* Expose sibling subtree information +* Expose unauthorized billing data +* Expose unauthorized device inventory +* Recommend actions outside user scope +* Execute workflow changes without proper review/approval when required + +--- + +# 6. Multi-Tenant Hierarchy Model + +## 6.1 Recursive Customer/Sub-Operator Model + +The system uses a recursive tenant hierarchy. + +```text +Root Operator + └── Customer/Sub-Operator A + └── Customer/Sub-Operator B + └── Customer/Sub-Operator C + ├── Nodes + ├── Venues + ├── Devices + ├── Clients + ├── Users + ├── Configurations + ├── Billing Subscriptions + ├── Maps + ├── Contacts + └── Locations +``` + +Meaning: + +```text +Customer = Sub-Operator = Child Tenant +``` + +Every child customer/sub-operator behaves like its parent: + +* Can manage its own subtree +* Can create child customers/sub-operators +* Can create users +* Can create venues +* Can manage infrastructure inventory +* Can view clients within its scope +* Can manage configuration +* Can manage billing plan visibility for direct children when allowed +* Can view and select eligible billing plans from its parent scope +* Can manage maps +* Can manage contacts and locations + +--- + +## 6.2 Isolation Rules + +Each customer/sub-operator only sees its own subtree. + +Example: + +```text +Customer A + cannot see +Customer B +``` + +Rules: + +* Child cannot see sibling subtree +* Child cannot see parent resources unless explicitly allowed +* Child cannot create resources outside its scope +* Child cannot bypass scope boundaries +* Child cannot access unauthorized billing, device, client, map, topology, or AI context data + +--- + +# 7. Authentication Flow + +## 7.1 Login Flow + +```text +1. User opens MDU UI. +2. UI calls OWSEC login API directly. +3. OWSEC authenticates credentials. +4. OWSEC returns: + access_token + refresh_token + session information + user information +5. UI stores token/session. +6. UI calls MDU backend bootstrap API. +7. MDU backend validates token. +8. MDU backend resolves RBAC scope using OWPROV. +9. UI loads dashboard, navigation, selected hierarchy context, and allowed modules. +``` + +--- + +## 7.2 Session Refresh Flow + +```text +1. UI detects token nearing expiry. +2. UI directly calls OWSEC refresh API. +3. OWSEC returns refreshed token. +4. UI updates stored session. +``` + +--- + +## 7.3 Backend Down Behavior + +If MDU backend is unavailable: + +```text +- Login still works. +- Logout still works. +- Session refresh still works. +- UI shell still loads. +- Navigation renders from cached/bootstrapped permissions when safe. +- Data pages show service unavailable state. +``` + +Business data must not be shown from stale cache unless the UI clearly marks it as stale and the product requirement allows it. + +--- + +# 8. RBAC Model + +## 8.1 RBAC Ownership + +RBAC means **Role-Based Access Control**. + +RBAC determines: + +```text +Who can do what, and where. +``` + +OWPROV is the source of truth for: + +* RBAC +* Scope +* Hierarchy +* Role attachment +* Policy attachment +* Access validation + +--- + +## 8.2 ManagementRole + +ManagementRole defines: + +```text +Who has access +and +Where access is scoped +``` + +Example: + +```text +Customer Admin Role + → attached to customer entity + → contains customer admin users +``` + +--- + +## 8.3 ManagementPolicy + +ManagementPolicy defines: + +```text +What actions are allowed +on which resource types +``` + +Example: + +```text +Customer Full Access Policy + → inventory FULL + → venue FULL + → configuration FULL +``` + +--- + +## 8.4 Scope Chain + +OWPROV evaluates access through scope chains. + +Example: + +```text +venue + → parent venue + → entity + → parent entity + → operator entity + → operator +``` + +Frontend should never directly implement this logic. + +--- + +## 8.5 RBAC-Aware Navigation + +The UI must apply RBAC to: + +* Sidebar modules +* Top context bar scope options +* Hierarchy tree nodes +* Workspace tabs +* Page actions +* Dropdown options +* Search results +* Billing plans and subscriptions +* Device and client visibility +* AI prompts, context, and recommendations + +Backend authorization remains mandatory even when the UI hides unauthorized elements. + +--- + +# 9. Customer/Sub-Operator Creation Flow + +## 9.1 Frontend Behavior + +Frontend performs one business action: + +```http +POST /api/v1/mdu/customers +``` + +Frontend does not individually call: + +* create entity +* create role +* create policy +* create user +* attach role +* attach policy + +Those are backend orchestration operations. + +--- + +## 9.2 Backend Orchestration Flow + +```text +1. Authenticate token. +2. Resolve current parent scope. +3. Validate create-customer permission. +4. Create child entity in OWPROV. +5. Create admin user in OWSEC. +6. Create management policy in OWPROV. +7. Create management role in OWPROV. +8. Attach user to role. +9. Attach role and policy to entity. +10. Return customer/sub-operator summary. +``` + +--- + +## 9.3 Result + +The newly created customer/sub-operator receives: + +* Its own entity scope +* Its own admin user +* Its own RBAC policy +* Its own role attachment +* Its own subtree isolation + +The new admin can then: + +* Login +* Create child sub-operators when allowed +* Create users +* Create venues +* Manage devices +* View clients +* Manage configuration +* View/select billing plans when eligible + +--- + +# 10. User Creation Flow + +## 10.1 First Admin User + +The first admin user is automatically created during customer/sub-operator creation. + +--- + +## 10.2 Additional Users + +Additional users are created through User Management. + +Frontend: + +```http +POST /api/v1/mdu/users +``` + +Backend internally: + +```text +1. Validate permission. +2. Create user in OWSEC. +3. Attach user to role. +4. Create/reuse policy profile. +5. Attach policy to current scope. +``` + +--- + +## 10.3 Supported User Types + +Supported user profiles: + +* Customer Admin +* Installer +* NOC +* Read-only +* CSR +* Accounting +* Partner + +--- + +# 11. Node and Venue Model + +## 11.1 MDU Node Concept + +The frontend uses the abstraction: + +```text +Node +``` + +A node may internally map to: + +* OWPROV Entity +* OWPROV Venue + +The frontend should not need to know which internal object type is used. + +--- + +## 11.2 Recursive Node Tree + +Example: + +```text +Customer + └── Site + └── Building + └── Tower + └── Floor + └── Venue +``` + +The frontend must support variable depth. + +Examples: + +```text +Customer → Venue +``` + +```text +Customer → Site → Building → Tower → Floor → Venue +``` + +--- + +## 11.3 Node APIs + +```text +GET /api/v1/mdu/nodes +POST /api/v1/mdu/nodes +GET /api/v1/mdu/nodes/{nodeId} +GET /api/v1/mdu/nodes/{nodeId}/children +GET /api/v1/mdu/nodes/{nodeId}/topology +GET /api/v1/mdu/nodes/{nodeId}/workspace +``` + +`GET /api/v1/mdu/nodes/{nodeId}/workspace` may return contextual tabs, summary metrics, and allowed actions for the selected hierarchy node. + +--- + +## 11.4 Hierarchy Workspace Tabs + +A selected node may expose: + +* Overview +* Topology +* Devices +* Clients +* Maps +* Configurations +* Metrics +* AI Insights + +The backend should return only tabs allowed by RBAC and enabled platform capabilities. + +--- + +# 12. Device Management + +## 12.1 Device Categories + +The Devices module is for infrastructure devices only. + +Infrastructure device categories: + +* Gateways +* Switches +* Access Points + +Clients must not be treated as infrastructure devices in the Devices module. + +--- + +## 12.2 Device Module Structure + +Recommended structure: + +```text +Devices + ├── Gateways + ├── Switches + ├── Access Points + ├── Inventory + ├── Firmware + ├── Assignments + └── Connectivity View +``` + +--- + +## 12.3 Device Operations + +Supported operations: + +* Create device +* Assign device +* Move device +* Reboot device +* Upgrade device +* Blink device +* Factory reset +* View contextual topology +* View connectivity topology +* View metrics +* Run AI-assisted diagnostics when permitted + +--- + +## 12.4 Device Connectivity View + +Device connectivity topology is an engineering-focused view under: + +```text +Devices → Connectivity View +``` + +It may show: + +* Gateway uplinks +* Switch uplinks +* AP uplinks +* Mesh links +* WAN connectivity +* L2/L3 relationships +* Port connectivity +* Logical network graph + +This view is intended mainly for NOC, engineering, and advanced troubleshooting roles. + +--- + +## 12.5 Inventory Validation + +Backend must validate: + +* Device belongs to allowed scope +* Serial number uniqueness +* Configuration scope compatibility +* Contact/location scope compatibility +* Assignment target is inside the user's allowed subtree + +--- + +# 13. Client Management + +## 13.1 Client Domain + +Clients are end-user/mobile/endpoint devices and should exist as a separate operational domain from infrastructure devices. + +Examples: + +* Phones +* Laptops +* Tablets +* IoT endpoints +* Printers +* TVs + +--- + +## 13.2 Client Module Structure + +Recommended structure: + +```text +Clients + ├── Active Clients + ├── Historical Clients + ├── Client Sessions + ├── Wireless Experience + ├── Roaming + ├── Client Analytics + └── Troubleshooting +``` + +--- + +## 13.3 Client Characteristics + +Clients are: + +* Transient +* Session-oriented +* High-volume +* Analytics-focused +* Wireless-experience-focused + +Clients should appear in topology primarily as: + +* Counts +* Overlays +* Heatmaps +* Density visualization +* Roaming visualization + +Clients should not appear as default topology graph nodes. + +--- + +## 13.4 Client RBAC and Scope + +Client visibility must follow the selected hierarchy scope and RBAC rules. + +A user can only view clients connected within the user's allowed subtree. Unauthorized clients and client sessions must not appear in lists, searches, topology overlays, AI context, or analytics. + +--- + +# 14. Configuration Management + +## 14.1 Configuration Sets + +Frontend exposes: + +```text +Configuration Set +``` + +Internally backed by OWPROV DeviceConfiguration. + +--- + +## 14.2 Supported Features + +* Create configuration set +* Edit configuration set +* Versioning +* Assign to nodes/devices +* Preview effective configuration +* Rollout configuration +* Rollback configuration +* Staged/phased deployment + +--- + +## 14.3 Rollout Lifecycle States + +Supported rollout states: + +```text +pending +successful +failed +``` + +--- + +## 14.4 Staged/Phased Rollouts + +The platform should support staged/phased rollouts. + +Example: + +```text +Stage 1: + 10 devices + +Stage 2: + 100 devices + +Stage 3: + Remaining devices +``` + +Supported rollout modes: + +* Immediate rollout +* Scheduled rollout +* Staged/phased rollout + +The rollout UI should support: + +* Stage visibility +* Per-stage progress +* Retry actions +* Rollback actions +* Rollout cancellation +* AI-assisted rollout failure explanation when permitted + +--- + +# 15. Billing and Subscription Management + +## 15.1 Billing Plan Ownership + +Billing plans are owned and managed by parent operators for their direct child customers/sub-operators. + +A parent operator may: + +* Create billing plans +* Edit billing plans +* Activate/deactivate billing plans +* Assign plans to direct child customers/sub-operators +* Control billing visibility within its subtree +* View subscription status for direct child customers/sub-operators when permitted + +A child customer/sub-operator may: + +* Log in +* View plans assigned or offered by its parent operator +* Select one eligible active billing plan +* View current subscription/billing status +* Manage billing details according to permissions + +A child customer/sub-operator cannot: + +* Modify parent-created billing plans +* Create billing plans outside its allowed scope +* View sibling customer subscriptions +* View sibling billing plan assignments +* View parent-private billing plans + +--- + +## 15.2 Billing Plan Model + +Operators can create two types of billing plans: + +```text +connection_based +fixed_device +``` + +Plan type behavior: + +* `connection_based` plan charges based on the number of connected devices per month. +* `fixed_device` plan assigns a fixed device limit and may be monthly, yearly, or free. + +Recommended billing plan structure: + +```json +{ + "id": "plan-pro-1", + "name": "Professional Plan", + "status": "active", + "type": "fixed_device", + "description": "Professional deployment package", + "features": [ + "500 APs", + "Topology", + "Advanced Metrics" + ], + "limits": { + "devices": 500, + "users": 100 + }, + "billing": { + "cycle": "monthly", + "connectionBased": false + }, + "price": { + "currency": "USD", + "amount": 199 + } +} +``` + +Example connection-based billing plan: + +```json +{ + "id": "plan-connection-1", + "name": "Connection Based Plan", + "status": "active", + "type": "connection_based", + "description": "Monthly billing based on connected devices", + "features": [ + "Connected device billing", + "Topology", + "Basic Metrics" + ], + "limits": { + "devices": null, + "users": 100 + }, + "billing": { + "cycle": "monthly", + "connectionBased": true, + "pricePerConnectedDevice": 2 + }, + "price": { + "currency": "USD", + "amount": 0 + } +} +``` + +Plan status values: + +```text +active +inactive +draft +archived +``` + +Billing cycle values: + +```text +monthly +yearly +free +``` + +Only active and eligible plans should be selectable by a child customer/sub-operator. + +--- + +## 15.3 Subscription Model + +Each customer/sub-operator may have one active billing subscription at a time. + +Recommended subscription structure: + +```json +{ + "id": "subscription-1", + "customerId": "customer-a1", + "planId": "plan-pro-1", + "status": "active", + "startedAt": "2026-01-01T00:00:00Z", + "renewalAt": "2026-02-01T00:00:00Z" +} +``` + +Subscription states: + +```text +active +inactive +pending +suspended +expired +cancelled +``` + +The UI must clearly show the current subscription state and must prevent selecting more than one active plan at the same time. + +--- + +## 15.4 Billing APIs + +Frontend billing APIs: + +```http +POST /api/v1/mdu/billing/plans +GET /api/v1/mdu/billing/plans +GET /api/v1/mdu/billing/available-plans +POST /api/v1/mdu/billing/subscription/select-plan +GET /api/v1/mdu/billing/subscription +``` + +Recommended behavior: + +* `POST /api/v1/mdu/billing/plans` creates a fixed-device or connection-based plan within the caller's allowed operator scope. +* `GET /api/v1/mdu/billing/plans` returns plans the caller is allowed to manage or view. +* `GET /api/v1/mdu/billing/available-plans` returns only eligible active plans offered by the parent scope. +* `POST /api/v1/mdu/billing/subscription/select-plan` selects one eligible active plan for the current customer/sub-operator. +* `GET /api/v1/mdu/billing/subscription` returns the current subscription/billing status for the caller's allowed scope. + +The frontend should interact only with MDU billing APIs and should not directly access internal billing providers, OWPROV billing internals, payment processors, or backend billing implementation details. + +--- + +## 15.5 Billing RBAC Rules + +RBAC behavior: + +* Parent operator can create, edit, activate, deactivate, and assign billing plans for direct child operators/customers. +* Child operator can only view available plans from its parent scope. +* Child operator can select one eligible active plan. +* Child operator cannot modify parent-created billing plans. +* Child operator cannot view sibling billing plans or subscriptions. +* Child operator cannot select inactive, suspended, archived, or unauthorized plans. +* Billing plan and subscription APIs must enforce backend authorization even when UI actions are hidden. + +--- + +## 15.6 Billing UI Features + +Operator billing UI features: + +* Billing plan list +* Create/edit billing plan +* Select billing plan type: connection-based or fixed-device +* Configure connection-based monthly device charge +* Configure fixed-device limit and billing cycle: monthly, yearly, or free +* Activate/deactivate plans +* Assign plans to direct child customers/sub-operators +* Subscription visibility dashboard +* Filter subscriptions by child customer/sub-operator +* View current plan and subscription state for allowed child scopes +* AI-assisted subscription risk summary when permitted + +Customer/sub-operator billing UI features: + +* Available plan list +* Current subscription view +* Plan selection +* Billing status visibility +* Subscription details +* Clear disabled/hidden state for unauthorized billing actions + +--- + +## 15.7 Billing Scope Isolation + +Billing visibility follows subtree isolation rules. + +Example: + +```text +Operator A + ├── Customer A1 + └── Customer A2 +``` + +Rules: + +```text +Customer A1 cannot view: + - Customer A2 subscription + - Customer A2 plan assignments + - Operator private plans + - Billing plans outside the parent-approved scope +``` + +Billing scope resolution must follow the same hierarchy isolation model used throughout the MDU platform. + +--- + +## 15.8 Billing Error and Empty-State UX + +Billing screens should handle: + +* No available plans +* No active subscription +* Inactive or expired subscription +* Suspended billing status +* Unauthorized plan selection +* Backend 403 permission denial +* Backend 409 conflict when another active subscription already exists +* Fixed-device plan limit exceeded + +Recommended messages: + +```text +No billing plans are currently available for your account. +``` + +```text +You do not have permission to manage this billing plan. +``` + +```text +Only one active billing plan can be selected at a time. +``` + +```text +This plan does not allow more connected devices. +``` + +--- + + +# 16. Maps and Topology + +## 16.1 Maps Module Purpose + +The Maps module is a standalone operational module for managing map assets. + +It may include: + +* Map list +* Upload map +* Edit map metadata +* Associate map with node/venue/floor +* Manage map visibility + +Topology should not be a standalone root sidebar module. Topology should appear as a contextual workspace tab after the user selects a hierarchy node. + +```text +Maps = map asset management +Topology = contextual visualization inside a selected hierarchy workspace +``` +--- + +## 16.2 Supported Map Types + +The MDU UI map system supports: + +* png +* jpg +* jpeg +* svg +* pdf + +Unsupported formats: + +* dwg +* dxf +* geojson +* advanced GIS/CAD formats + +--- + +## 16.3 Venue Multi-Floor Support + +A venue may contain multiple floors/maps. + +Example: + +```text +Venue + ├── Floor 1 map + ├── Floor 2 map + └── Floor 3 map +``` + +This supports: + +* Apartment deployments +* Hotels +* Office buildings +* Malls +* Campus deployments + +--- + +## 16.4 Coordinate System + +Device placement coordinates should support both: + +* Normalized coordinates +* Rendered pixel coordinates + +Internal storage: + +```text +Normalized coordinates (0.0–1.0) +``` + +Rendering: + +```text +Frontend dynamically converts normalized coordinates into pixels. +``` + +Example: + +```json +{ + "x": 0.42, + "y": 0.67 +} +``` + +Benefits: + +* Resolution-independent rendering +* Responsive UI scaling +* Zoom compatibility +* SVG/PDF scaling compatibility +* Multi-device compatibility + +--- + +## 16.5 Device Placement Model + +Supported overlay objects: + +* Gateways +* Switches +* Access Points +* Client counts +* Client density +* Wireless links +* Uplink/downlink paths +* Venue hierarchy visualization + +Recommended placement object: + +```json +{ + "deviceId": "ap-1", + "deviceType": "access-point", + "x": 0.42, + "y": 0.67, + "rotation": 90, + "status": "online" +} +``` + +--- + +## 16.6 Topology Overlay Behavior + +Topology overlays should support: + +* Complete venue structure visualization +* Device hierarchy visualization +* AP placement +* Switch placement +* Gateway placement +* Client count overlays +* Client density visualization +* Wireless quality visualization +* Online/offline state visualization +* Uplink/downlink visualization +* Interactive device selection +* AI-assisted topology analysis when permitted + +--- + +## 16.7 Map Interaction Features + +The frontend should support: + +* Zoom in/out +* Pan +* Fit-to-screen +* Floor switching +* Overlay toggles +* Device selection +* Device hover states +* Responsive scaling + +--- + +## 16.8 Topology by Hierarchy Level + +Topology behavior should adapt to the selected hierarchy level: + +* Site level: building summaries, aggregate health, deployment overview, regional metrics +* Building level: floor structure, distribution switches, AP density, backbone connectivity +* Tower level: floor relationships, AP distribution, tower-level health, aggregation links +* Floor level: floor maps, AP placement, wireless overlays, client density, wireless quality, roaming visualization +* Venue level: detailed operational topology, overlays, client relationships, AP/client behavior, coverage visualization, wireless experience metrics + +--- + +# 17. UI Modules + +## 17.1 Dashboard + +Dashboard includes: + +* Customer count +* Device count +* Client count +* Venue count +* Health summary +* Billing/subscription summary when permitted +* Recent alerts +* Recent rollouts +* AI-generated operational insights when enabled + +--- + +## 17.2 Customers/Sub-Operators + +Features: + +* List customers +* Create customer/sub-operator +* Edit customer +* Suspend customer +* Delete customer +* Navigate subtree +* View customer health summary +* Generate customer health summary using AI when permitted + +--- + +## 17.3 Hierarchy + +The Hierarchy module is the primary operational subtree navigation workspace. + +Features: + +* Recursive hierarchy tree +* Node detail +* Node hierarchy +* Selected-scope context +* Contextual workspace tabs +* Overview tab +* Topology tab +* Effective configuration tab +* Metrics tab +* AI Insights tab when enabled + +--- + +## 17.4 Devices + +Features: + +* Gateway management +* Switch management +* Access point management +* Inventory +* Firmware +* Assignments +* Device actions +* Device metrics +* Connectivity View +* AI-assisted device diagnostics when enabled + +--- + +## 17.5 Clients + +Features: + +* Active clients +* Historical clients +* Client sessions +* Wireless experience +* Roaming visibility +* Client analytics +* Troubleshooting +* Client overlays in topology + +--- + +## 17.6 Configurations + +Features: + +* Configuration sets +* Templates +* Overrides +* Rollouts +* Assignment management +* Effective configuration preview + +--- + +## 17.7 Rollouts + +Features: + +* Rollout list +* Rollout detail +* Immediate rollout +* Scheduled rollout +* Staged/phased rollout +* Per-stage progress +* Retry/rollback/cancel actions +* AI-assisted rollout failure explanation when permitted + +--- + +## 17.8 Maps + +Features: + +* Map list +* Upload map +* Edit map metadata +* Associate map with node/venue/floor +* Visibility management +* Map preview + +--- + +## 17.9 Billing + +Features: + +* Billing plan management +* Subscription management +* Plan selection +* Billing status visibility +* Parent-child plan assignment +* Subscription visibility dashboard +* Billing RBAC behavior +* AI-assisted subscription risk summary when enabled + +--- + +## 17.10 Users + +Features: + +* User list +* Create user +* Assign permission profile +* Suspend user +* Reset password +* Manage sessions +* View role/scope assignment summary + +--- + +## 17.11 Metrics + +Features: + +* Device health +* Client health +* Traffic +* Wireless quality +* Client metrics +* Billing/subscription metrics when permitted +* Rollout progress +* Hierarchy-scoped metric filtering + +--- + +## 17.12 AI Agent + +Features: + +```text +AI Agent + ├── Ask Anything + ├── Investigations + ├── Recommendations + ├── Automations + ├── Playbooks + └── Agent Activity +``` + +The AI Agent must remain RBAC-aware and scope-aware. + +--- + +## 17.13 Administration + +Features: + +* Platform settings +* Operator administration +* Permission profile administration +* Audit views +* Advanced/debug views when permitted + +--- + +# 18. RBAC UX Behavior + +## 18.1 Hidden vs Disabled Actions + +The UI should primarily use hidden actions for unauthorized operations. + +Behavior: + +```text +If user lacks permission: + hide action completely +``` + +Examples: + +* Delete buttons hidden +* Create customer hidden +* Rollout actions hidden +* Billing plan create/edit hidden +* User management hidden +* AI action hidden when the AI context would include unauthorized data + +The frontend must still rely on backend authorization validation. + +--- + +## 18.2 Permission Denied UX + +If backend denies an operation: + +```text +403 Forbidden +``` + +The UI should: + +* Show contextual permission-denied message +* Preserve current screen state +* Avoid redirect loops +* Avoid blank/error-only screens + +Recommended message: + +```text +You do not have permission to perform this action within the current scope. +``` + +--- + +## 18.3 Scoped Dropdown Behavior + +All hierarchy/resource dropdowns must only load resources from the user's allowed subtree. + +Examples: + +* Venue selector +* Node selector +* User assignment selector +* Device assignment selector +* Configuration assignment selector +* Billing plan assignment selector +* Subscription customer selector +* AI context selector + +Behavior: + +```text +Only allowed subtree items are returned. +Unauthorized resources are never shown. +``` + +--- + +## 18.4 Subtree Switching UX + +The platform should support both: + +* Persistent hierarchy-tree navigation +* Breadcrumb/dropdown subtree switching +* Top context bar selected-scope switching + +Desktop behavior: + +* Operational left sidebar +* Collapsible hierarchy tree where appropriate +* Top context bar +* Breadcrumb synchronization +* Context-aware navigation + +Mobile/tablet behavior: + +* Collapsed operational navigation +* Collapsed hierarchy drawer +* Breadcrumb navigation +* Dropdown subtree switcher + +Navigation state must remain synchronized across: + +* Hierarchy tree +* Breadcrumbs +* Top context bar +* Route context +* Selected subtree +* Operational workspace + +--- + +## 18.5 RBAC for AI + +AI prompts, recommendations, and automation plans must only use data from the user's allowed scope. + +AI must not: + +* Expose sibling subtree information +* Expose unauthorized billing data +* Expose unauthorized device inventory +* Expose unauthorized client sessions +* Recommend actions outside the user's allowed scope + +AI-generated operational actions should follow: + +```text +AI Suggestion + → Review Plan + → Approve Action + → Execute Workflow + → Track Result +``` + +--- + +# 19. Role-Based Navigation + +## 19.1 Root Admin + +Can access: + +* Operators +* All customers +* All subtrees +* Global metrics +* Platform administration +* Billing administration where permitted +* AI Agent where enabled + +--- + +## 19.2 Operator Admin + +Can access: + +* Own operator subtree +* Direct and nested child customers/sub-operators when permitted +* Hierarchy +* Devices +* Clients +* Users +* Configuration +* Rollouts +* Maps +* Billing plans and subscriptions for allowed child scopes +* Metrics +* AI Agent/contextual AI actions when enabled + +Cannot access: + +* Another operator subtree +* Unauthorized sibling/parent scopes +* Billing data outside allowed scope + +--- + +## 19.3 Customer/Sub-Operator Admin + +Can access: + +* Own subtree +* Child customers/sub-operators when permitted +* Own users +* Own devices +* Own clients +* Own venues +* Own configurations +* Own maps +* Available billing plans from parent scope +* Own subscription status +* AI Agent/contextual AI actions when enabled and scoped + +Cannot access: + +* Parent resources unless explicitly allowed +* Sibling subtrees +* Parent-private billing plans +* Sibling billing plans or subscriptions +* Unauthorized AI context + +--- + +## 19.4 Installer + +Can access limited operational workflows based on permission profile, usually: + +* Assigned hierarchy scopes +* Device installation/assignment +* Maps/topology views needed for installation +* Limited device actions + +Cannot access billing or administrative user management unless explicitly granted. + +--- + +## 19.5 NOC + +Can access operational monitoring and troubleshooting workflows based on permission profile, usually: + +* Devices +* Clients +* Metrics +* Rollouts +* Connectivity View +* Contextual AI diagnostics when enabled + +Cannot manage billing plans unless explicitly granted. + +--- + +## 19.6 Read-only + +Can view allowed data within assigned scope. + +Cannot create, update, delete, assign, select billing plans, execute device actions, or approve AI-generated workflow actions. + +--- + +# 20. API Design Philosophy + +## 20.1 Frontend Uses Only MDU APIs + +Frontend should use: + +```text +/api/v1/mdu/* +``` + +Frontend should not directly call: + +* OWPROV entity APIs +* OWPROV venue APIs +* OWPROV role APIs +* OWPROV policy APIs +* Internal billing provider APIs +* Internal AI provider APIs + +Authentication APIs are the only exception. + +--- + +## 20.2 Response Format + +Recommended response format: + +```json +{ + "code": 0, + "message": "ok", + "data": {} +} +``` + +--- + +## 20.3 Scoped API Behavior + +All MDU APIs should resolve scope from: + +* Authenticated user +* Selected hierarchy context +* Route/resource parameters +* Backend RBAC rules + +Unauthorized resources should not be returned in API responses. + +--- + +## 20.4 Navigation Bootstrap API + +The frontend should be able to bootstrap allowed navigation and default selected scope after login. + +Recommended API: + +```http +GET /api/v1/mdu/bootstrap +``` + +Recommended response includes: + +* User summary +* Allowed modules +* Default selected scope +* Allowed hierarchy roots +* Feature flags +* Role/permission summary + +--- + +# 21. UI Technology Expectations + +Recommended stack: + +* React +* TypeScript +* TailwindCSS +* TanStack Query +* Zustand or Context API +* React Router +* OpenAPI-generated API clients + +--- + +# 22. Recommended Frontend Structure + +```text +src/ + ├── app/ + ├── api/ + ├── auth/ + ├── components/ + ├── layouts/ + ├── navigation/ + ├── hierarchy/ + ├── pages/ + ├── modules/ + │ ├── dashboard/ + │ ├── customers/ + │ ├── hierarchy/ + │ ├── devices/ + │ ├── clients/ + │ ├── configurations/ + │ ├── rollouts/ + │ ├── maps/ + │ ├── billing/ + │ ├── users/ + │ ├── metrics/ + │ ├── ai-agent/ + │ └── administration/ + ├── hooks/ + ├── state/ + ├── types/ + ├── routes/ + ├── utils/ + └── styles/ +``` + +--- + +# 23. Security and Session Behavior + +## 23.1 Token Storage + +Recommended token handling: + +```text +Access token: + stored in memory only + +Refresh token: + stored in secure HttpOnly cookie +``` + +The frontend should avoid storing long-lived tokens in localStorage. + +--- + +## 23.2 Session Lifetime + +Session configuration: + +```text +Access token lifetime: + 15 minutes + +Refresh token lifetime: + 7 days + +Idle timeout: + 30 minutes + +Absolute session timeout: + 12 hours +``` + +--- + +## 23.3 Refresh Behavior + +Behavior: + +```text +1 automatic refresh retry +``` + +If refresh fails: + +```text +- clear local session state +- synchronize logout across tabs +- redirect to login page +``` + +--- + +## 23.4 Multi-Tab Session Synchronization + +If logout/session expiry occurs in one tab: + +```text +all tabs must logout automatically +``` + +--- + +## 23.5 CSRF/CORS Assumptions + +Frontend assumes: + +* OWSEC supports secure CORS configuration +* Refresh cookie uses Secure + HttpOnly + SameSite protections +* Backend APIs validate bearer tokens +* Session refresh endpoints are CSRF-protected when cookies are used + +--- + +## 23.6 Audit Logging + +The platform should support backend audit logging for: + +* Login/logout +* Customer creation +* User creation +* Role changes +* Rollouts +* Configuration changes +* Device actions +* Billing plan changes +* Subscription changes +* AI-generated recommendation approvals/actions +* Permission failures + +--- + +# 24. Acceptance Requirements + +## 24.1 Authentication + +Acceptance checks: + +* User can login directly through OWSEC. +* User can refresh session without MDU backend. +* Logout propagates across all browser tabs. +* Session expiry redirects user to login. +* Invalid refresh token clears session state. + +--- + +## 24.2 Scope Isolation + +Acceptance checks: + +* Customer admin cannot see sibling customer in node tree. +* Customer admin cannot assign device outside subtree. +* Customer admin cannot view clients outside subtree. +* Customer admin cannot load unauthorized venues in dropdowns. +* Customer admin cannot view parent subtree unless explicitly allowed. +* Unauthorized resources never appear in dropdown/search responses. + +--- + +## 24.3 RBAC Behavior + +Acceptance checks: + +* Unauthorized actions are hidden. +* Backend 403 responses show contextual permission messages. +* Navigation updates according to subtree context. +* Role changes update visible navigation/actions after refresh. +* AI actions are hidden when user lacks required scope or permission. + +--- + +## 24.4 Backend Outage Behavior + +Acceptance checks: + +* Login/logout continues while MDU backend is unavailable. +* UI shell/navigation still renders. +* Data pages show service unavailable state. +* Retry button is available. +* UI performs automatic retry attempts. +* No stale/cached business data is displayed unless clearly marked and allowed. + +--- + +## 24.5 Information Architecture and Navigation + +Acceptance checks: + +* Left sidebar contains only operational modules. +* Top context bar shows the selected hierarchy scope. +* Hierarchy tree, breadcrumbs, selected subtree, route context, and workspace context remain synchronized. +* Selecting a hierarchy node updates all scoped modules. +* Desktop layouts support recursive hierarchy navigation. +* Mobile layouts support subtree switching. +* Selected subtree persists during route navigation. +* Topology does not appear as a standalone root sidebar module. + +--- + +## 24.6 Maps and Topology + +Acceptance checks: + +* Multi-floor venue maps render correctly. +* Device overlays scale correctly during zoom. +* Device coordinates remain accurate after resize. +* Topology renders as a contextual tab for the selected hierarchy node. +* Venue topology is the default topology experience. +* Device connectivity topology is available from Devices → Connectivity View for permitted roles. +* Supported map types upload successfully. + +--- + +## 24.7 Devices and Clients + +Acceptance checks: + +* Devices module shows infrastructure devices only. +* Clients module exists separately from Devices. +* Clients appear in topology as counts, overlays, heatmaps, density, or roaming visualization. +* Clients do not appear as default topology graph nodes. +* Client visibility follows subtree and RBAC rules. + +--- + +## 24.8 Rollouts + +Acceptance checks: + +* Rollout supports staged deployment. +* Rollout states update correctly. +* Failed rollout displays actionable status. +* Rollback actions are visible after failure. +* Stage progress is visible in UI. +* AI can explain rollout failure only when enabled and authorized. + +--- + +## 24.9 Billing and Subscription Management + +Acceptance checks: + +* Parent operator can create billing plans. +* Parent operator can assign billing plans to direct child customers/sub-operators. +* Child customer can only view plans from parent scope. +* Child customer cannot modify parent-created plans. +* Child customer cannot view sibling subscriptions. +* Customer can select one active billing plan. +* Subscription state updates correctly in UI. +* Unauthorized billing resources never appear in API responses. +* AI subscription risk summaries do not include unauthorized billing data. + +--- + +## 24.10 AI Agent and Contextual AI + +Acceptance checks: + +* AI Agent appears as a module only for authorized users. +* Contextual AI actions appear only where supported and authorized. +* AI uses the selected hierarchy scope as context. +* AI does not expose sibling subtree data. +* AI does not expose unauthorized billing, device, or client data. +* AI-generated operational plans remain reviewable/editable before execution. + +--- + +# 25. Future Backend Alignment + +Current UI specification is intentionally backend-abstraction-first. + +As the MDU backend API evolves: + +* openapi.yaml will be aligned with production contracts +* screens.yaml bindings will be updated +* validation rules will be tightened +* metrics schemas will be finalized +* rollout APIs will be finalized +* billing APIs will be finalized +* client analytics APIs will be finalized +* AI Agent APIs and approval workflows will be finalized if enabled + +The frontend architecture should remain stable because it already abstracts OWPROV internals behind MDU APIs and separates operational navigation from hierarchy scope navigation. + +--- + +# 26. Final Summary + +The MDU platform is a recursive multi-tenant management system. + +Core principles: + +```text +Frontend directly authenticates through OWSEC. +Frontend uses only MDU business APIs. +MDU backend orchestrates OWSEC + OWPROV. +OWPROV remains source of truth for hierarchy and RBAC. +Customer/sub-operator hierarchy is recursive. +Each subtree is isolated. +Frontend uses business abstractions instead of OWPROV internals. +Operational navigation is separate from hierarchy scope navigation. +Topology is a contextual hierarchy view, not a root sidebar module. +Devices and clients are separate operational domains. +AI remains RBAC-aware and scope-aware. +``` + +The resulting UI provides: + +* Multi-tenant administration +* Recursive customer/sub-operator management +* Hierarchy-first navigation +* Top context bar selected-scope model +* Contextual hierarchy workspaces +* Venue and device management +* Separate client management +* Configuration and rollout management +* Billing and subscription management +* Contextual maps and topology +* Device connectivity topology for advanced troubleshooting +* AI Agent and contextual AI workflows +* RBAC-aware navigation +* Secure tenant isolation +* Scalable hierarchical management +* Stable frontend architecture independent of OWPROV internals diff --git a/ui-docs/plan-phases/layout-system.md b/ui-docs/plan-phases/layout-system.md new file mode 100644 index 0000000..ebe54ec --- /dev/null +++ b/ui-docs/plan-phases/layout-system.md @@ -0,0 +1,910 @@ +# MDU UI - Layout System + +## 1. Purpose + +This document defines the reusable layout patterns for the first-phase MDU UI. + +It follows: + +```text +mdu-ui-spec.md +workflows.md +figma-navigation-model.md +screen-inventory.md +screen-definitions.md +``` + +Goal: + +```text +Do not design every screen from scratch. +Use reusable layouts for repeated screen patterns. +``` + +This document feeds the next phase: + +```text +wireframe-plan.md +``` + +--- + +## 2. Phase Scope + +### Included modules + +```text +Global Shell +Authentication +Dashboard +Hierarchy +Topology +Devices +Configuration +Customers / Sub-Operators +Billing +Users +Administration +``` + +### Deferred modules + +```text +Clients +Rollouts +Maps +Metrics +AI Agent +``` + +Deferred modules should not be expanded in this layout phase. + +--- + +## 3. Core Rules + +### 3.1 Navigation model + +```text +Top App Header = GLOBAL product controls +Sidebar = WHAT the user wants to do +Scope Breadcrumb Bar = WHERE the user is working +Workspace Tabs = HOW the user works inside the selected scope +``` + +### 3.2 Top App Header + +Contains: + +```text +Logo +Global search +Notifications +Help +User profile +``` + +The Top App Header does not control hierarchy scope. + +### 3.3 Scope Breadcrumb Bar + +Shows and controls the selected working scope: + +```text +Operator > Customer > Sub-Operator > Site > Building > Floor > Venue +``` + +Changing this scope refreshes all scoped module data. + +### 3.4 Scope-first loading + +Every scoped screen must follow: + +```text +Open screen +-> Resolve selected scope from Scope Breadcrumb Bar +-> Load authorized data only +-> Show authorized actions only +``` + +### 3.5 RBAC behavior + +Layouts must support: + +```text +Visible +Hidden +Disabled +Read-only +No permission +``` + +Default rules: + +```text +Unauthorized module = hidden +Unauthorized action = hidden +Read-only = visible but not editable +Backend 403 = no-permission state +``` + +### 3.6 System states + +Every layout must support: + +```text +Loading +Empty +Error +No Permission +Backend Unavailable +Partial Data +Success +Confirmation Required +``` + +--- + +## 4. Layout List + +| ID | Layout | Purpose | +|---|---|---| +| LYT-001 | App Shell | Shared authenticated frame. | +| LYT-002 | Auth | Login and session screens. | +| LYT-003 | Dashboard | Summary cards, alerts, health, quick actions. | +| LYT-004 | Hierarchy Workspace | Hierarchy tree plus node workspace. | +| LYT-005 | List + Detail | Tables, filters, detail drawers/pages. | +| LYT-006 | Form + Confirmation | Create, edit, assign, move, delete, confirm flows. | +| LYT-007 | Topology Canvas | Hierarchy topology and device connectivity views. | +| LYT-008 | System State | Loading, empty, error, no-permission, backend-down states. | + +These eight layouts are enough for the first-phase UI. + +--- + +# 5. LYT-001 - App Shell + +## Purpose + +Provides the shared frame for authenticated screens. + +## Used by + +```text +Dashboard +Hierarchy +Devices +Configuration +Customers +Billing +Users +Administration +``` + +## Structure + +```text ++-------------------------------------------------------------+ +| Top App Header: Logo | Search | Notifications | Help | User | ++----------------------+--------------------------------------+ +| Sidebar | Scope Breadcrumb Bar | +| | Operator > Customer > Site > Floor | +| +--------------------------------------+ +| | Main Workspace | ++----------------------+--------------------------------------+ +``` + +## Required regions + +| Region | Purpose | +|---|---| +| Top App Header | Global product controls. | +| Sidebar | Operational modules. | +| Scope Breadcrumb Bar | Current working scope and scope switching. | +| Main Workspace | Page content. | +| Optional Drawer | Details, filters, confirmations, related context. | + +## Rules + +- Sidebar shows operational modules only. +- Topology is not a root sidebar module. +- Scope Breadcrumb Bar controls selected scope. +- Unauthorized sidebar modules are hidden. +- On mobile, sidebar becomes drawer and Scope Breadcrumb Bar becomes compact selector. + +## Figma components + +```text +Shell/TopAppHeader +Shell/Sidebar +Shell/SidebarItem +Shell/ScopeBreadcrumbBar +Shell/MainWorkspace +Shell/UserProfileMenu +Shell/GlobalSearchOverlay +``` + +--- + +# 6. LYT-002 - Auth + +## Purpose + +Supports unauthenticated and session-related screens. + +## Used by + +```text +Login +Forgot Password +Reset Password +Change Password +Session Expired +Logout Processing +Backend Bootstrap Failed +``` + +## Structure + +```text ++-------------------------------------------------------------+ +| Brand / Product Identity | ++-------------------------------------------------------------+ +| Auth Card | +| Title | +| Form Fields | +| Primary Action | +| Secondary Links | ++-------------------------------------------------------------+ +``` + +## Rules + +- No sidebar before authentication. +- No hierarchy scope before backend bootstrap. +- OWSEC authentication can work even when MDU backend is unavailable. +- Do not reveal whether an account exists during password reset. + +## States + +```text +Submitting +Invalid credentials +Account locked +OWSEC unavailable +Backend bootstrap failed +Session expired +Password reset success +``` + +--- + +# 7. LYT-003 - Dashboard + +## Purpose + +Shows operational summary for global or selected scope. + +## Used by + +```text +Global Dashboard +Scoped Dashboard +Health Summary Panel +Recent Alerts Panel +Billing Summary Panel +``` + +## Structure + +```text ++-------------------------------------------------------------+ +| Page Header: Dashboard title, selected scope, last updated | ++-------------------------------------------------------------+ +| KPI Cards | +| Customers | Sites | Devices | Users | Alerts | Billing | ++-------------------------------------------------------------+ +| Health Summary | Recent Alerts | ++-------------------------------------------------------------+ +| Device Summary / Activity | Quick Actions | ++-------------------------------------------------------------+ +``` + +## Recommended content + +```text +Customer/site/building/floor/venue counts +Device count and health +User count +Recent alerts +Billing summary if permitted +Quick actions if permitted +``` + +## RBAC behavior + +- Billing cards are hidden if the user lacks billing permission. +- Admin actions are hidden for non-admin users. +- Read-only users see summaries only. + +## States + +```text +Loading +Empty scope +Partial data +No permission +Backend unavailable +``` + +--- + +# 8. LYT-004 - Hierarchy Workspace + +## Purpose + +Supports recursive hierarchy navigation and node-level workspaces. + +This is the highest-priority layout because hierarchy-context complexity is the biggest UX risk. + +## Used by + +```text +Hierarchy Module +Hierarchy Tree +Node Workspace Shell +Node Overview Tab +Node Topology Tab +Node Devices Tab +Node Configurations Tab +Create Node +Edit Node +Move Node +Delete Node +``` + +## Structure + +```text ++-------------------------------------------------------------+ +| Page Header: Hierarchy | ++-------------------------------------------------------------+ +| Hierarchy Tree | Node Workspace | +| Search / Filter | Node Header | +| Recursive Tree | Workspace Tabs | +| Selected Node | Overview / Topology / Devices | ++-------------------------------------------------------------+ +``` + +## Workspace tabs for this phase + +```text +Overview +Topology +Devices +Configurations +``` + +Deferred tabs: + +```text +Clients +Maps +Metrics +AI Insights +``` + +## Tree behavior + +The tree must support variable depth: + +```text +Operator +-> Customer + -> Sub-Operator + -> Site + -> Building + -> Tower + -> Floor + -> Venue +``` + +Rules: + +- Tree shows allowed nodes only. +- Selected node is highlighted. +- Tree selection updates the Scope Breadcrumb Bar. +- Scope Breadcrumb Bar selection updates the tree. +- Tabs adapt by node type, permissions, and available data. + +## States + +```text +Tree loading +Node loading +Empty hierarchy +No selected node +Node unavailable +No permission +Backend unavailable +Partial data +``` + +--- + +# 9. LYT-005 - List + Detail + +## Purpose + +Reusable layout for resource lists, tables, filters, and detail inspection. + +## Used by + +```text +Customer List +Device Inventory +Gateway / Switch / AP Lists +Configuration List +Billing Plan List +Subscription Visibility Dashboard +User List +Audit Logs +``` + +## Structure + +```text ++-------------------------------------------------------------+ +| Page Header: title, scope, primary action | ++-------------------------------------------------------------+ +| Filter Bar: search, filters, sort | ++-------------------------------------------------------------+ +| Table / List | +| Rows, columns, status, actions | ++-------------------------------------------------------------+ +| Optional Detail Drawer / Detail Page | ++-------------------------------------------------------------+ +``` + +## Common columns + +| Module | Typical columns | +|---|---| +| Customers | Name, status, parent scope, subscription, users, devices. | +| Devices | Name, type, serial, status, assignment, firmware, last seen. | +| Configurations | Name, version, status, assignments, updated date. | +| Billing Plans | Name, type, status, cycle, price, limits. | +| Users | Name, email, role/profile, status, scope. | +| Audit Logs | Time, actor, action, resource, scope, result. | + +## Rules + +- Lists show only authorized resources. +- Primary create action is hidden if not permitted. +- Row actions are RBAC-aware. +- Destructive actions open confirmation. +- Empty lists use System State layout. + +## States + +```text +Loading +Empty +No search results +No permission +Backend unavailable +Partial data +Row action failed +``` + +--- + +# 10. LYT-006 - Form + Confirmation + +## Purpose + +Reusable layout for create, edit, assignment, move, delete, and confirmation flows. + +## Used by + +```text +Create Customer +Edit Customer +Create Node +Move Node +Add Device +Assign Device +Create Configuration +Assign Configuration +Create Billing Plan +Assign Plan to Customer +Create User +Assign Role/Profile +Edit Role/Policy +Confirmation Dialogs +``` + +## Modal structure + +```text ++-------------------------------------------+ +| Header: title, close | ++-------------------------------------------+ +| Body: fields, validation, warnings | ++-------------------------------------------+ +| Footer: Cancel | Primary Action | ++-------------------------------------------+ +``` + +## Wizard structure + +```text ++-------------------------------------------------------------+ +| Header: title, step indicator | ++-------------------------------------------------------------+ +| Step Content | ++-------------------------------------------------------------+ +| Footer: Back | Next | Submit | ++-------------------------------------------------------------+ +``` + +## Common wizard examples + +### Create Customer + +```text +Customer details +First admin user +Optional billing assignment +Review and create +``` + +### Create Billing Plan + +```text +Plan type +Plan details +Pricing and limits +Review and save +``` + +### Move Node / Move Device + +```text +Select new parent/scope +Validate compatibility +Review impact +Confirm move +``` + +## Rules + +- Parent scope must be visible before submit. +- Validation errors appear inline. +- Unauthorized actions are hidden before the form opens. +- Backend errors preserve entered data. +- Destructive actions require confirmation. + +## States + +```text +Loading +Submitting +Validation error +Conflict +No permission +Backend unavailable +Success +Confirmation required +``` + +--- + +# 11. LYT-007 - Topology Canvas + +## Purpose + +Supports visual topology views. + +There are two topology experiences: + +```text +Hierarchy -> Select Node -> Topology Tab +Devices -> Connectivity View +``` + +## Used by + +```text +Node Topology Tab +Contextual Venue Topology +Site-Level Topology +Building-Level Topology +Tower-Level Topology +Floor-Level Topology +Venue-Level Topology +Topology Overlay Controls +Topology Device Detail Drawer +Device Connectivity View +``` + +## Structure + +```text ++-------------------------------------------------------------+ +| Topology Header: node/scope, status, view controls | ++-------------------------------------------------------------+ +| Overlay Controls / Filters | ++-------------------------------------------------------------+ +| Canvas / Graph | +| Devices, links, markers, overlays | ++-------------------------------------------------------------+ +| Optional Detail Drawer | ++-------------------------------------------------------------+ +``` + +## Topology by level + +| Selected level | Layout behavior | +|---|---| +| Site | Building summaries and aggregate health. | +| Building | Floor structure and AP density. | +| Tower | Floor relationships and tower health. | +| Floor | Floor topology, AP placement, wireless overlays. | +| Venue | Detailed AP behavior and coverage visualization. | + +## Rules + +- Topology is not a root sidebar module. +- Device connectivity topology belongs under Devices. +- Unauthorized devices and links are hidden. +- Read-only users can view but not edit. +- Partial topology data must be clearly marked. + +## States + +```text +Loading +No topology data +No map available +Partial data +Overlay unavailable +No permission +Backend unavailable +Graph layout failed +``` + +--- + +# 12. LYT-008 - System State + +## Purpose + +Defines reusable screen states across all layouts. + +## Used by + +```text +Permission Denied +Backend Unavailable +Empty State +Loading State +Not Found +Confirmation Dialog +Backend Bootstrap Failed +Empty Hierarchy +Device Empty Inventory +Billing Conflict +No Active Subscription +``` + +## State patterns + +| State | Pattern | +|---|---| +| Loading | Skeleton inside current layout. | +| Empty | Message, explanation, permitted CTA. | +| No Permission | Safe message, no resource leak, safe navigation. | +| Backend Unavailable | Service message, retry action. | +| Error | Error summary, retry, preserve screen. | +| Partial Data | Show available data and mark failed sections. | +| Not Found | Resource unavailable without leaking details. | +| Confirmation | Review impact, confirm or cancel. | + +## Rules + +- Keep App Shell visible where possible. +- Do not flash unauthorized actions before RBAC resolves. +- Empty-state CTAs appear only if permitted. +- No-permission messages must not expose hidden resources. +- Backend-unavailable state should include retry. + +--- + +# 13. Responsive Rules + +## Desktop + +```text +Full Top App Header +Visible sidebar +Full Scope Breadcrumb Bar +Tables use full columns +Drawers can appear on the right +``` + +## Tablet + +```text +Collapsible sidebar +Compact filters +Hierarchy tree may become drawer +Tables reduce columns +``` + +## Mobile + +```text +Sidebar becomes drawer +Scope Breadcrumb Bar becomes compact selector +Tables become cards +Detail drawers become full-screen panels +Topology controls become bottom sheet +Workspace tabs scroll horizontally +``` + +--- + +# 14. Screen-to-Layout Mapping + +| Screen group | Primary layout | Secondary layout | +|---|---|---| +| Global Shell | App Shell | System State | +| Authentication | Auth | System State | +| Dashboard | Dashboard | App Shell, System State | +| Customers | List + Detail | Form + Confirmation | +| Hierarchy | Hierarchy Workspace | Topology Canvas, Form + Confirmation | +| Topology | Topology Canvas | System State | +| Devices | List + Detail | Form + Confirmation, Topology Canvas | +| Configuration | List + Detail | Form + Confirmation | +| Billing | List + Detail | Form + Confirmation, System State | +| Users | List + Detail | Form + Confirmation | +| Administration | List + Detail | Form + Confirmation, System State | + +--- + +# 15. Figma Component Set + +## Shell + +```text +Shell/TopAppHeader +Shell/Sidebar +Shell/SidebarItem +Shell/ScopeBreadcrumbBar +Shell/MainWorkspace +Shell/GlobalSearchOverlay +Shell/UserProfileMenu +``` + +## Navigation + +```text +Navigation/HierarchyTree +Navigation/HierarchyTreeNode +Navigation/WorkspaceTabs +Navigation/ActionMenu +``` + +## Content + +```text +Content/PageHeader +Content/KPICard +Content/SummaryCard +Content/StatusBadge +Content/MetadataList +Content/ActivityList +``` + +## Table + +```text +Table/DataTable +Table/FilterBar +Table/RowActions +Table/Pagination +``` + +## Forms + +```text +Form/TextInput +Form/Select +Form/ScopeSelector +Form/StepIndicator +Form/ValidationMessage +Modal/Confirmation +Modal/ImpactWarning +``` + +## Topology + +```text +Topology/Canvas +Topology/OverlayControls +Topology/Legend +Topology/DeviceMarker +Topology/Link +Topology/DetailDrawer +``` + +## States + +```text +State/Loading +State/Empty +State/NoPermission +State/BackendUnavailable +State/Error +State/PartialData +State/Confirmation +State/SuccessToast +``` + +--- + +# 16. Acceptance Checklist + +This layout system is complete when: + +- Top App Header and Scope Breadcrumb Bar are separated correctly. +- Sidebar represents operational modules only. +- Scope Breadcrumb Bar controls selected hierarchy scope. +- Topology remains contextual under Hierarchy. +- Device connectivity topology remains under Devices. +- Every first-phase screen group maps to a reusable layout. +- RBAC behavior is supported. +- Loading, empty, error, no-permission, backend-unavailable, partial-data, and confirmation states are supported. +- Responsive behavior is defined. +- Figma components are listed. +- The document is ready for `wireframe-plan.md`. + +--- + +# 17. Next Phase + +Next document: + +```text +wireframe-plan.md +``` + +It should define: + +```text +Which low-fidelity wireframes to create +Which workflow wireframes to create +Which Figma frames are required +Which prototype paths are required +Which RBAC and system states need visual frames +``` + +--- + +# 18. Final Summary + +The first-phase MDU UI should use these reusable layouts: + +```text +App Shell +Auth +Dashboard +Hierarchy Workspace +List + Detail +Form + Confirmation +Topology Canvas +System State +``` + +These layouts are enough to support the current phase while keeping the UI scalable for later modules. diff --git a/ui-docs/plan-phases/navigation-model.md b/ui-docs/plan-phases/navigation-model.md new file mode 100644 index 0000000..7d9a811 --- /dev/null +++ b/ui-docs/plan-phases/navigation-model.md @@ -0,0 +1,1175 @@ +# MDU UI - Figma Navigation Model + +## 1. Purpose + +This document defines the navigation and hierarchy-context model that should be used while creating the MDU UI wireframes and clickable prototype in Figma. + +It is the Phase 2 design document after `workflows.md`. + +It translates the completed `mdu-ui-spec.md` and `workflows.md` into a practical Figma structure for: + +* global navigation +* hierarchy scope navigation +* contextual workspaces +* module navigation +* RBAC-aware visibility +* role-based navigation +* prototype flow linking +* reusable Figma frame organization + +This document does not replace `mdu-ui-spec.md`. + +```text +mdu-ui-spec.md = source of truth +workflows.md = operational workflow source +figma-navigation-model.md = Figma navigation and prototype structure +``` + +--- + +## 2. Core Navigation Principle + +The MDU UI must separate operational navigation from hierarchy scope navigation. + +```text +Sidebar = WHAT the user wants to do +Top Context Bar = WHERE the user is working +Workspace Tabs = HOW the user views or operates inside the selected scope +``` + +This rule is mandatory for all scoped workflows. + +Before any resource workflow executes, the UI must resolve the current hierarchy scope from the Top Context Bar. + +Examples: + +```text +Devices page -> uses selected customer/site/node scope +Billing page -> uses selected customer/sub-operator scope +Configuration rollout -> uses selected hierarchy scope +Topology tab -> uses selected node/venue/floor scope +Maps module -> manages map assets within allowed scope +``` + +--- + +## 3. Figma File Structure + +Recommended Figma pages: + +```text +00 - Cover and Design Notes +01 - Navigation Architecture +02 - App Shell Components +03 - Role-Based Navigation +04 - Hierarchy Workspace +05 - Module Navigation Frames +06 - Prototype Workflows +07 - System and RBAC States +08 - Reusable Components +09 - Mobile and Responsive Navigation +``` + +### 3.1 Page Purpose + +| Figma Page | Purpose | +| ---------- | ------- | +| 00 - Cover and Design Notes | Document source, version, design principles, and scope. | +| 01 - Navigation Architecture | Sidebar, top context bar, workspace tabs, breadcrumbs, route model. | +| 02 - App Shell Components | Reusable shell layout, sidebar, header, context picker, tab bar. | +| 03 - Role-Based Navigation | Navigation visibility per role. | +| 04 - Hierarchy Workspace | Customer/site/building/tower/floor/venue workspace examples. | +| 05 - Module Navigation Frames | Dashboard, Customers, Devices, Clients, Billing, Users, etc. | +| 06 - Prototype Workflows | Clickable end-to-end flows from `workflows.md`. | +| 07 - System and RBAC States | Loading, empty, error, no permission, backend down, read-only. | +| 08 - Reusable Components | Tables, cards, breadcrumbs, tabs, filters, drawers, modals. | +| 09 - Mobile and Responsive Navigation | Drawer, compact context switcher, responsive workspace behavior. | + +--- + +## 4. Global Application Shell + +Every authenticated screen should use the same base shell. + +```text ++--------------------------------------------------------------+ +| Top Context Bar / Breadcrumb / User Actions | ++----------------------+---------------------------------------+ +| Left Sidebar | Main Workspace | +| Operational Modules | Contextual Content | +| | Workspace Tabs / Page Content | ++----------------------+---------------------------------------+ +``` + +### 4.1 Shell Regions + +| Region | Purpose | +| ------ | ------- | +| Left Sidebar | Stable operational navigation. | +| Top Context Bar | Current hierarchy scope and subtree switcher. | +| Breadcrumbs | Shows current hierarchy and route context. | +| Main Workspace | Module content rendered within current scope. | +| Workspace Tabs | Contextual tabs for selected hierarchy node. | +| Right Context Panel | Optional details, AI assistant, filters, or actions. | + +--- + +## 5. Left Sidebar Navigation + +The left sidebar should contain operational modules only. + +Recommended order: + +```text +Dashboard +Customers +Hierarchy +Devices +Clients +Configurations +Rollouts +Maps +Billing +Users +Metrics +AI Agent +Administration +``` + +### 5.1 Sidebar Module Definitions + +| Module | Meaning | +| ------ | ------- | +| Dashboard | Global or scoped operational summary. | +| Customers | Tenant, customer, and sub-operator management. | +| Hierarchy | Operational subtree navigation and contextual workspace. | +| Devices | Infrastructure devices: gateways, switches, APs, inventory, firmware, assignments. | +| Clients | End-user/mobile clients, sessions, roaming, wireless experience. | +| Configurations | Configuration sets, templates, assignments, effective configuration. | +| Rollouts | Rollout creation, staged rollout progress, rollback, failure analysis. | +| Maps | Map asset management: upload, metadata, floor/venue association, visibility. | +| Billing | Billing plans, available plans, subscription selection, subscription status. | +| Users | User lifecycle, role/profile assignment, password reset, suspension. | +| Metrics | Health, traffic, wireless quality, client experience, rollout metrics. | +| AI Agent | Ask anything, investigations, recommendations, automations, playbooks, activity. | +| Administration | Platform/admin settings, roles, policies, audit logs, advanced controls. | + +### 5.2 Sidebar Rules + +* Sidebar items represent operational domains. +* Sidebar items should remain stable regardless of hierarchy depth. +* Sidebar visibility must be RBAC-aware. +* Unauthorized modules should be hidden by default. +* Read-only users may see fewer modules and fewer actions. +* Topology must not be a root sidebar item. + +Correct: + +```text +Hierarchy -> Select Floor 12 -> Topology tab +``` + +Not recommended: + +```text +Sidebar -> Topology +``` + +--- + +## 6. Top Context Bar + +The Top Context Bar represents the selected hierarchy scope. + +Example: + +```text +Operator A / Customer B / Sunrise Towers / Tower 1 / Floor 12 +``` + +### 6.1 Purpose + +The Top Context Bar answers: + +```text +WHERE is the user currently working? +``` + +It must control the scope for scoped modules such as: + +* Devices +* Clients +* Configurations +* Rollouts +* Maps +* Billing +* Users +* Metrics +* AI Agent + +### 6.2 Required Elements + +```text +Current Scope Breadcrumb +Scope Switcher +Search within hierarchy +Recently used scopes +Scope type label +Permission indicator when useful +``` + +### 6.3 Scope Resolution Rule + +All resource workflows must resolve current scope before execution. + +Required workflow pattern: + +```text +Open module +-> Resolve current hierarchy scope from Top Context Bar +-> Load resources allowed in that scope +-> Show only authorized actions +-> Execute workflow inside resolved scope +``` + +### 6.4 Scope Error States + +The Figma prototype should include these context states: + +| State | Behavior | +| ----- | -------- | +| No scope selected | Prompt user to select a customer/site/node. | +| Scope loading | Show skeleton or loading state. | +| Scope unavailable | Show service unavailable or retry state. | +| No permission | Show permission-denied message. | +| Scope changed | Refresh module data and preserve safe UI state. | + +--- + +## 7. Hierarchy Navigation Model + +The MDU UI uses hierarchy-first navigation for contextual operations. + +Example hierarchy: + +```text +Root Operator +-> Operator + -> Customer/Sub-Operator + -> Site + -> Building + -> Tower + -> Floor + -> Venue +``` + +The hierarchy depth may vary by deployment. + +Examples: + +```text +Customer -> Venue +Customer -> Site -> Building -> Tower -> Floor -> Venue +``` + +The UI must support recursive and variable-depth hierarchy. + +--- + +## 8. Hierarchy Workspace Model + +When a user selects a hierarchy node, the workspace should change contextually. + +Example: + +```text +Selected Node: Sunrise Towers / Floor 12 +``` + +Recommended workspace tabs: + +```text +Overview +Topology +Devices +Clients +Maps +Configurations +Metrics +AI Insights +``` + +### 8.1 Tab Behavior Rules + +* Tabs are contextual to the selected node. +* Tabs are RBAC-aware. +* Tabs may differ by node type. +* Tabs may hide if capability is unavailable. +* Tabs must preserve selected scope. +* Tabs should not expose sibling or parent data unless explicitly allowed. + +### 8.2 Node-Level Workspace Examples + +| Selected Level | Recommended Tabs | +| -------------- | ---------------- | +| Customer/Sub-Operator | Overview, Devices, Clients, Billing, Users, Metrics, AI Insights | +| Site | Overview, Topology, Devices, Clients, Maps, Configurations, Metrics | +| Building | Overview, Topology, Devices, Maps, Metrics, AI Insights | +| Tower | Overview, Topology, Devices, Metrics | +| Floor | Overview, Topology, Devices, Clients, Maps, Metrics, AI Insights | +| Venue | Overview, Topology, Devices, Clients, Maps, Metrics, AI Insights | + +--- + +## 9. Customers vs Hierarchy Navigation + +The sidebar includes both `Customers` and `Hierarchy`, but they have different purposes. + +```text +Customers = tenant/customer/sub-operator management +Hierarchy = operational subtree navigation and scoped workspace +``` + +### 9.1 Customers Module + +Used for: + +* customer list +* create customer/sub-operator +* edit customer +* suspend customer +* delete customer +* customer billing summary +* customer admin overview + +### 9.2 Hierarchy Module + +Used for: + +* recursive hierarchy tree +* selected subtree navigation +* node workspace +* contextual topology +* node-scoped devices +* node-scoped clients +* node-scoped maps +* node-scoped metrics + +--- + +## 10. Maps vs Topology Navigation + +Maps and topology are related but not the same. + +```text +Maps = map asset management +Topology = contextual visualization inside selected hierarchy workspace +``` + +### 10.1 Maps Module + +The Maps module is a standalone operational module for map assets. + +Used for: + +* map list +* upload map +* edit map metadata +* associate map with node/venue/floor +* manage map visibility +* validate supported map formats + +### 10.2 Topology View + +Topology is not a root sidebar item. + +Topology appears as a workspace tab after selecting a hierarchy node. + +Correct Figma prototype path: + +```text +Sidebar -> Hierarchy -> Select Floor 12 -> Topology tab +``` + +### 10.3 Device Connectivity Topology + +Device connectivity topology is an engineering-focused view. + +Recommended path: + +```text +Sidebar -> Devices -> Connectivity View +``` + +This is separate from venue/floor topology. + +--- + +## 11. Devices vs Clients Navigation + +Devices and clients must be separate operational domains. + +```text +Devices = managed infrastructure assets +Clients = transient end-user/mobile devices and sessions +``` + +### 11.1 Devices Module + +Recommended structure: + +```text +Devices +-> Gateways +-> Switches +-> Access Points +-> Inventory +-> Firmware +-> Assignments +-> Connectivity View +``` + +### 11.2 Clients Module + +Recommended structure: + +```text +Clients +-> Active Clients +-> Historical Clients +-> Client Sessions +-> Wireless Experience +-> Roaming +-> Client Analytics +-> Troubleshooting +``` + +### 11.3 Topology Behavior + +Clients should appear in venue/floor topology primarily as: + +* counts +* overlays +* heatmaps +* density indicators +* roaming paths +* wireless experience visualizations + +Clients should not appear as default graph nodes in complex topology views. + +--- + +## 12. Billing Navigation Model + +Billing must follow parent-child scope isolation. + +### 12.1 Operator Admin Billing Navigation + +Path: + +```text +Sidebar -> Billing -> Plans +Sidebar -> Billing -> Subscriptions +Customers -> Select Customer -> Billing Summary +``` + +Operator Admin can: + +* create billing plans +* edit billing plans +* activate/deactivate plans +* assign plans to direct child customers/sub-operators +* view subscription status within allowed subtree + +### 12.2 Customer/Sub-Operator Billing Navigation + +Path: + +```text +Sidebar -> Billing -> Available Plans +Sidebar -> Billing -> Current Subscription +``` + +Customer/Sub-Operator Admin can: + +* view eligible plans offered by parent scope +* select one active billing plan +* view current subscription status +* view billing details according to permissions + +Customer/Sub-Operator Admin cannot: + +* modify parent-created plans +* view sibling subscriptions +* view parent-private plans +* select more than one active subscription + +### 12.3 Billing Prototype Rule + +Billing selection flow must include: + +```text +Open Billing +-> Resolve current customer/sub-operator scope +-> Load available plans from parent scope +-> Select plan +-> Check existing active subscription +-> Replace existing active plan or reject invalid selection +-> Confirm subscription +``` + +--- + +## 13. AI Agent Navigation Model + +AI is both a module and a contextual assistant. + +### 13.1 AI Agent Module + +Recommended structure: + +```text +AI Agent +-> Ask Anything +-> Investigations +-> Recommendations +-> Automations +-> Playbooks +-> Agent Activity +``` + +### 13.2 Contextual AI Entry Points + +AI actions should appear contextually throughout workflows. + +Examples: + +| Context | AI Action | +| ------- | --------- | +| Hierarchy node | Ask AI about this floor/building/site. | +| Device detail | Diagnose this AP or analyze uplink stability. | +| Rollout detail | Explain rollout failure or recommend rollback. | +| Billing | Summarize subscription risk. | +| Customer workspace | Generate customer health summary. | +| Metrics | Explain anomaly. | + +### 13.3 AI Approval Rule + +AI Assistant must not auto-execute operational actions. + +Required flow: + +```text +AI suggestion +-> User reviews recommendation +-> User approves action +-> System executes workflow +-> Result is tracked +``` + +AI must obey: + +* RBAC +* subtree scope +* billing visibility rules +* device/client scope isolation +* audit logging requirements + +--- + +## 14. Role-Based Navigation Visibility + +Navigation must adapt based on role and permissions. + +### 14.1 Root Operator + +Visible modules: + +```text +Dashboard +Customers +Hierarchy +Devices +Clients +Configurations +Rollouts +Maps +Billing +Users +Metrics +AI Agent +Administration +``` + +Purpose: + +* global platform visibility +* all operators/customers depending on product policy +* platform administration +* audit and advanced controls + +### 14.2 Operator Admin + +Visible modules: + +```text +Dashboard +Customers +Hierarchy +Devices +Clients +Configurations +Rollouts +Maps +Billing +Users +Metrics +AI Agent +Administration limited by policy +``` + +Purpose: + +* manage own operator subtree +* create/manage direct child customers/sub-operators +* manage billing plans for direct children +* manage devices, users, maps, configurations, rollouts, metrics in allowed scope + +### 14.3 Customer/Sub-Operator Admin + +Visible modules: + +```text +Dashboard +Hierarchy +Devices +Clients +Configurations +Rollouts +Maps +Billing +Users +Metrics +AI Agent +``` + +Optional, if allowed: + +```text +Customers +Administration limited +``` + +Purpose: + +* manage own subtree +* view/select eligible billing plans from parent scope +* manage own users, devices, maps, configurations, and rollouts + +Cannot: + +* view sibling subtrees +* modify parent billing plans +* access parent resources unless explicitly allowed + +### 14.4 NOC/Support + +Visible modules: + +```text +Dashboard +Hierarchy +Devices +Clients +Metrics +AI Agent +Rollouts read-only or diagnostic access +``` + +Purpose: + +* monitoring +* diagnostics +* operational investigation +* issue triage + +### 14.5 Installer + +Visible modules: + +```text +Hierarchy +Devices +Maps +Metrics limited +AI Agent limited +``` + +Purpose: + +* deployment setup +* device placement +* map association +* installation validation + +### 14.6 Billing/Admin + +Visible modules: + +```text +Dashboard limited +Customers limited +Billing +Metrics limited +AI Agent limited +``` + +Purpose: + +* plan management +* subscription status +* billing visibility according to scope + +### 14.7 Read-only + +Visible modules: + +```text +Dashboard +Hierarchy +Devices read-only +Clients read-only +Maps read-only +Metrics read-only +Billing read-only if allowed +AI Agent limited +``` + +Purpose: + +* view-only monitoring and reporting + +--- + +## 15. Navigation State Model + +Figma should define variants for these navigation states. + +### 15.1 Sidebar States + +```text +Expanded +Collapsed +Mobile drawer +Active item +Hover item +Disabled item +Hidden item by RBAC +``` + +### 15.2 Top Context Bar States + +```text +Default selected scope +Scope picker open +Scope search active +Scope loading +No scope selected +No permission for scope +Backend unavailable +Mobile compact context selector +``` + +### 15.3 Workspace Tab States + +```text +Active tab +Inactive tab +Hidden tab by RBAC +Disabled tab due to missing data +Loading tab content +Empty tab content +Error tab content +``` + +--- + +## 16. Prototype Workflow Paths + +The clickable Figma prototype should include these minimum paths. + +### 16.1 Authentication Path + +Workflow IDs: + +```text +WF-AUTH-001 +WF-AUTH-002 +WF-AUTH-003 +``` + +Prototype path: + +```text +Login +-> Dashboard +-> Session refresh invisible state +-> Logout +-> Login +``` + +### 16.2 Scope Switching Path + +Workflow IDs: + +```text +WF-HIERARCHY-001 +WF-HIERARCHY-002 +WF-HIERARCHY-003 +``` + +Prototype path: + +```text +Dashboard +-> Open Top Context Bar +-> Select Customer/Site/Floor +-> Hierarchy workspace updates +-> Workspace tabs update +``` + +### 16.3 Customer Creation Path + +Workflow ID: + +```text +WF-CUSTOMER-001 +``` + +Prototype path: + +```text +Customers +-> Create Customer +-> Enter details +-> Optional billing plan assignment +-> Submit +-> Success +-> Customer workspace +``` + +### 16.4 Billing Selection Path + +Workflow ID: + +```text +WF-BILLING-003 +``` + +Prototype path: + +```text +Billing +-> Available Plans +-> Resolve current customer scope +-> Select plan +-> Existing active subscription check +-> Confirm +-> Current Subscription +``` + +### 16.5 Device Diagnostics Path + +Workflow IDs: + +```text +WF-DEVICE-002 +WF-AI-002 +``` + +Prototype path: + +```text +Devices +-> Device Detail +-> Diagnostics +-> Ask AI +-> AI recommendation +-> User approval +-> Result +``` + +### 16.6 Rollout Path + +Workflow IDs: + +```text +WF-CONFIG-002 +WF-CONFIG-003 +``` + +Prototype path: + +```text +Configurations +-> Select configuration +-> Resolve current scope +-> Choose devices/nodes +-> Select staged rollout +-> Review +-> Execute +-> Progress tracking +-> Failure analysis +``` + +### 16.7 Maps and Topology Path + +Workflow IDs: + +```text +WF-MAP-001 +WF-MAP-002 +WF-MAP-003 +``` + +Prototype path: + +```text +Maps +-> Upload map asset +-> Associate to venue/floor +-> Hierarchy +-> Select Floor +-> Topology tab +-> View overlays +``` + +### 16.8 User Management Path + +Workflow IDs: + +```text +WF-USER-001 +WF-USER-002 +WF-USER-003 +``` + +Prototype path: + +```text +Users +-> Create User +-> Assign role/profile +-> Save +-> Reset Password +-> Suspend User +``` + +--- + +## 17. Figma Frame Naming Convention + +Use consistent frame names so later screen inventory and implementation mapping are easy. + +Recommended format: + +```text +[Module] / [Screen or State] / [Role] / [Viewport] +``` + +Examples: + +```text +Dashboard / Scoped Overview / Operator Admin / Desktop +Hierarchy / Floor Workspace - Topology Tab / NOC / Desktop +Billing / Available Plans / Customer Admin / Desktop +Devices / AP Detail - Diagnostics / NOC / Desktop +Maps / Upload Map / Installer / Desktop +Users / Create User / Customer Admin / Desktop +AI Agent / Investigation Detail / NOC / Desktop +``` + +For states: + +```text +Hierarchy / Floor Workspace - No Permission / Customer Admin / Desktop +Devices / Device List - Empty / NOC / Desktop +Billing / Available Plans - Existing Active Plan / Customer Admin / Desktop +``` + +--- + +## 18. Component Naming Convention + +Reusable Figma components should use predictable names. + +```text +Shell/Sidebar +Shell/TopContextBar +Shell/Breadcrumb +Shell/WorkspaceTabs +Navigation/SidebarItem +Navigation/ScopePicker +Navigation/HierarchyTree +Navigation/WorkspaceTab +Table/DataTable +Table/FilterBar +Form/TextInput +Form/Select +Form/PermissionAwareAction +State/Loading +State/Empty +State/Error +State/NoPermission +State/BackendUnavailable +AI/AssistantPanel +AI/RecommendationCard +Billing/PlanCard +Billing/SubscriptionStatus +Map/MapCanvas +Map/DeviceMarker +Topology/OverlayToggle +``` + +--- + +## 19. Mobile and Responsive Navigation + +The MDU UI must support desktop, tablet, and mobile layouts. + +### 19.1 Desktop + +```text +Left sidebar visible +Top context bar visible +Hierarchy tree can be persistent or collapsible +Workspace tabs visible horizontally +Right panel optional +``` + +### 19.2 Tablet + +```text +Sidebar may collapse +Hierarchy tree may become drawer +Top context bar remains visible +Workspace tabs may scroll horizontally +``` + +### 19.3 Mobile + +```text +Sidebar becomes drawer +Top context bar becomes compact selector +Hierarchy tree opens as full-screen picker or drawer +Workspace tabs become segmented control or horizontal scroll +Large topology/map views require pan/zoom controls +``` + +--- + +## 20. RBAC and System State Requirements + +Every major navigation path should include state variants. + +Required states: + +```text +Default +Loading +Empty +Error +No Permission +Backend Unavailable +Read-only +Action Hidden +Action Disabled +Success +Confirmation Required +``` + +### 20.1 RBAC Rules for Navigation + +* Unauthorized sidebar modules should be hidden by default. +* Unauthorized actions should be hidden by default. +* Backend 403 responses should show contextual permission messages. +* Scoped dropdowns should only show allowed subtree resources. +* Breadcrumbs and hierarchy trees must not expose unauthorized ancestors/siblings beyond allowed display policy. +* AI must not expose information outside current scope. + +--- + +## 21. Minimum Navigation Frames to Create First + +For the first Figma navigation model, create these frames before detailed screens. + +```text +1. Desktop App Shell - Default +2. Desktop App Shell - Sidebar Collapsed +3. Desktop App Shell - Scope Picker Open +4. Dashboard - Global/Operator View +5. Dashboard - Scoped Customer View +6. Customers - List +7. Customers - Create Customer +8. Hierarchy - Tree + Workspace Overview +9. Hierarchy - Floor Workspace Topology Tab +10. Devices - List +11. Devices - Device Detail Diagnostics +12. Clients - Active Clients +13. Configurations - List +14. Rollouts - Progress Tracking +15. Maps - Asset List +16. Maps - Upload Map +17. Billing - Plans Management +18. Billing - Available Plans +19. Billing - Current Subscription +20. Users - User List +21. Metrics - Scoped Metrics +22. AI Agent - Ask Anything +23. AI Context Panel - Recommendation Approval +24. Administration - Roles/Policies +25. No Permission State +26. Backend Unavailable State +27. Mobile App Shell - Drawer Closed +28. Mobile App Shell - Drawer Open +29. Mobile Scope Picker +``` + +--- + +## 22. Acceptance Checklist + +The Figma navigation model is acceptable when: + +* Sidebar clearly represents WHAT the user wants to do. +* Top Context Bar clearly represents WHERE the user is working. +* Scoped workflows resolve current hierarchy scope before execution. +* Customers and Hierarchy are clearly separated. +* Maps and Topology are clearly separated. +* Topology is not shown as a root sidebar item. +* Devices and Clients are separate modules. +* Billing respects parent-child scope and single active subscription rules. +* AI suggestions require explicit user approval before execution. +* RBAC visibility is shown for at least Root Operator, Operator Admin, Customer Admin, NOC/Support, Installer, Billing/Admin, and Read-only. +* Loading, empty, error, no-permission, and backend-unavailable states are represented. +* Mobile navigation has a clear drawer and compact context selector model. +* Prototype links cover the major workflows from `workflows.md`. + +--- + +## 23. Output of This Phase + +After this document is approved, the next phase is: + +```text +screen-inventory.md +``` + +The screen inventory should list every screen/frame required by this navigation model and map each screen to: + +* module +* workflow ID +* actor/role +* scope dependency +* RBAC behavior +* system states diff --git a/ui-docs/plan-phases/screen-definition.md b/ui-docs/plan-phases/screen-definition.md new file mode 100644 index 0000000..bdf58ff --- /dev/null +++ b/ui-docs/plan-phases/screen-definition.md @@ -0,0 +1,735 @@ +# MDU UI - Screen Definitions + +## 1. Purpose + +This document defines the purpose, actions, key information, hierarchy dependency, RBAC behavior, and required UI states for the first-phase MDU UI screens. + +It is the Phase 4 design document after: + +- `workflows.md` +- `figma-navigation-model.md` +- `screen-inventory.md` + +This document is intended to guide: + +- low-fidelity wireframes +- Figma screen creation +- clickable prototype behavior +- frontend implementation planning +- RBAC-aware UI behavior +- loading, empty, error, no-permission, and backend-unavailable states + + +--- + +## 2. Design Scope for This Phase + +This screen definition document intentionally covers only the first-phase screen inventory. + +### Included modules + +- Global Shell +- Authentication +- Dashboard +- Hierarchy +- Topology +- Devices +- Configuration +- Customers / Sub-Operators +- Billing +- Users +- Administration + +### Deferred modules + +- Clients +- Rollouts +- Maps +- Metrics +- AI Agent + +Deferred modules remain part of the full MDU UI product, but they are intentionally excluded from this phase and should be defined in later screen-definition documents. + +--- + +## 3. Core UX Rules + +### 3.1 Navigation rule + +```text +Sidebar = WHAT the user wants to do +Scope Breadcrumb Bar = WHERE the user is working +Workspace Tabs = HOW the user operates inside the selected scope +``` + +### 3.2 Scope rule + +Every resource screen must resolve the selected hierarchy scope before loading data or enabling actions. + +Required behavior: + +```text +Open screen +-> Resolve selected scope from Scope Breadcrumb Bar +-> Load only authorized resources inside that scope +-> Render only authorized actions +-> Preserve scope across navigation +``` + +### 3.3 RBAC rule + +The frontend must hide unauthorized modules and actions by default, but backend authorization remains mandatory. + +Default UI behavior: + +```text +Unauthorized module = hidden +Unauthorized action = hidden +Read-only permission = visible but non-editable +Backend 403 = contextual no-permission state +``` + +### 3.4 Topology rule + +Topology is not a root sidebar module. + +Correct path: + +```text +Hierarchy -> Select Node -> Topology Tab +``` + +Device connectivity topology is allowed under: + +```text +Devices -> Connectivity View +``` + +### 3.5 Billing rule + +Billing screens must enforce parent-child scope isolation. + +Key behaviors: + +- Parent operator can manage plans for direct child customers/sub-operators. +- Customer/sub-operator can view only eligible parent-offered plans. +- Customer/sub-operator can have only one active subscription. +- Sibling billing plans and subscriptions must never be visible. + +--- + +## 4. Screen Definition Template + +Each screen definition follows this model: + +| Field | Meaning | +| --- | --- | +| Screen ID | Unique screen identifier from `screen-inventory.md`. | +| Screen Name | Human-readable screen name. | +| Purpose | Why the screen exists. | +| Primary Actions | Main user actions supported by the screen. | +| Key Information / KPIs | Primary content, fields, counts, summaries, or operational information. | +| Hierarchy Dependency | Whether the screen depends on the selected scope from the Scope Breadcrumb Bar. | +| Linked Workflows | Workflow IDs supported by the screen. | +| RBAC Behavior | Which roles can view or act, and how restricted users are handled. | +| Required States | Loading, empty, error, no-permission, backend-unavailable, read-only, success, and confirmation states as applicable. | + +--- + +## 5. Role Model Used in This Document + +| Role | General UI Access | +| --- | --- | +| Root Operator | Platform/global access where product policy allows. | +| Operator Admin | Own operator subtree, child customers/sub-operators, scoped resources, billing plan management. | +| Customer Admin | Own customer/sub-operator subtree, own users/devices/configurations, available billing plans, own subscription. | +| NOC/Support | Monitoring, diagnostics, device visibility, connectivity troubleshooting where permitted. | +| Installer | Deployment, device assignment, limited map/topology/device actions where permitted. | +| Billing/Admin | Billing plan, subscription, and customer billing visibility according to assigned scope. | +| Read-only | View-only access to allowed resources; no create, edit, delete, assign, execute, or approve actions. | + +--- + +## 6. Standard System States + +| State | Required UX Behavior | +| --- | --- | +| Loading | Use skeletons or progress indicators. Preserve shell, sidebar, Top App Header, Scope Breadcrumb Bar, and current route. | +| Empty | Explain that no resources exist in the selected scope. Provide create action only if user has permission. | +| Error | Show contextual error message, retry action, and preserve current screen state. | +| No Permission | Show a permission-denied message without exposing unauthorized resource details. Avoid redirect loops. | +| Backend Unavailable | Show service-unavailable state with retry. Authentication shell may remain available. | +| Partial Data | Render available safe data and clearly mark missing sections. Never show unauthorized cached data. | +| Success | Confirm completion and navigate or refresh according to workflow. | +| Read-only | Show permitted data but disable or hide write actions. | +| Hidden Action | If user lacks permission, hide the action by default. | +| Disabled Action | Use only when action is unavailable because of state, dependency, or validation, not because of missing permission. | +| Confirmation Required | Sensitive/destructive actions require explicit review and confirmation. | + +--- + +## 7. Global Shell and Cross-Cutting Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-SHELL-001 | Main App Shell | Provide the authenticated product shell: Top App Header, sidebar, Scope Breadcrumb Bar, main content area, and user/session controls. | Navigate modules; open global search; use notifications/help/user menu; switch working scope through Scope Breadcrumb Bar; preserve selected scope while changing modules. | Current user, active role, selected scope, visible modules, active route, session status, backend status. | Required for all authenticated screens. Scope must remain synchronized across Scope Breadcrumb Bar, hierarchy tree, route, and workspace. | All workflows | All authenticated users see shell after login. Sidebar modules and actions are filtered by role and scope. | Loading shell, bootstrap failed, backend unavailable, no permission module, mobile/collapsed sidebar, read-only visible modules. | +| SCR-SHELL-002 | Scope Breadcrumb Bar / Scope Selector | Show and control the current hierarchy working scope using a breadcrumb-style selector. | Open a scope level dropdown; search hierarchy; select operator/customer/sub-operator/site/building/floor/venue; switch recent scopes. | Current scope path, current scope badge, scope type, allowed hierarchy levels, permission indicator when useful, recently used scopes. | Critical. Controls resource scope for dashboard, hierarchy, devices, configurations, billing, users, and topology. | WF-HIERARCHY-001 | Only allowed subtree items are visible. Unauthorized siblings, parents, and unrelated scopes are not selectable. | Scope loading, no scope selected, scope unavailable, no permission, backend unavailable, scope changed, unsaved changes warning. | +| SCR-SHELL-003 | Top App Header | Provide global product controls that are independent from hierarchy scope. | Toggle sidebar; open global search; view notifications; open help; open user profile menu. | Product logo/name, global search input, notifications count, help access, user avatar/name/role, session/account menu. | Not hierarchy-resource scoped. It persists across authenticated screens and does not change selected scope directly. | Cross-cutting, WF-AUTH-003 | Visible to all authenticated users. Notification, help, and profile menu contents may be filtered by role. | Loading user session, notification error, search unavailable, logout processing, mobile compact header. | +| SCR-SHELL-004 | Global Search / Resource Search | Search across permitted customers, nodes, devices, configurations, billing plans, and users. | Search resources; open result; filter by resource type; jump to result or switch to result scope when needed. | Permitted results only, result type, hierarchy path, status, last updated where useful. | Search results must be scoped by user RBAC and allowed subtree. Some results may also change the Scope Breadcrumb Bar when opened. | Cross-cutting | No unauthorized resources in results. Read-only users may open permitted results but not act. | Loading, no results, no permission, backend unavailable, partial results. | +| SCR-SHELL-005 | User Profile Menu | Provide account actions and session controls. | Open profile; change password; logout; view role/scope summary. | User name, role/profile, active session, account status. | User-session scoped, not hierarchy-resource scoped. | WF-AUTH-003 | Available to all authenticated users. Admin-only profile controls hidden unless permitted. | Logout processing, session expired, OWSEC unavailable, success. | +| SCR-SHELL-006 | Permission Denied State | Show contextual 403/no-permission UI without breaking navigation. | Return to safe page; retry if permissions changed; switch scope if allowed. | Message, current scope, blocked action/screen label. | Appears in any scoped screen when backend denies access. | Cross-cutting | Must not reveal unauthorized resource details. | No permission, permission changed, safe fallback. | +| SCR-SHELL-007 | Backend Unavailable State | Show service unavailable for business/resource operations. | Retry; keep shell visible; logout if needed. | Service status, affected module, retry affordance. | Applies to screens that call MDU backend. | Cross-cutting | Auth shell may remain available. No stale business data unless explicitly marked and allowed. | Backend unavailable, retrying, recovered, persistent failure. | +| SCR-SHELL-008 | Empty State Template | Reusable empty state for scoped resources. | Show create action if permitted; explain empty state. | Resource type, selected scope, suggested next action. | Depends on current screen and selected scope. | Cross-cutting | Create action hidden when not permitted. | Empty, read-only empty, no scope selected. | +| SCR-SHELL-009 | Loading / Skeleton State | Reusable loading state for module data. | Indicate data loading while preserving layout stability. | Skeleton areas for tables, cards, tabs, topology, forms. | Depends on current screen. | Cross-cutting | No RBAC-specific content should flash before permission resolution. | Initial loading, refresh loading, tab loading. | +| SCR-SHELL-010 | Not Found State | Handle deleted or missing resources. | Return to list; switch scope; retry. | Missing resource label, selected scope, safe next action. | Resource and route scoped. | Cross-cutting | Must not distinguish between missing and unauthorized resource if that would leak data. | Not found, no permission equivalent, deleted resource. | +| SCR-SHELL-011 | Confirmation Dialog | Reusable confirmation for destructive/sensitive actions. | Review impact; confirm; cancel. | Action name, target resource, impact warning, dependency warning. | Appears inside scoped workflows. | Customer, Device, Billing, User, Admin | Only shown when user already has permission to perform action. Read-only users never see destructive confirmations. | Confirmation required, validation error, submitting, success, failure. | + +--- + +## 8. Authentication Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-AUTH-001 | Login | Authenticate users directly through OWSEC before loading MDU backend bootstrap. | Enter credentials; submit login; recover password. | Login status, validation errors, account lock information when safe. | None before login. | WF-AUTH-001 | Public unauthenticated screen. After login, backend bootstrap determines role/scope/module visibility. | Loading, invalid credentials, account locked, OWSEC unavailable, bootstrap failed. | +| SCR-AUTH-002 | Forgot Password | Start OWSEC password recovery. | Enter email; request reset link. | Submitted email, safe success message. | None. | Auth support | Public unauthenticated screen. Do not reveal whether account exists. | Loading, success, invalid input, OWSEC unavailable. | +| SCR-AUTH-003 | Reset Password | Complete password reset through OWSEC. | Enter new password; confirm password; submit. | Password rules, token validity, success/error. | None. | Auth support | Public token-based screen. | Loading, token expired, weak password, success, OWSEC unavailable. | +| SCR-AUTH-004 | Change Password | Allow authenticated user or forced-reset user to change password. | Enter current/new password; submit. | Password policy, success/error, session status. | User-session scoped. | Auth support | Available to authenticated users; forced reset users may only access this flow until complete. | Loading, invalid current password, weak password, success. | +| SCR-AUTH-005 | Session Expired | Explain session expiry and return user to login. | Go to login; clear session. | Expiry reason if safe, login call-to-action. | User-session scoped. | WF-AUTH-002 | All users. | Session expired, redirecting, local cleanup failure. | +| SCR-AUTH-006 | Logout Processing | Clear session and synchronize logout across browser tabs. | Show logout progress; redirect to login. | Logout status. | User-session scoped. | WF-AUTH-003 | All authenticated users. | Processing, OWSEC logout failed but local cleanup succeeded, success. | +| SCR-AUTH-007 | Backend Bootstrap Failed | Handle case where OWSEC login succeeds but MDU backend bootstrap fails. | Retry bootstrap; logout; show limited shell if allowed. | Bootstrap service state, retry action. | No business scope until bootstrap succeeds. | WF-AUTH-001 | Authenticated but no resource permissions loaded yet. Do not show business data. | Backend unavailable, retrying, failed, logout. | + +--- + +## 9. Dashboard Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-DASHBOARD-001 | Global Dashboard | Show root/operator-level operational overview after login when permitted. | View summaries; open alerts; navigate to customers/devices/billing. | Customer count, device count, health summary, recent alerts, billing summary if permitted. | Uses default operator/root scope after bootstrap. | WF-AUTH-001 | Root Operator and Operator Admin. Customer Admin may not see global version unless policy allows. | Loading, empty summary, partial data, no permission, backend unavailable. | +| SCR-DASHBOARD-002 | Scoped Dashboard | Show dashboard for selected customer/site/node scope. | Switch scope; review health; open scoped modules. | Scoped device count, health, alerts, subscription status when permitted. | Required. Uses Scope Breadcrumb Bar selected scope. | WF-HIERARCHY-001 | Visible to users with dashboard access in selected scope. Billing cards hidden if not permitted. | Loading, empty scope, no permission, backend unavailable, partial data. | +| SCR-DASHBOARD-003 | Health Summary Panel | Summarize operational health for the current dashboard scope. | Open related device/hierarchy detail; filter health categories. | Online/offline devices, service health, warning/error counts. | Scoped by dashboard context. | Device | Visible to roles with operational monitoring access. Detail links follow RBAC. | Loading, no data, partial data, error. | +| SCR-DASHBOARD-004 | Recent Alerts Panel | Show recent operational alerts inside selected scope. | Open alert target; filter severity; acknowledge if permitted. | Alert severity, timestamp, affected resource, scope. | Scoped by dashboard context. | Cross-cutting | View depends on monitoring permission. Acknowledge action hidden if unauthorized. | Loading, no alerts, error, backend unavailable. | +| SCR-DASHBOARD-005 | Billing Summary Panel | Show subscription or billing summary when permitted. | Open billing overview; view subscription state. | Current plan, subscription state, renewal, device usage or connected-device billing summary. | Scoped by customer/sub-operator billing context. | WF-BILLING-004 | Visible to Operator Admin/Billing Admin/Customer Admin only when billing permission exists. | Loading, no active subscription, no permission, backend unavailable. | + +--- + +## 10. Customers / Sub-Operators Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-CUSTOMER-001 | Customer List | List permitted customers/sub-operators for tenant management. | Search; filter; select customer; create customer if permitted. | Customer name, status, parent scope, subscription summary, health summary. | Scoped to operator/customer subtree. | WF-CUSTOMER-002 | Root/Operator Admin see permitted child customers. Customer Admin sees children only if allowed. Create hidden if unauthorized. | Loading, empty, no permission, backend unavailable. | +| SCR-CUSTOMER-002 | Create Customer | Create child customer/sub-operator and first admin user. | Enter customer details; enter first admin; optionally assign billing; submit. | Customer identity, admin user, parent scope, billing plan if selected. | Required. Parent scope must be resolved before create. | WF-CUSTOMER-001 | Operator Admin or authorized Customer/Sub-Operator Admin only. Read-only/NOC/Installer hidden. | Loading, validation error, duplicate, permission denied, orchestration failure, success. | +| SCR-CUSTOMER-003 | Customer Detail | View customer profile, status, scope, and summary. | Edit; suspend/delete if permitted; open workspace/tabs. | Customer metadata, status, parent path, health, billing, user count. | Customer resource scoped. | WF-CUSTOMER-002 | Visible only for customers in allowed subtree. Sensitive actions hidden by RBAC. | Loading, not found, no permission, backend unavailable, partial data. | +| SCR-CUSTOMER-004 | Edit Customer | Edit customer/sub-operator metadata. | Update name/contact/status fields; save. | Editable metadata, validation status. | Customer resource scoped. | Customer management | Operator/Customer Admin with edit permission. No role/policy internals shown. | Loading, validation error, no permission, success, backend unavailable. | +| SCR-CUSTOMER-005 | Suspend Customer Confirmation | Confirm customer suspension with impact warning. | Review impact; confirm suspend; cancel. | Affected customer, active users/devices/subscription warning. | Customer resource scoped. | WF-CUSTOMER-003 | Only users with suspend permission see this modal. | Confirmation required, dependency warning, submitting, error, success. | +| SCR-CUSTOMER-006 | Delete Customer Confirmation | Confirm destructive customer deletion with dependency warning. | Review dependencies; confirm delete; cancel. | Child nodes, users, devices, subscriptions, deletion impact. | Customer resource scoped. | WF-CUSTOMER-003 | Only authorized users. Delete may be disabled by active dependencies. | Confirmation required, dependency blocking, submitting, permission denied, success. | +| SCR-CUSTOMER-007 | Customer Workspace | Provide customer-level contextual workspace. | Switch tabs; view overview/billing/users/health. | Customer health, devices, users, subscription, hierarchy summary. | Customer scope required. | WF-CUSTOMER-002 | Tabs filtered by role and enabled capabilities. | Loading, empty, no permission, partial data, backend unavailable. | +| SCR-CUSTOMER-008 | Customer Billing Tab | View or assign billing plan for customer when permitted. | View current plan; assign plan; open subscription detail. | Plan name, type, status, eligibility, active subscription. | Customer billing scope required. | WF-BILLING-002, WF-BILLING-004 | Operator/Billing Admin can assign to direct child. Customer Admin cannot modify parent-created plans. | Loading, no active subscription, no available plan, no permission, conflict. | +| SCR-CUSTOMER-009 | Customer Users Tab | View users inside customer scope. | List users; create user if permitted; open user detail. | User count, roles/profiles, status, scope summary. | Customer scope required. | WF-USER-001, WF-USER-002, WF-USER-003 | Only users inside permitted subtree. Create/edit hidden if unauthorized. | Loading, empty, no permission, backend unavailable. | +| SCR-CUSTOMER-010 | Customer Health Summary | Show operational summary for a customer. | Open related devices/hierarchy/billing where permitted. | Health score, device status, alerts, subscription status when allowed. | Customer scope required. | WF-CUSTOMER-002 | Health visible to operational roles. Billing parts hidden if not allowed. | Loading, partial data, no permission, backend unavailable. | + +--- + +## 11. Hierarchy Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-HIERARCHY-001 | Hierarchy Module | Entry screen for recursive subtree navigation. | Open tree; select node; create node if permitted. | Allowed hierarchy roots, selected node, node counts. | Required. Uses allowed subtree roots and selected scope. | WF-HIERARCHY-002 | All roles with hierarchy access see only allowed subtree. Create hidden if unauthorized. | Loading, empty hierarchy, no permission, backend unavailable. | +| SCR-HIERARCHY-002 | Hierarchy Tree | Expand and select customers, sites, buildings, towers, floors, and venues. | Expand/collapse; select node; search tree. | Node name, type, status, child count, selected state. | Critical. Must synchronize with Scope Breadcrumb Bar | WF-HIERARCHY-001, WF-HIERARCHY-002 | Tree only contains allowed nodes. Unauthorized siblings hidden. | Loading nodes, empty children, node unavailable, no permission. | +| SCR-HIERARCHY-003 | Node Workspace Shell | Contextual workspace for selected hierarchy node. | Switch workspace tabs; view overview/topology/devices/configurations. | Selected node, node type, health, tabs, allowed actions. | Required. All tabs depend on selected node. | WF-HIERARCHY-003 | Tabs/actions returned or filtered by RBAC, node type, capabilities. | Loading, no compatible tabs, no permission, backend unavailable, partial data. | +| SCR-HIERARCHY-004 | Node Overview Tab | Summarize selected node health, counts, and status. | Open related tab; view children/resources. | Device counts, child nodes, health, status, recent activity. | Selected node required. | WF-HIERARCHY-003 | View depends on node access. Actions hidden by permission. | Loading, empty node, partial data, no permission. | +| SCR-HIERARCHY-005 | Node Topology Tab | Show contextual topology for selected hierarchy node. | Open topology; switch overlays; inspect device; zoom/pan if applicable. | Topology type, devices, overlays, health, wireless quality where available. | Selected node required. Topology varies by site/building/tower/floor/venue. | WF-TOPOLOGY-001 | Only authorized resources and overlays appear. Topology tab hidden if user lacks access. | Loading, no map/topology, partial data, error, no permission, backend unavailable. | +| SCR-HIERARCHY-006 | Node Devices Tab | List infrastructure devices inside selected node scope. | Filter devices; open device detail; add/assign if permitted. | Gateway/switch/AP counts, status, assignment, firmware. | Selected node required. | WF-DEVICE-001 | Devices outside allowed subtree hidden. Create/assign actions hidden by permission. | Loading, empty devices, no permission, backend unavailable. | +| SCR-HIERARCHY-007 | Node Configurations Tab | Show configurations assigned or effective for selected node. | View assigned configs; assign config; preview effective config. | Config set, version, assignment target, effective status. | Selected node required. | WF-CONFIG-003, WF-CONFIG-004 | Visible to config-capable roles. Assign hidden for read-only/unauthorized users. | Loading, empty, validation/error, no permission. | +| SCR-HIERARCHY-008 | Create Node | Create site/building/tower/floor/venue under selected scope. | Select node type; enter details; save. | Parent node, node type, name, metadata. | Parent scope required. | WF-HIERARCHY-004 | Operator/Customer Admin with hierarchy create permission. Node type options may vary by policy. | Loading, validation error, duplicate, no permission, success. | +| SCR-HIERARCHY-009 | Edit Node | Edit selected node details. | Update metadata; save. | Node name, type, metadata, status. | Selected node required. | WF-HIERARCHY-005 | Edit hidden unless permitted. | Loading, validation error, no permission, success. | +| SCR-HIERARCHY-010 | Move Node | Move node to a new permitted parent scope. | Choose new parent; validate impact; save. | Current parent, new parent, affected descendants. | Selected node and allowed target parent required. | WF-HIERARCHY-006 | Only permitted target parents visible. Cannot move outside allowed subtree. | Loading, invalid parent, dependency conflict, no permission, success. | +| SCR-HIERARCHY-011 | Delete Node Confirmation | Confirm delete with impact/dependency warning. | Review impact; confirm delete; cancel. | Child nodes, devices, configs, topology/map dependencies. | Selected node required. | WF-HIERARCHY-007 | Only authorized destructive users. Delete may be blocked by dependencies. | Confirmation required, dependency warning, submitting, no permission, success. | +| SCR-HIERARCHY-012 | Empty Hierarchy State | Show when selected scope has no child nodes. | Create node if permitted; switch scope. | Selected scope and resource type. | Selected scope required. | WF-HIERARCHY-002 | Create call-to-action shown only if permitted. | Empty, read-only empty, no permission. | + +--- + +## 12. Devices Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-DEVICE-001 | Device Inventory | List infrastructure devices inside selected scope. | Filter/search; open detail; add/assign/move if permitted. | Device type, serial, status, node/venue assignment, firmware. | Selected scope required. | WF-DEVICE-001 | Only permitted devices in subtree. Clients are excluded from Devices. | Loading, empty, no permission, backend unavailable. | +| SCR-DEVICE-002 | Gateways List | Filtered list of gateway infrastructure devices. | Filter; open gateway detail; run allowed actions. | Gateway status, uplink, assignment, firmware. | Selected scope required. | WF-DEVICE-001 | Visible if Devices module and gateway view permitted. | Loading, empty, no permission, backend unavailable. | +| SCR-DEVICE-003 | Switches List | Filtered list of switch infrastructure devices. | Filter; open switch detail; run allowed actions. | Switch status, uplinks, ports, firmware, assignment. | Selected scope required. | WF-DEVICE-001 | Visible if Devices module and switch view permitted. | Loading, empty, no permission, backend unavailable. | +| SCR-DEVICE-004 | Access Points List | Filtered list of access point infrastructure devices. | Filter; open AP detail; run allowed actions. | AP status, clients count if permitted, channel/health, firmware. | Selected scope required. | WF-DEVICE-001 | Visible if Devices module and AP view permitted. | Loading, empty, no permission, backend unavailable. | +| SCR-DEVICE-005 | Device Detail | View device identity, status, assignment, and operational summary. | View diagnostics; run action; move/assign; open connectivity view. | Serial, type, model, status, assignment, firmware, health, last seen. | Device must belong to allowed selected/accessible scope. | WF-DEVICE-001 | NOC/Customer Admin/Installer access depends on permission. Dangerous actions hidden unless permitted. | Loading, not found, offline, no permission, backend unavailable, partial data. | +| SCR-DEVICE-006 | Device Diagnostics | View logs, status, uplink, errors, and troubleshooting data. | Inspect logs/metrics; retry load; open related topology. | Status, logs, uplink state, errors, diagnostics summary. | Device scope required. | WF-DEVICE-002 | Diagnostic depth depends on role. Read-only users see summary only. | Loading, logs unavailable, metrics unavailable, no permission, partial data. | +| SCR-DEVICE-007 | Device Action Confirmation | Confirm reboot, upgrade, blink, or factory reset. | Review action; confirm; cancel; track result. | Device identity, action impact, risk level. | Device scope required. | WF-DEVICE-003 | Only shown when action permission exists. Factory reset is highest-risk and requires strong warning. | Confirmation required, device offline, unsupported action, submitting, failed, success. | +| SCR-DEVICE-008 | Add Device | Add infrastructure device by serial and type. | Enter serial; select type; save. | Serial, device type, initial status, target scope. | Selected scope required. | WF-DEVICE-004 | Operator/Customer Admin/Installer if permitted. Serial uniqueness enforced by backend. | Loading, duplicate serial, invalid type, no permission, success. | +| SCR-DEVICE-009 | Assign Device | Assign device to node/venue/floor. | Select target; validate compatibility; save. | Device, allowed target nodes/venues, current assignment. | Selected scope and target scope required. | WF-DEVICE-005 | Targets outside allowed subtree never shown. | Loading, invalid target, compatibility error, no permission, success. | +| SCR-DEVICE-010 | Move Device | Move device to another permitted node/venue. | Choose new scope; validate; save. | Current assignment, new assignment, impact warning. | Device and target scope required. | WF-DEVICE-006 | Can move only within allowed subtree and compatible scope. | Loading, invalid target, no permission, success. | +| SCR-DEVICE-011 | Firmware Management | View firmware state and upgrade eligibility. | View version; start upgrade if permitted. | Current version, available version, eligibility, upgrade status. | Selected scope/device required. | WF-DEVICE-003 | Upgrade hidden unless permitted. Read-only users view version only. | Loading, no update, incompatible, no permission, upgrade queued/success/failure. | +| SCR-DEVICE-012 | Device Assignments | Manage assignment history and current scope. | View history; assign/move if permitted. | Current scope, previous assignments, timestamps. | Device scope required. | WF-DEVICE-005, WF-DEVICE-006 | Assignment actions hidden unless permitted. | Loading, empty history, no permission, error. | +| SCR-DEVICE-013 | Connectivity View | Engineering topology for gateways, switches, AP uplinks, mesh links, and port relationships. | Inspect device/link; filter graph; open device detail. | Gateways, switches, AP uplinks, mesh links, WAN, port/link state. | Selected subtree or device group scope required. | WF-TOPOLOGY-002 | NOC/engineering/Customer Admin where permitted. Only authorized devices/links appear. | Loading graph, empty graph, partial link data, no permission, backend unavailable. | +| SCR-DEVICE-014 | Device Empty Inventory State | Show when no infrastructure devices exist in selected scope. | Add device if permitted; switch scope. | Selected scope and device type. | Selected scope required. | WF-DEVICE-001 | Add device CTA shown only if user has create permission. | Empty, read-only empty, no permission. | + +--- + +## 13. Configuration Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-CONFIG-001 | Configuration List | List configuration sets inside selected scope. | Search/filter; create; open detail. | Config name, version, status, assignment count, last updated. | Selected scope required. | WF-CONFIG-001, WF-CONFIG-002 | Only configurations in allowed scope. Create/edit hidden if unauthorized. | Loading, empty, no permission, backend unavailable. | +| SCR-CONFIG-002 | Create Configuration | Create a configuration set after resolving current scope. | Enter settings; validate; save. | Config name, settings, target scope, validation status. | Selected scope required. | WF-CONFIG-001 | Operator/Customer Admin with config create permission. | Loading, validation error, duplicate name, no permission, success. | +| SCR-CONFIG-003 | Edit Configuration | Edit configuration settings. | Modify settings; validate; save version. | Editable settings, version, validation results. | Config resource scoped. | WF-CONFIG-002 | Edit hidden unless permitted. Read-only users view detail only. | Loading, validation error, no permission, conflict, success. | +| SCR-CONFIG-004 | Configuration Detail | View configuration summary, status, and assignments. | Open version history; assign; preview effective configuration. | Config version, status, assignments, last modified. | Config resource scoped. | WF-CONFIG-002, WF-CONFIG-003 | Visible only inside allowed scope. Assignment action hidden unless permitted. | Loading, not found, no permission, partial data. | +| SCR-CONFIG-005 | Configuration Version History | View previous versions and change history. | Compare versions; open version detail. | Version number, author, timestamp, change summary. | Config resource scoped. | WF-CONFIG-002 | View depends on config permission. Rollback is deferred unless rollout module is in scope later. | Loading, empty history, no permission, error. | +| SCR-CONFIG-006 | Assign Configuration | Assign configuration to permitted nodes/devices. | Select targets; validate; assign. | Target nodes/devices, compatibility, existing assignments. | Selected config and target scopes required. | WF-CONFIG-003 | Targets outside allowed subtree hidden. Assign hidden for read-only. | Loading targets, no eligible targets, validation error, no permission, success. | +| SCR-CONFIG-007 | Effective Configuration Preview | Preview effective configuration for selected node/device and overrides. | Select target; compare inherited/assigned overrides. | Effective values, override source, conflict indicators. | Selected node/device scope required. | WF-CONFIG-004 | Visible to roles with config view access. Sensitive values masked if required by policy. | Loading, no config, partial data, conflict/error, no permission. | +| SCR-CONFIG-008 | Configuration Validation Errors | Show invalid settings or assignment conflicts. | Review errors; jump to affected field; retry validation. | Error code, field, reason, suggested fix. | Config or assignment context required. | WF-CONFIG-001, WF-CONFIG-002 | Visible only to users editing/validating permitted configs. | Validation error, backend validation unavailable, resolved state. | + +--- + +## 14. Topology Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-TOPOLOGY-001 | Contextual Venue Topology | Default topology view inside selected hierarchy workspace. | View topology; toggle overlays; select device; zoom/pan. | Map/canvas, device placements, health overlays, wireless quality overlays where available. | Selected hierarchy node required. | WF-TOPOLOGY-001 | Only authorized resources appear. Clients only appear as permitted overlays/counts, not default graph nodes. | Loading, no topology/map, partial data, no permission, backend unavailable. | +| SCR-TOPOLOGY-002 | Site-Level Topology | Show building summaries and aggregate health. | Inspect building summary; open child node. | Building summaries, aggregate health, deployment overview. | Selected site required. | WF-TOPOLOGY-001 | Only buildings/resources in allowed subtree. | Loading, empty site, partial data, no permission. | +| SCR-TOPOLOGY-003 | Building-Level Topology | Show floor structure, AP density, and distribution summary. | Open floor; view AP density; inspect devices. | Floors, AP density, distribution switches, health summary. | Selected building required. | WF-TOPOLOGY-001 | Only authorized floors/devices visible. | Loading, no floors, partial data, no permission. | +| SCR-TOPOLOGY-004 | Tower-Level Topology | Show floor relationships and tower-level health. | Open floor; inspect tower health. | Floor relationships, AP distribution, aggregation health. | Selected tower required. | WF-TOPOLOGY-001 | Only authorized floors/devices visible. | Loading, empty tower, partial data, no permission. | +| SCR-TOPOLOGY-005 | Floor-Level Topology | Show AP placement and wireless overlays for a floor. | Zoom/pan; toggle AP/switch/gateway/quality overlays; select device. | Floor map, AP placement, wireless overlays, client density if permitted. | Selected floor required. | WF-TOPOLOGY-001 | Only permitted devices and overlays. Client details hidden unless later client module permits. | Loading, no floor map, placement missing, partial data, no permission. | +| SCR-TOPOLOGY-006 | Venue-Level Topology | Show detailed overlays, AP behavior, and coverage visualization. | Inspect APs; view coverage; switch overlays. | AP behavior, coverage visualization, operational health, device relationships. | Selected venue required. | WF-TOPOLOGY-001 | Venue data only within allowed subtree. | Loading, no topology data, partial data, no permission. | +| SCR-TOPOLOGY-007 | Topology Overlay Controls | Toggle topology layers and display modes. | Turn overlays on/off; select health/wireless/device layers. | Available overlays, active overlays, layer status. | Selected topology context required. | WF-TOPOLOGY-001 | Unauthorized overlays hidden. Missing-data overlays disabled with explanation. | Loading overlays, overlay unavailable, disabled, no permission. | +| SCR-TOPOLOGY-008 | Topology Device Detail Drawer | Inspect selected device from topology. | View device summary; open full detail; run allowed action. | Device identity, status, assignment, health, selected coordinates if available. | Selected device inside topology scope required. | WF-TOPOLOGY-001, WF-DEVICE-001 | Shows only authorized device data. Actions hidden unless permitted. | Loading, no permission, device offline, not found. | + +--- + +## 15. Billing Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-BILLING-001 | Billing Overview | Show billing status, plan summary, and actions for selected scope. | Open plans, available plans, current subscription, child subscriptions. | Current plan, subscription state, plan count, billing warnings. | Customer/sub-operator or operator billing scope required. | WF-BILLING-004 | Operator/Billing Admin see management views; Customer Admin sees own subscription/available plans. | Loading, no subscription, no permission, backend unavailable, partial data. | +| SCR-BILLING-002 | Billing Plan List | List plans the user can manage or view. | Search/filter; create plan; open detail; activate/deactivate. | Plan name, type, status, cycle, price, limits. | Operator billing scope required for management list. | WF-BILLING-001 | Parent operators manage own plans. Children cannot modify parent-created plans. | Loading, empty plans, no permission, backend unavailable. | +| SCR-BILLING-003 | Create Billing Plan | Create connection-based or fixed-device plan. | Select plan type; enter features, limits, pricing, status; save. | Plan type, device limits, billing cycle, price, connection-based charge. | Operator/parent billing scope required. | WF-BILLING-001 | Operator Admin/Billing Admin only where create permission exists. | Loading, validation error, duplicate, no permission, success. | +| SCR-BILLING-004 | Edit Billing Plan | Edit allowed billing plan fields. | Update details; activate/deactivate via confirmation. | Plan fields, status, eligibility, assignment impact. | Plan owner scope required. | WF-BILLING-001 | Only plan owner/authorized parent operator can edit. Child customers cannot edit. | Loading, validation error, no permission, conflict, success. | +| SCR-BILLING-005 | Billing Plan Detail | View plan details, status, features, pricing, and limits. | Edit if permitted; assign to customer; activate/deactivate. | Plan type, status, features, limits, billing cycle, price. | Plan scope required. | WF-BILLING-001 | View/manage depends on plan ownership and scope. Private parent plans hidden from children. | Loading, not found, no permission, backend unavailable. | +| SCR-BILLING-006 | Activate / Deactivate Plan Confirmation | Confirm plan status change. | Review impact; confirm; cancel. | Affected plan, child assignments, subscription impact. | Plan owner scope required. | WF-BILLING-001 | Only authorized plan managers. | Confirmation required, dependency warning, no permission, submitting, success. | +| SCR-BILLING-007 | Assign Plan to Customer | Assign eligible plan to a direct child customer/sub-operator. | Select direct child; select active plan; confirm. | Eligible plans, child customer, plan type, price, limits. | Parent operator scope and direct child customer scope required. | WF-BILLING-002 | Can assign only to direct child customers/sub-operators within allowed subtree. | Loading, no eligible plans, customer outside scope, inactive plan, no permission, success. | +| SCR-BILLING-008 | Available Plans | Allow customer/sub-operator to view parent-offered active plans. | Review plans; select eligible plan; open confirmation. | Plan cards, type, price, limits, active eligibility. | Current customer/sub-operator scope required. | WF-BILLING-003 | Customer Admin sees only eligible active parent-offered plans. Operator private/sibling plans hidden. | Loading, no available plans, no permission, backend unavailable. | +| SCR-BILLING-009 | Select Plan Confirmation | Confirm selected plan and check existing active subscription. | Review selected plan; confirm subscription; cancel. | Selected plan, current subscription if any, billing effect. | Customer/sub-operator scope required. | WF-BILLING-003 | Customer Admin with subscription select permission. Existing active subscription requires conflict handling. | Confirmation required, conflict, inactive plan, no permission, submitting, success. | +| SCR-BILLING-010 | Replace Existing Plan Confirmation | Confirm replace-or-reject behavior for existing active subscription. | Review current and new plan; confirm replacement if allowed. | Current plan, new plan, effective date, impact. | Customer/sub-operator scope required. | WF-BILLING-003 | Only shown if product allows replacement. Otherwise show conflict state. | Confirmation required, 409 conflict, no permission, success. | +| SCR-BILLING-011 | Current Subscription Detail | View current subscription, state, plan type, limits, and renewal. | View plan; open available plans; view usage details. | Subscription state, plan, renewal, limits, connection/fixed-device details. | Customer/sub-operator or permitted child scope required. | WF-BILLING-004 | Customer sees own subscription. Operator/Billing Admin sees permitted child subscriptions. | Loading, no active subscription, suspended/expired, no permission, backend unavailable. | +| SCR-BILLING-012 | Subscription Visibility Dashboard | Allow operator to view permitted child subscriptions. | Filter by child customer; open subscription detail. | Child customer, plan, status, renewal, usage alerts. | Operator/parent scope required. | WF-BILLING-004 | Only permitted child scopes. Sibling/unrelated subscriptions hidden. | Loading, empty, no permission, partial data. | +| SCR-BILLING-013 | Connection-Based Billing Detail | Show connected-device billing details. | Review connected-device usage; open subscription. | Connected device count, price per connected device, billing cycle. | Subscription scope required. | WF-BILLING-004 | Visible only for connection-based plans and billing-authorized roles. | Loading, no data, no permission, backend unavailable. | +| SCR-BILLING-014 | Fixed-Device Billing Detail | Show fixed-device limits and usage. | Review device allowance; inspect limit warning. | Device limit, used count, remaining allowance, billing cycle. | Subscription scope required. | WF-BILLING-004 | Visible only for fixed-device plans and billing-authorized roles. | Loading, limit exceeded, no permission, backend unavailable. | +| SCR-BILLING-015 | No Available Plans State | Show when customer has no eligible plans. | Return to billing overview; contact parent/operator if applicable. | Selected customer scope and empty plan state. | Customer/sub-operator scope required. | WF-BILLING-003 | No create/edit actions for child customer. Parent operator management link hidden unless role permits. | Empty, no permission equivalent, backend unavailable. | +| SCR-BILLING-016 | No Active Subscription State | Show when no subscription exists. | Open available plans if permitted. | Selected scope, subscription absence. | Customer/sub-operator scope required. | WF-BILLING-004 | Select plan CTA only if eligible and permitted. | Empty, no permission, backend unavailable. | +| SCR-BILLING-017 | Billing Conflict State | Show single-active-plan conflict or 409 error. | Review conflict; return to subscription; choose replace flow if allowed. | Existing subscription, attempted plan, conflict reason. | Customer/sub-operator scope required. | WF-BILLING-003 | Do not expose unauthorized subscription details. Only own/current conflict shown. | 409 conflict, no permission, backend unavailable. | + +--- + +## 16. Users Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-USER-001 | User List | List users inside selected or permitted scope. | Search/filter; create user; open detail. | User name, email, role/profile, status, scope. | Selected customer/subtree scope required. | WF-USER-001 | Only users in permitted scope. Create hidden unless permitted. | Loading, empty, no permission, backend unavailable. | +| SCR-USER-002 | Create User | Create user and assign role/profile/scope. | Enter user details; select role/profile; select scope; save. | Email, name, role/profile, assigned scope. | Current scope and assignable child scopes required. | WF-USER-001 | Actor cannot grant permissions higher than allowed authority. Assignable roles filtered. | Loading, duplicate email, invalid role, scope not allowed, no permission, success. | +| SCR-USER-003 | User Detail | View user profile, status, roles, and scope. | Edit; assign role; reset password; suspend if permitted. | Profile, status, roles/profiles, scope assignments, sessions. | User resource must be inside permitted subtree. | WF-USER-001, WF-USER-002, WF-USER-003 | Cannot view users outside scope. Higher-authority users may be restricted by policy. | Loading, not found, no permission, backend unavailable. | +| SCR-USER-004 | Edit User | Edit user details where permitted. | Update profile fields; save. | Editable user metadata, status. | User resource scoped. | WF-USER-001 | Edit hidden unless permitted. Cannot elevate authority through edit. | Loading, validation error, no permission, success. | +| SCR-USER-005 | Assign Role/Profile | Assign permission profile within allowed authority. | Select role/profile; select scope; save. | Available profiles, scope summary, impact warning. | User and target scope required. | WF-USER-001 | Assignable profiles filtered by actor authority. Backend enforces OWPROV policy. | Loading, invalid assignment, no permission, success. | +| SCR-USER-006 | Reset Password Confirmation | Trigger OWSEC password reset flow. | Confirm reset; send reset. | Target user, email, reset status. | User resource scoped. | WF-USER-002 | Only allowed for users inside permitted scope. | Confirmation required, OWSEC unavailable, no permission, success. | +| SCR-USER-007 | Suspend User Confirmation | Suspend user and optionally revoke active sessions. | Review impact; confirm suspend; cancel. | Target user, role, active sessions, impact. | User resource scoped. | WF-USER-003 | Cannot suspend users outside scope or higher authority unless explicitly allowed. | Confirmation required, no permission, session revocation failure, success. | +| SCR-USER-008 | User Sessions | View and manage active sessions when permitted. | View sessions; revoke session if allowed. | Session device/browser, last active, status. | User resource scoped. | WF-USER-003 | Session management permission required. Read-only may view summary only. | Loading, no sessions, no permission, backend unavailable. | +| SCR-USER-009 | User Scope Assignment Summary | Show assigned customer/subtree/node scope. | Inspect assigned scopes; open hierarchy if permitted. | Scope path, role/profile, inherited permissions summary. | User resource scoped. | WF-USER-001 | Do not expose unauthorized hierarchy details. | Loading, no scope, no permission, partial data. | + +--- + +## 17. Administration Screen Definitions + +| Screen ID | Screen Name | Purpose | Primary Actions | Key Information / KPIs | Hierarchy Dependency | Linked Workflows | RBAC Behavior | Required States | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| SCR-ADMIN-001 | Administration Overview | Entry point for platform/operator administration. | Open settings, roles/policies, audit logs, debug views if permitted. | Available admin sections, system status, permission level. | Platform/operator scope depending on role. | WF-ADMIN-001 | Root Operator broadest access. Operator Admin limited by policy. Others usually hidden. | Loading, no permission, backend unavailable. | +| SCR-ADMIN-002 | Platform Settings | Manage global settings when permitted. | View/edit settings; save. | Setting name, value, scope, last updated. | Platform scope. | WF-ADMIN-001 | Root Operator or explicit platform admin only. | Loading, validation error, no permission, success. | +| SCR-ADMIN-003 | Operator Administration | Manage operator-level settings and child operator context. | View operator settings; edit permitted values. | Operator identity, status, settings, child context. | Operator scope required. | WF-ADMIN-001 | Operator Admin sees own operator scope only. Root sees permitted operators. | Loading, no permission, partial data, backend unavailable. | +| SCR-ADMIN-004 | Roles and Policies | View and manage role/policy profiles without exposing raw OWPROV complexity. | View profiles; edit allowed profile; inspect impact. | Role/profile names, permissions summary, scope rules. | Platform/operator scope depending on authority. | WF-ADMIN-001 | Root/Operator Admin only. Users cannot grant permissions outside their authority. | Loading, empty, no permission, backend unavailable, impact warning. | +| SCR-ADMIN-005 | Edit Role / Policy | Edit permitted role or policy settings. | Modify profile; validate; save. | Permissions summary, affected users/scopes, impact warning. | Admin scope required. | WF-ADMIN-001 | Restricted to authorized admins. Prevent breaking required admin access. | Loading, validation error, impact warning, no permission, success. | +| SCR-ADMIN-006 | Audit Logs | View permitted audit events. | Filter by user/action/resource/scope/date; open event detail. | Timestamp, actor, action, resource, scope, result. | Platform/operator/subtree scope depending on role. | WF-ADMIN-002 | Audit logs are scoped. No events from unauthorized subtrees. | Loading, empty logs, no permission, backend unavailable. | +| SCR-ADMIN-007 | Audit Event Detail | Inspect selected audit event. | View event metadata; return to log list. | Actor, action, resource, scope, before/after summary if permitted. | Audit event scope required. | WF-ADMIN-002 | Sensitive fields masked if not permitted. | Loading, not found, no permission, partial data. | +| SCR-ADMIN-008 | Advanced / Debug Views | Internal troubleshooting views for permitted admins. | Open debug details; inspect internal mappings when explicitly allowed. | Entity/venue mapping summaries, backend status, troubleshooting metadata. | Admin/debug scope required. | Admin support | Only advanced/internal admins. Normal users should not see raw OWPROV internals. | Loading, no permission, backend unavailable. | +| SCR-ADMIN-009 | Permission Change Impact Warning | Warn before sensitive RBAC changes. | Review affected users/scopes; confirm/cancel. | Affected roles, users, scopes, risk warning. | Admin scope required. | WF-ADMIN-001 | Only displayed during authorized role/policy changes. | Confirmation required, validation failure, no permission, success. | + +--- + + +## 18. High-Priority Detailed Definitions + +The following screens require extra care in wireframes and prototype behavior because they carry the highest UX and RBAC risk. + +### 18.1 SCR-SHELL-001 - Main App Shell + +Purpose: + +```text +Provide a stable authenticated shell while all modules, routes, hierarchy scope, and RBAC visibility change underneath it. +``` + +Required behavior: + +- Top App Header must remain visible on authenticated screens. +- Sidebar must show only authorized in-scope modules. +- Scope Breadcrumb Bar must show and control the selected working scope. +- Main content must not render protected data until bootstrap and permission resolution complete. +- Mobile shell must collapse sidebar into drawer and keep the Scope Breadcrumb Bar or compact scope selector available. +- Route changes must not accidentally reset the selected scope. + +Required states: + +- Initial bootstrap loading +- Backend bootstrap failed +- Backend unavailable +- No modules available +- Scope changed +- Session expired +- Read-only module visibility + +--- + +### 18.2 SCR-SHELL-002 - Scope Breadcrumb Bar / Scope Selector + +Purpose: + +```text +Control WHERE the user is working across all scoped modules. +``` + +Required behavior: + +- Must display scope as: + ```text + Operator > Customer > Sub-Operator > Site > Building > Floor > Venue + ``` +- Must support recursive variable-depth hierarchy. +- Each scope level may open a dropdown selector for switching to another permitted item at that level. +- Must show only allowed subtree items. +- Must synchronize with hierarchy tree, route context, and workspace. +- When scope changes, all scoped module data must refresh. +- Unsafe forms should warn before discarding unsaved changes during scope switch. +- It replaces the old separate `Scope Breadcrumb Bar` and `Scope Breadcrumb Bar` model. + +Required states: + +- Scope loading +- No scope selected +- Scope search active +- Scope unavailable +- No permission for selected scope +- Backend unavailable +- Mobile compact selector + +--- + +### 18.3 SCR-SHELL-003 - Top App Header + +Purpose: + +```text +Provide global product controls that are independent from hierarchy scope. +``` + +Required behavior: + +- Must contain: + ```text + Logo / product identity + Sidebar toggle + Global search + Notifications + Help + User profile menu + ``` +- Must not be used to change selected hierarchy scope. +- Global search can jump to resources, but actual working-scope changes must be reflected through the Scope Breadcrumb Bar. +- User menu provides profile, change password, role/scope summary, and logout. +- Mobile version may collapse global actions into icons or menu. + +Required states: + +- User/session loading +- Search unavailable +- Notifications unavailable +- Logout processing +- Session expired +- Mobile compact header + +--- + +### 18.4 SCR-HIERARCHY-003 - Node Workspace Shell + +Purpose: + +```text +Provide contextual operations for the selected hierarchy node. +``` + +Required behavior: + +- Workspace tabs adapt to node type, RBAC, capabilities, and available data. +- Unauthorized tabs are hidden. +- Missing-data tabs may be disabled with explanation. +- Selected node must remain clear at all times. + +Required tab model for this phase: + +- Overview +- Topology +- Devices +- Configurations + +Deferred tabs: + +- Clients +- Maps +- Metrics +- AI Insights + +--- + +### 18.5 SCR-HIERARCHY-005 - Node Topology Tab + +Purpose: + +```text +Show contextual topology for the selected hierarchy node without making topology a root navigation module. +``` + +Required behavior: + +- Site, building, tower, floor, and venue levels should render different topology summaries. +- Device overlays must include only authorized infrastructure devices. +- Client overlays are deferred unless represented only as non-identifying aggregate counts. +- Device details open in a drawer or link to Device Detail if permitted. + +Required states: + +- No topology available +- No map available where map is required +- Partial topology data +- Overlay unavailable +- Backend unavailable +- No permission + +--- + +### 18.6 SCR-DEVICE-005 - Device Detail + +Purpose: + +```text +Provide the canonical operational detail page for an infrastructure device. +``` + +Required behavior: + +- Show device identity, assignment, status, firmware, and health. +- Diagnostic depth depends on role. +- Dangerous actions require confirmation. +- If device is offline, actions may be disabled for state reasons. + +Required RBAC behavior: + +- Read-only: view only +- Installer: install/assignment actions if permitted +- NOC/Support: diagnostics and limited actions if permitted +- Customer Admin: management actions inside own scope if permitted +- Operator Admin: management actions inside operator subtree if permitted + +--- + +### 18.7 SCR-DEVICE-013 - Connectivity View + +Purpose: + +```text +Show engineering-focused connectivity topology under Devices, separate from venue/floor topology. +``` + +Required behavior: + +- Render gateways, switches, AP uplinks, mesh links, WAN relationships, and port/link states. +- Only authorized devices and links can appear. +- Link details must not reveal devices outside scope. +- If graph data is partial, label it clearly. + +--- + +### 18.8 SCR-BILLING-003 - Create Billing Plan + +Purpose: + +```text +Allow authorized parent operators to create fixed-device or connection-based billing plans. +``` + +Required behavior: + +- Plan type must be selected first. +- Connection-based plans require price per connected device. +- Fixed-device plans require device limit and billing cycle. +- Children/customers cannot access this screen for parent-created plans. + +--- + +### 18.9 SCR-BILLING-008 - Available Plans + +Purpose: + +```text +Allow a customer/sub-operator to view eligible active plans offered by its parent operator. +``` + +Required behavior: + +- Show only eligible active plans. +- Do not show inactive, archived, parent-private, sibling, or unauthorized plans. +- If there is an existing active subscription, route to confirmation/conflict handling. + +--- + +### 18.10 SCR-BILLING-009 - Select Plan Confirmation + +Purpose: + +```text +Prevent accidental subscription changes and enforce single-active-subscription rules. +``` + +Required behavior: + +- Show selected plan summary. +- Show existing active subscription conflict if present. +- Confirm or block selection based on backend validation. +- Preserve current subscription if selection fails. + +--- + +### 18.11 SCR-BILLING-011 - Current Subscription Detail + +Purpose: + +```text +Show the current subscription state and plan limits for the selected customer/sub-operator scope. +``` + +Required behavior: + +- Show subscription state clearly: active, inactive, pending, suspended, expired, or cancelled. +- Show plan type and relevant usage details. +- Show fixed-device or connection-based details only when applicable. +- Do not expose sibling subscriptions. + +--- + +### 18.12 SCR-CONFIG-007 - Effective Configuration Preview + +Purpose: + +```text +Explain the final effective configuration for a node or device after assignments and overrides. +``` + +Required behavior: + +- Show inherited, assigned, and overridden values. +- Mark conflicts and validation issues. +- Keep backend as source of truth. +- Do not expose configuration from unauthorized parent/sibling scopes unless explicitly allowed. + +--- + +### 18.13 SCR-ADMIN-004 - Roles and Policies + +Purpose: + +```text +Expose permission profiles in a business-friendly way while hiding OWPROV internals from normal users. +``` + +Required behavior: + +- Use user-facing role/profile labels. +- Avoid exposing raw managementRole, managementPolicy, policy inheritance, or scope-chain internals. +- Edits must include impact warning. +- Users cannot grant authority outside their own allowed authority. + +--- + +## 19. Screen Definition Acceptance Checklist + +This document is acceptable when: + +- Every in-scope screen from `screen-inventory.md` has a purpose. +- Every in-scope screen has primary actions. +- Every in-scope screen identifies hierarchy/scope dependency. +- Every in-scope screen identifies RBAC behavior. +- Every important screen has loading, empty, error, no-permission, backend-unavailable, and read-only states where applicable. +- Topology remains contextual and not a root sidebar module. +- Device connectivity topology remains under Devices. +- Billing respects parent-child scope isolation. +- Customers and Hierarchy remain separate concepts. +- Devices and clients remain separate, with Clients deferred for this phase. +- Deferred modules are not accidentally expanded in this document. +- The document is ready to feed `layout-system.md` and `wireframe-plan.md`. + +--- + +## 20. Next Phase Inputs + +This document should feed directly into: + +```text +layout-system.md +wireframe-plan.md +Figma low-fidelity screens +Figma clickable prototype +``` + +Recommended next step: + +```text +Create layout-system.md using the recurring layout needs discovered in this screen definition: +- App Shell Layout +- Auth Layout +- Dashboard Layout +- Table + Detail Layout +- Form / Wizard Layout +- Hierarchy Workspace Layout +- Topology Canvas Layout +- Billing Management Layout +- System State Layout +``` + +--- + +## 21. Final Summary + +This `screen-definition.md` defines all first-phase MDU UI screens from the approved inventory. + +It covers: + +- Global Shell, including Top App Header and Scope Breadcrumb Bar +- Authentication +- Dashboard +- Customers / Sub-Operators +- Hierarchy +- Devices +- Configuration +- Topology +- Billing +- Users +- Administration + +It intentionally excludes: + +- Clients +- Rollouts +- Maps +- Metrics +- AI Agent + +Those deferred modules remain part of the full MDU UI design direction and should be handled in later design phases. + diff --git a/ui-docs/plan-phases/screen-inventory.md b/ui-docs/plan-phases/screen-inventory.md new file mode 100644 index 0000000..ff5b5cd --- /dev/null +++ b/ui-docs/plan-phases/screen-inventory.md @@ -0,0 +1,481 @@ +# MDU UI - Screen Inventory + +# 1. Purpose + +This document defines the complete screen inventory for the first-phase MDU UI design scope. + +It is the Phase 3 design document and is based on: + +* `mdu-ui-spec.md` +* `workflows.md` +* `figma-navigation-model.md` +* MDU UI wireframing and UX design process + +The goal is to identify every screen, workspace, modal, panel, and important system state required before creating detailed screen definitions and low-fidelity wireframes. + +This document answers: + +```text +Which screens are required to support the approved in-scope MDU UI workflows for this phase? +``` + +It does not define final layout details. Detailed purpose, RBAC states, loading states, empty states, and error states will be defined in: + +```text +screen-definitions.md +``` + +--- + +# 2. Screen Inventory Principles + +The screen inventory follows these product rules: + +* `mdu-ui-spec.md` remains the source of truth. +* Top App Header represents global product controls: logo, global search, notifications, help, and user profile. +* Sidebar navigation represents what the user wants to do. +* Scope Breadcrumb Bar represents where the user is working. +* Every resource screen must resolve scope from the selected hierarchy context shown in the Scope Breadcrumb Bar. +* Topology is not a root sidebar screen. +* Topology is a contextual workspace view inside the selected hierarchy node. +* Billing screens must enforce parent-child scope isolation. + + +Navigation rule: + +```text +Top App Header = GLOBAL product controls +Sidebar = WHAT the user wants to do +Scope Breadcrumb Bar = WHERE the user is working +``` + +--- + +# 3. Screen ID Naming Convention + +Use the following naming convention: + +```text +SCR-- +``` + +Examples: + +```text +SCR-AUTH-001 +SCR-DASHBOARD-001 +SCR-HIERARCHY-003 +SCR-BILLING-004 +``` + +Recommended Figma frame naming: + +```text +[Screen ID] - [Screen Name] +``` + +Example: + +```text +SCR-BILLING-003 - Create Billing Plan +``` + +--- + +# 4. Layout Type Reference + +The following reusable layout types should be referenced from this inventory and finalized in `layout-system.md`. + +| Layout Type | Description | +| ---------- | ----------- | +| App Shell Layout | Top App Header, sidebar, Scope Breadcrumb Bar, main workspace | +| Auth Layout | Login, password reset, session screens | +| Dashboard Layout | Cards, summaries, charts, alerts, insights | +| Table + Detail Layout | List/table with detail drawer or detail page | +| Form / Wizard Layout | Create/edit flows and multi-step workflows | +| Hierarchy Workspace Layout | Hierarchy tree with contextual workspace tabs | +| System State Layout | Loading, empty, no permission, backend unavailable, error | + +--- + +# 5. Global Shell and Cross-Cutting Screens + +These screens/components exist across the whole product. + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-SHELL-001 | Main App Shell | Shell | Provides Top App Header, sidebar, Scope Breadcrumb Bar, content area, and global shell structure | All workflows | +| SCR-SHELL-002 | Scope Breadcrumb Bar / Scope Selector | Component/Overlay | Shows and controls current hierarchy scope: Operator > Customer > Sub-Operator > Site > Building > Floor > Venue | WF-HIERARCHY-001 | +| SCR-SHELL-003 | Top App Header | Component | Shows global product controls: logo, global search, notifications, help, and user profile | Cross-cutting, WF-AUTH-003 | +| SCR-SHELL-004 | Global Search / Resource Search | Overlay | Search permitted customers, nodes, devices and users | Cross-cutting | +| SCR-SHELL-005 | User Profile Menu | Overlay | Access profile, change password, logout | WF-AUTH-003 | +| SCR-SHELL-006 | Permission Denied State | System State | Show 403 and no-permission UI without breaking navigation | Cross-cutting | +| SCR-SHELL-007 | Backend Unavailable State | System State | Show service unavailable and retry behavior | Cross-cutting | +| SCR-SHELL-008 | Empty State Template | System State | Standard empty state for scoped resources | Cross-cutting | +| SCR-SHELL-009 | Loading / Skeleton State | System State | Standard loading behavior for modules and tables | Cross-cutting | +| SCR-SHELL-010 | Not Found State | System State | Handles missing or deleted resources | Cross-cutting | +| SCR-SHELL-011 | Confirmation Dialog | Component/Modal | Used for destructive or sensitive actions | Customer, Device, Billing, User, Admin | + +--- + +# 6. Authentication Screens + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-AUTH-001 | Login | Page | User login through OWSEC | WF-AUTH-001 | +| SCR-AUTH-002 | Forgot Password | Page/Form | Start password recovery | Auth support | +| SCR-AUTH-003 | Reset Password | Page/Form | Complete password reset | Auth support | +| SCR-AUTH-004 | Change Password | Page/Form | Change password after login or forced reset | Auth support | +| SCR-AUTH-005 | Session Expired | Page/State | Inform user session expired and redirect to login | WF-AUTH-002 | +| SCR-AUTH-006 | Logout Processing | State | Clear session and synchronize logout across tabs | WF-AUTH-003 | +| SCR-AUTH-007 | Backend Bootstrap Failed | State | Auth succeeded but backend bootstrap failed | WF-AUTH-001 | + +--- + +# 7. Dashboard Screens + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-DASHBOARD-001 | Global Dashboard | Page | Root/operator-level platform overview | WF-AUTH-001 | +| SCR-DASHBOARD-002 | Scoped Dashboard | Page | Dashboard scoped to selected customer/site/node | WF-HIERARCHY-001 | +| SCR-DASHBOARD-003 | Health Summary Panel | Panel | Summarize device, and service health | Device| +| SCR-DASHBOARD-004 | Recent Alerts Panel | Panel | Show recent operational alerts inside selected scope | Cross-cutting | +| SCR-DASHBOARD-005 | Billing Summary Panel | Panel | Show subscription or billing summary when permitted | WF-BILLING-004 | + +--- + +# 8. Customers / Sub-Operators Screens + +The Customers module is for tenant/customer/sub-operator management. + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-CUSTOMER-001 | Customer List | Page/Table | List permitted customers/sub-operators | WF-CUSTOMER-002 | +| SCR-CUSTOMER-002 | Create Customer | Form/Wizard | Create child customer/sub-operator and first admin user | WF-CUSTOMER-001 | +| SCR-CUSTOMER-003 | Customer Detail | Page/Detail | View customer profile, status, scope, and summary | WF-CUSTOMER-002 | +| SCR-CUSTOMER-004 | Edit Customer | Form | Edit customer/sub-operator metadata | Customer management | +| SCR-CUSTOMER-005 | Suspend Customer Confirmation | Modal | Confirm customer suspension with impact warning | WF-CUSTOMER-003 | +| SCR-CUSTOMER-006 | Delete Customer Confirmation | Modal | Confirm destructive customer deletion with dependency warning | WF-CUSTOMER-003 | +| SCR-CUSTOMER-007 | Customer Workspace | Workspace | Customer-level contextual workspace | WF-CUSTOMER-002 | +| SCR-CUSTOMER-008 | Customer Billing Tab | Tab | View/assign billing plan for customer when permitted | WF-BILLING-002, WF-BILLING-004 | +| SCR-CUSTOMER-009 | Customer Users Tab | Tab | View users inside customer scope | WF-USER-001, WF-USER-002, WF-USER-003 | +| SCR-CUSTOMER-010 | Customer Health Summary | Panel/Page | Show health and operational summary for customer | WF-CUSTOMER-002 | + + +--- + +# 9. Hierarchy Screens + +The Hierarchy module is the primary operational subtree navigation workspace. + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-HIERARCHY-001 | Hierarchy Module | Page | Entry screen for subtree navigation | WF-HIERARCHY-002 | +| SCR-HIERARCHY-002 | Hierarchy Tree | Component | Expand and select customers, sites, buildings, towers, floors, venues | WF-HIERARCHY-001, WF-HIERARCHY-002 | +| SCR-HIERARCHY-003 | Node Workspace Shell | Workspace | Contextual workspace for selected hierarchy node | WF-HIERARCHY-003 | +| SCR-HIERARCHY-004 | Node Overview Tab | Tab | Summary of selected node health, counts, and status | WF-HIERARCHY-003 | +| SCR-HIERARCHY-005 | Node Topology Tab | Tab | Contextual topology for selected hierarchy node | WF-TOPOLOGY-001 | +| SCR-HIERARCHY-006 | Node Devices Tab | Tab/Table | Infrastructure devices inside selected node scope | WF-DEVICE-001 | +| SCR-HIERARCHY-007 | Node Configurations Tab | Tab | Configurations assigned/effective for selected node | WF-CONFIG-003, WF-CONFIG-004 | +| SCR-HIERARCHY-008 | Create Node | Form/Modal | Create site/building/tower/floor/venue under selected scope | WF-HIERARCHY-004 | +| SCR-HIERARCHY-009 | Edit Node | Form/Modal | Edit selected node details | WF-HIERARCHY-005 | +| SCR-HIERARCHY-010 | Move Node | Modal/Wizard | Move node to a new permitted parent scope | WF-HIERARCHY-006 | +| SCR-HIERARCHY-011 | Delete Node Confirmation | Modal | Confirm delete with impact/dependency warning | WF-HIERARCHY-007 | +| SCR-HIERARCHY-012 | Empty Hierarchy State | State | Show when selected scope has no child nodes | WF-HIERARCHY-002 | + +--- + +# 10. Devices Screens + +The Devices module is only for infrastructure devices: gateways, switches, and access points. + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-DEVICE-001 | Device Inventory | Page/Table | List infrastructure devices inside selected scope | WF-DEVICE-001 | +| SCR-DEVICE-002 | Gateways List | Page/Tab | Filtered gateway inventory | WF-DEVICE-001 | +| SCR-DEVICE-003 | Switches List | Page/Tab | Filtered switch inventory | WF-DEVICE-001 | +| SCR-DEVICE-004 | Access Points List | Page/Tab | Filtered AP inventory | WF-DEVICE-001 | +| SCR-DEVICE-005 | Device Detail | Page/Detail | View device identity, status, assignment | WF-DEVICE-001 | +| SCR-DEVICE-006 | Device Diagnostics | Page/Tab | View logs, status, uplink, errors | WF-DEVICE-002 | +| SCR-DEVICE-007 | Device Action Confirmation | Modal | Confirm reboot, upgrade, blink, factory reset | WF-DEVICE-003 | +| SCR-DEVICE-008 | Add Device | Form/Modal | Add infrastructure device by serial/type | WF-DEVICE-004 | +| SCR-DEVICE-009 | Assign Device | Form/Modal | Assign device to node/venue/floor | WF-DEVICE-005 | +| SCR-DEVICE-010 | Move Device | Form/Modal | Move device to another permitted node/venue | WF-DEVICE-006 | +| SCR-DEVICE-011 | Firmware Management | Page/Tab | View firmware state and upgrade eligibility | WF-DEVICE-003 | +| SCR-DEVICE-012 | Device Assignments | Page/Tab | Manage assignment history and current scope | WF-DEVICE-005, WF-DEVICE-006 | +| SCR-DEVICE-013 | Connectivity View | Page/Graph | Engineering topology for device uplinks and connectivity | WF-TOPOLOGY-002 | +| SCR-DEVICE-014 | Device Empty Inventory State | State | Show when no devices exist in selected scope | WF-DEVICE-001 | + +--- + +# 11. Configuration Screens + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-CONFIG-001 | Configuration List | Page/Table | List configuration sets inside selected scope | WF-CONFIG-001, WF-CONFIG-002 | +| SCR-CONFIG-002 | Create Configuration | Form | Create configuration set after resolving current scope | WF-CONFIG-001 | +| SCR-CONFIG-003 | Edit Configuration | Form | Edit configuration settings | WF-CONFIG-002 | +| SCR-CONFIG-004 | Configuration Detail | Page/Detail | View configuration summary, status, assignments | WF-CONFIG-002, WF-CONFIG-003 | +| SCR-CONFIG-005 | Configuration Version History | Page/Tab | View previous versions and change history | WF-CONFIG-002 | +| SCR-CONFIG-006 | Assign Configuration | Form/Modal | Assign configuration to permitted nodes/devices | WF-CONFIG-003 | +| SCR-CONFIG-007 | Effective Configuration Preview | Page/Panel | Preview effective config for node/device and overrides | WF-CONFIG-004 | +| SCR-CONFIG-008 | Configuration Validation Errors | State/Panel | Show invalid settings or conflicts | WF-CONFIG-001, WF-CONFIG-002 | + +--- + +# 12. Topology Screens + +Topology screens are contextual and are not root sidebar screens. + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-TOPOLOGY-001 | Contextual Venue Topology | Tab/Canvas | Default topology view inside selected hierarchy workspace | WF-TOPOLOGY-001 | +| SCR-TOPOLOGY-002 | Site-Level Topology | Tab/Canvas | Building summaries and aggregate health | WF-TOPOLOGY-001 | +| SCR-TOPOLOGY-003 | Building-Level Topology | Tab/Canvas | Floor structure, AP density, distribution summary | WF-TOPOLOGY-001 | +| SCR-TOPOLOGY-004 | Tower-Level Topology | Tab/Canvas | Floor relationships and tower-level health | WF-TOPOLOGY-001 | +| SCR-TOPOLOGY-005 | Floor-Level Topology | Tab/Canvas | AP placement, wireless overlays | WF-TOPOLOGY-001 | +| SCR-TOPOLOGY-006 | Venue-Level Topology | Tab/Canvas | Detailed overlays, AP behavior, coverage visualization | WF-TOPOLOGY-001 | +| SCR-TOPOLOGY-007 | Topology Overlay Controls | Panel | Toggle APs, switches, gateways, health, wireless quality | WF-TOPOLOGY-001 | +| SCR-TOPOLOGY-008 | Topology Device Detail Drawer | Drawer | Inspect selected device from topology | WF-TOPOLOGY-001, WF-DEVICE-001 | + +--- + +# 13. Billing Screens + +Billing screens must enforce direct parent-child plan ownership, eligible plan visibility, and single active subscription behavior. + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-BILLING-001 | Billing Overview | Page/Dashboard | Show billing status, plan summary, and actions for selected scope | WF-BILLING-004 | +| SCR-BILLING-002 | Billing Plan List | Page/Table | List plans user can manage or view | WF-BILLING-001 | +| SCR-BILLING-003 | Create Billing Plan | Form | Create connection-based or fixed-device plan | WF-BILLING-001 | +| SCR-BILLING-004 | Edit Billing Plan | Form | Edit allowed plan fields | WF-BILLING-001 | +| SCR-BILLING-005 | Billing Plan Detail | Page/Detail | View plan details, status, features, pricing, limits | WF-BILLING-001 | +| SCR-BILLING-006 | Activate / Deactivate Plan Confirmation | Modal | Confirm plan status change | WF-BILLING-001 | +| SCR-BILLING-007 | Assign Plan to Customer | Form/Modal | Assign eligible plan to direct child customer/sub-operator | WF-BILLING-002 | +| SCR-BILLING-008 | Available Plans | Page/Cards | Customer/sub-operator views parent-offered active plans | WF-BILLING-003 | +| SCR-BILLING-009 | Select Plan Confirmation | Modal | Confirm selected plan and check existing active subscription | WF-BILLING-003 | +| SCR-BILLING-010 | Replace Existing Plan Confirmation | Modal | Confirm replace-or-reject behavior for existing active subscription | WF-BILLING-003 | +| SCR-BILLING-011 | Current Subscription Detail | Page/Detail | View current subscription, state, plan type, limits, renewal | WF-BILLING-004 | +| SCR-BILLING-012 | Subscription Visibility Dashboard | Page/Table | Operator views permitted child subscriptions | WF-BILLING-004 | +| SCR-BILLING-013 | Connection-Based Billing Detail | Page/Panel | Show connected-device billing details | WF-BILLING-004 | +| SCR-BILLING-014 | Fixed-Device Billing Detail | Page/Panel | Show fixed device limits and usage | WF-BILLING-004 | +| SCR-BILLING-015 | No Available Plans State | State | Show when customer has no eligible plans | WF-BILLING-003 | +| SCR-BILLING-016 | No Active Subscription State | State | Show when no subscription exists | WF-BILLING-004 | +| SCR-BILLING-017 | Billing Conflict State | State | Show single-active-plan conflict or 409 error | WF-BILLING-003 | + +--- + +# 14. Users Screens + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-USER-001 | User List | Page/Table | List users inside selected or permitted scope | WF-USER-001 | +| SCR-USER-002 | Create User | Form | Create user and assign role/profile/scope | WF-USER-001 | +| SCR-USER-003 | User Detail | Page/Detail | View user profile, status, roles, scope | WF-USER-001, WF-USER-002, WF-USER-003 | +| SCR-USER-004 | Edit User | Form | Edit user details where permitted | WF-USER-001 | +| SCR-USER-005 | Assign Role/Profile | Form/Modal | Assign permission profile within allowed authority | WF-USER-001 | +| SCR-USER-006 | Reset Password Confirmation | Modal | Trigger OWSEC password reset flow | WF-USER-002 | +| SCR-USER-007 | Suspend User Confirmation | Modal | Suspend user and optionally revoke active sessions | WF-USER-003 | +| SCR-USER-008 | User Sessions | Page/Tab | View and manage active sessions when permitted | WF-USER-003 | +| SCR-USER-009 | User Scope Assignment Summary | Panel | Show assigned customer/subtree/node scope | WF-USER-001 | + +--- + +# 15. Administration Screens + +| Screen ID | Screen Name | Type | Purpose | Linked Workflows | +| --------- | ----------- | ---- | ------- | ---------------- | +| SCR-ADMIN-001 | Administration Overview | Page | Entry point for platform/operator administration | WF-ADMIN-001 | +| SCR-ADMIN-002 | Platform Settings | Page/Form | Manage global settings when permitted | WF-ADMIN-001 | +| SCR-ADMIN-003 | Operator Administration | Page/Table | Manage operator-level settings and child operator context | WF-ADMIN-001 | +| SCR-ADMIN-004 | Roles and Policies | Page/Table | View and manage role/policy profiles | WF-ADMIN-001 | +| SCR-ADMIN-005 | Edit Role / Policy | Form | Edit permitted role or policy settings | WF-ADMIN-001 | +| SCR-ADMIN-006 | Audit Logs | Page/Table | View permitted audit events | WF-ADMIN-002 | +| SCR-ADMIN-007 | Audit Event Detail | Page/Drawer | Inspect selected audit event | WF-ADMIN-002 | +| SCR-ADMIN-008 | Advanced / Debug Views | Page | Internal troubleshooting views for permitted admins | Admin support | +| SCR-ADMIN-009 | Permission Change Impact Warning | Modal | Warn before sensitive RBAC changes | WF-ADMIN-001 | + +--- + +# 16. Screen Coverage by Workflow + +| Workflow Area | Required Screens | +| ------------ | ---------------- | +| Dashboard | SCR-DASHBOARD-001 to SCR-DASHBOARD-005 | +| Authentication | SCR-AUTH-001 to SCR-AUTH-007 | +| Customer/Sub-Operator | SCR-CUSTOMER-001 to SCR-CUSTOMER-010 | +| Billing | SCR-BILLING-001 to SCR-BILLING-017 | +| Hierarchy | SCR-HIERARCHY-001 to SCR-HIERARCHY-012 | +| Devices | SCR-DEVICE-001 to SCR-DEVICE-014 | +| Configurations | SCR-CONFIG-001 to SCR-CONFIG-008 | +| Topology | SCR-TOPOLOGY-001 to SCR-TOPOLOGY-008 | +| Users | SCR-USER-001 to SCR-USER-009 | +| Administration | SCR-ADMIN-001 to SCR-ADMIN-009 | +| Global Shell / States | SCR-SHELL-001 to SCR-SHELL-011 | + +--- + +# 17. Recommended Figma Page Organization + +Recommended Figma pages: + +```text +00 - Cover and Notes +01 - App Shell and Navigation +02 - Authentication +03 - Dashboard +04 - Customers +05 - Hierarchy Workspace +06 - Devices +07 - Configurations +08 - Topology +09 - Billing +10 - Users +11 - Administration +12 - System States +13 - Prototype Flows +``` + +Recommended frame naming: + +```text +SCR-HIERARCHY-005 - Node Topology Tab +SCR-BILLING-009 - Select Plan Confirmation +``` + +--- + +# 18. Recommended Wireframing Priority + +Use this order for low-fidelity wireframes: + +```text +1. Main App Shell and Navigation +2. Top App Header and Scope Breadcrumb Bar +3. Hierarchy Workspace Shell +4. Dashboard +5. Customers +6. Devices +7. Topology +8. Configurations +9. Billing +10. Users +11. Administration +12. System States +``` + +Reason: + +```text +Hierarchy context is the highest UX risk. +``` + +The app shell, Top App Header, Scope Breadcrumb Bar, and hierarchy workspace should be validated before detailed module wireframes. + +--- + +# 19. Screens Requiring Detailed RBAC and State Definitions + +The following screens must receive detailed RBAC and system-state definitions in `screen-definitions.md`. + +## High Priority + +* SCR-SHELL-001 - Main App Shell +* SCR-SHELL-002 - Scope Breadcrumb Bar / Scope Selector +* SCR-SHELL-003 - Top App Header +* SCR-HIERARCHY-003 - Node Workspace Shell +* SCR-HIERARCHY-005 - Node Topology Tab +* SCR-DEVICE-005 - Device Detail +* SCR-DEVICE-013 - Connectivity View +* SCR-BILLING-003 - Create Billing Plan +* SCR-BILLING-008 - Available Plans +* SCR-BILLING-009 - Select Plan Confirmation +* SCR-BILLING-011 - Current Subscription Detail +* SCR-CONFIG-007 - Effective Configuration Preview +* SCR-ADMIN-004 - Roles and Policies + +## Required State Coverage + +Each important screen must define: + +```text +Loading +Empty +No Permission +Backend Unavailable +Partial Data +Success +Error +Read-only +Hidden Action +Disabled Action +``` + +--- + +# 20. Inventory Acceptance Checklist + +This inventory is complete when: + +* Every in-scope workflow from `workflows.md` maps to at least one screen. +* Every in-scope sidebar module for this phase has at least one screen. +* Hierarchy workspace tabs are represented. +* Topology appears only as contextual hierarchy workspace or device connectivity view. +* Billing includes plan management, assignment, available plans, and subscription screens. +* User management and administration screens are included. +* Global error, permission, empty, and backend unavailable states are included. +* Screens are ready to be expanded in `screen-definitions.md`. + +--- +# 21. Design Scope for This Phase + +This screen inventory intentionally covers only the first-phase design scope. + +Included modules: + +- Global Shell +- Authentication +- Dashboard +- Hierarchy +- Topology +- Devices +- Configuration +- Customers / Sub-Operators +- Billing +- Users +- Administration + +Deferred modules: + +- Clients +- Rollouts +- Maps +- Metrics +- AI Agent + +These deferred modules are part of the full MDU UI specification, but they are intentionally excluded from this phase of screen inventory and will be handled in later design phases. + +# 22. Final Summary + +This screen inventory defines the required screens for the MDU UI design system. + +It supports: + +* Recursive hierarchy navigation +* Scope Breadcrumb Bar selected-scope behavior +* Operational sidebar modules +* Customer/sub-operator management +* Billing and subscription management +* Topology as contextual visualization +* Configuration workflows +* RBAC-aware navigation and screen visibility +* Backend outage and system-state handling + +Next document: + +```text +screen-definitions.md +``` + +The next phase should define each important screen's purpose, primary actions, KPIs, hierarchy dependency, RBAC visibility, loading states, empty states, no-permission states, backend-unavailable states, and error states. diff --git a/ui-docs/plan-phases/wireframe-plan.md b/ui-docs/plan-phases/wireframe-plan.md new file mode 100644 index 0000000..68374f6 --- /dev/null +++ b/ui-docs/plan-phases/wireframe-plan.md @@ -0,0 +1,1021 @@ +# MDU UI - Wireframe Plan + +## 1. Purpose + +This document defines the low-fidelity wireframe plan for the first-phase MDU UI. + +It is the Phase 6 design document after: + +```text +1. workflows.md +2. figma-navigation-model.md +3. screen-inventory.md +4. screen-definitions.md +5. layout-system.md +6. wireframe-plan.md +``` + +The goal of this document is to define: + +```text +Which Figma wireframes to create +Which workflow flows to wireframe +Which prototype paths to connect +Which RBAC states to show +Which loading / empty / error / no-permission states to include +``` + +This document should be used before building the actual Figma low-fidelity wireframes and clickable prototype. + +--- + +## 2. Source Documents + +This wireframe plan is based on: + +```text +mdu-ui-spec.md +workflows.md +figma-navigation-model.md +screen-inventory.md +screen-definitions.md +layout-system.md +``` + +The source of truth is: + +```text +mdu-ui-spec.md = product direction +workflows.md = operational workflow behavior +figma-navigation-model.md = navigation and prototype rules +screen-inventory.md = required screens +screen-definitions.md = screen purpose, RBAC, and states +layout-system.md = reusable layout patterns +wireframe-plan.md = Figma execution plan +``` + +--- + +## 3. Phase Scope + +## 3.1 In-scope modules + +This wireframe plan covers only the first-phase modules: + +```text +Global Shell +Authentication +Dashboard +Hierarchy +Topology +Devices +Configuration +Customers / Sub-Operators +Billing +Users +Administration +``` + +## 3.2 Deferred modules + +These modules are intentionally deferred: + +```text +Clients +Rollouts +Maps +Metrics +AI Agent +``` + +Deferred modules should not be wireframed in this phase, except where placeholders are needed to show future tab/module behavior. + +--- + +## 4. Wireframing Principles + +## 4.1 Start low-fidelity + +Wireframes should focus on: + +```text +layout +navigation +hierarchy context +workflow flow +RBAC visibility +system states +information priority +``` + +Avoid detailed visual styling at this phase: + +```text +colors +branding polish +icons finalization +visual effects +pixel-perfect spacing +production UI details +``` + +--- + +## 4.2 Use reusable layouts + +All wireframes must use the layouts defined in `layout-system.md`: + +```text +App Shell +Auth +Dashboard +Hierarchy Workspace +List + Detail +Form + Confirmation +Topology Canvas +System State +``` + +Do not create one-off page structures unless a screen cannot fit a reusable layout. + +--- + +## 4.3 Use updated shell model + +All authenticated wireframes must use: + +```text +Top App Header = GLOBAL product controls +Sidebar = WHAT the user wants to do +Scope Breadcrumb Bar = WHERE the user is working +Workspace Tabs = HOW the user works inside selected scope +``` + +Top App Header contains: + +```text +Logo +Global search +Notifications +Help +User profile +``` + +Scope Breadcrumb Bar shows: + +```text +Operator > Customer > Sub-Operator > Site > Building > Floor > Venue +``` + +--- + +## 4.4 Wireframe by workflow + +Do not wireframe only isolated pages. + +Each major flow should show: + +```text +Entry point +Scope context +Primary screen +User action +Result screen +Error / empty / permission state where important +``` + +--- + +## 4.5 Scope and RBAC must be visible + +Every scoped wireframe should clearly show: + +```text +selected hierarchy scope +current role / role behavior where useful +hidden or disabled actions +read-only behavior +no-permission state +``` + +--- + +## 5. Figma Page Structure + +Create these Figma pages: + +```text +00 - Cover and Notes +01 - App Shell and Components +02 - Authentication +03 - Dashboard +04 - Hierarchy Workspace +05 - Topology +06 - Devices +07 - Configuration +08 - Customers +09 - Billing +10 - Users +11 - Administration +12 - System States +13 - Prototype Flows +14 - Mobile Wireframes +``` + +--- + +## 6. Figma Frame Naming Convention + +Use this format: + +```text +[Screen ID] - [Screen Name] - [Role] - [State] - [Viewport] +``` + +Examples: + +```text +SCR-DASHBOARD-002 - Scoped Dashboard - Customer Admin - Default - Desktop +SCR-HIERARCHY-005 - Node Topology Tab - NOC - Loading - Desktop +SCR-BILLING-008 - Available Plans - Customer Admin - Empty - Desktop +SCR-DEVICE-005 - Device Detail - Read Only - Default - Desktop +SCR-SHELL-002 - Scope Breadcrumb Bar - Operator Admin - Open - Desktop +``` + +For prototype flow frames, use: + +```text +FLOW-[NUMBER] - [Flow Name] - [Step Number] - [Screen Name] +``` + +Example: + +```text +FLOW-003 - Hierarchy Topology - 01 - Dashboard +FLOW-003 - Hierarchy Topology - 02 - Select Scope +FLOW-003 - Hierarchy Topology - 03 - Floor Workspace +FLOW-003 - Hierarchy Topology - 04 - Topology Tab +``` + +--- + +## 7. Wireframe Creation Order + +Use this order to reduce UX risk: + +```text +1. App Shell +2. Top App Header +3. Scope Breadcrumb Bar +4. Sidebar Navigation +5. System States +6. Authentication +7. Dashboard +8. Hierarchy Workspace +9. Topology Tab +10. Devices +11. Configuration +12. Customers +13. Billing +14. Users +15. Administration +16. Mobile / Responsive Variants +17. Prototype Flow Wiring +``` + +Reason: + +```text +Hierarchy context and scope switching are the highest UX risks. +``` + +The shell, scope selector, and hierarchy workspace should be validated before detailed module wireframes. + +--- + +## 8. Required Core Wireframes + +## 8.1 Global Shell + +| Frame | Purpose | +|---|---| +| SCR-SHELL-001 - Main App Shell - Default - Desktop | Base authenticated layout. | +| SCR-SHELL-001 - Main App Shell - Sidebar Collapsed - Desktop | Collapsed sidebar behavior. | +| SCR-SHELL-002 - Scope Breadcrumb Bar - Default - Desktop | Shows selected scope path. | +| SCR-SHELL-002 - Scope Breadcrumb Bar - Open - Desktop | Shows breadcrumb dropdown/scope selector. | +| SCR-SHELL-003 - Top App Header - Default - Desktop | Logo, search, notifications, help, user. | +| SCR-SHELL-004 - Global Search - Open - Desktop | Search permitted resources. | +| SCR-SHELL-005 - User Profile Menu - Open - Desktop | Profile, role, change password, logout. | + +--- + +## 8.2 Authentication + +| Frame | Purpose | +|---|---| +| SCR-AUTH-001 - Login - Default | OWSEC login. | +| SCR-AUTH-001 - Login - Invalid Credentials | Error state. | +| SCR-AUTH-002 - Forgot Password | Password recovery start. | +| SCR-AUTH-003 - Reset Password | Password reset completion. | +| SCR-AUTH-005 - Session Expired | Expired session state. | +| SCR-AUTH-007 - Backend Bootstrap Failed | Auth succeeded but MDU backend failed. | + +--- + +## 8.3 Dashboard + +| Frame | Purpose | +|---|---| +| SCR-DASHBOARD-001 - Global Dashboard - Operator Admin - Desktop | Operator/global overview. | +| SCR-DASHBOARD-002 - Scoped Dashboard - Customer Admin - Desktop | Selected customer/site/node dashboard. | +| SCR-DASHBOARD-002 - Scoped Dashboard - Loading | Loading state. | +| SCR-DASHBOARD-002 - Scoped Dashboard - Partial Data | Some panels failed. | +| SCR-DASHBOARD-005 - Billing Summary Panel - Hidden | Billing hidden for unauthorized roles. | + +Dashboard must show: + +```text +selected scope +KPI cards +health summary +recent alerts +device summary +billing summary if permitted +quick actions if permitted +``` + +--- + +## 8.4 Hierarchy + +| Frame | Purpose | +|---|---| +| SCR-HIERARCHY-001 - Hierarchy Module - Default | Entry to hierarchy module. | +| SCR-HIERARCHY-002 - Hierarchy Tree - Expanded | Recursive tree. | +| SCR-HIERARCHY-003 - Node Workspace Shell - Overview | Selected node workspace. | +| SCR-HIERARCHY-004 - Node Overview Tab | Node summary. | +| SCR-HIERARCHY-006 - Node Devices Tab | Devices in node scope. | +| SCR-HIERARCHY-007 - Node Configurations Tab | Assigned/effective configs. | +| SCR-HIERARCHY-008 - Create Node Modal | Create hierarchy node. | +| SCR-HIERARCHY-010 - Move Node Modal | Move node workflow. | +| SCR-HIERARCHY-011 - Delete Node Confirmation | Destructive confirmation. | +| SCR-HIERARCHY-012 - Empty Hierarchy State | No child nodes. | + +Hierarchy workspace tabs for this phase: + +```text +Overview +Topology +Devices +Configurations +``` + +Deferred tabs should not be active: + +```text +Clients +Maps +Metrics +AI Insights +``` + +--- + +## 8.5 Topology + +| Frame | Purpose | +|---|---| +| SCR-HIERARCHY-005 - Node Topology Tab - Floor - Default | Floor topology view. | +| SCR-TOPOLOGY-002 - Site-Level Topology | Site aggregate topology. | +| SCR-TOPOLOGY-003 - Building-Level Topology | Building/floor summary. | +| SCR-TOPOLOGY-005 - Floor-Level Topology | AP placement and overlays. | +| SCR-TOPOLOGY-007 - Overlay Controls - Open | Toggle overlays. | +| SCR-TOPOLOGY-008 - Device Detail Drawer - Open | Selected device detail. | +| SCR-TOPOLOGY-001 - No Topology Data | Empty topology state. | +| SCR-TOPOLOGY-001 - Backend Unavailable | Backend-down state. | + +Topology rules: + +```text +Topology is not a root sidebar module. +Topology appears inside hierarchy workspace. +Device connectivity topology appears under Devices. +Unauthorized devices and overlays are hidden. +``` + +--- + +## 8.6 Devices + +| Frame | Purpose | +|---|---| +| SCR-DEVICE-001 - Device Inventory - Default | List devices in selected scope. | +| SCR-DEVICE-001 - Device Inventory - Empty | No devices in scope. | +| SCR-DEVICE-005 - Device Detail - Default | Device identity/status/assignment. | +| SCR-DEVICE-006 - Device Diagnostics | Logs/status/uplink/errors. | +| SCR-DEVICE-007 - Device Action Confirmation | Reboot/upgrade/blink/factory reset. | +| SCR-DEVICE-008 - Add Device Modal | Add device by serial/type. | +| SCR-DEVICE-009 - Assign Device Modal | Assign device to node/venue/floor. | +| SCR-DEVICE-013 - Connectivity View | Engineering topology for device links. | +| SCR-DEVICE-013 - Connectivity View - Partial Data | Some link data missing. | + +--- + +## 8.7 Configuration + +| Frame | Purpose | +|---|---| +| SCR-CONFIG-001 - Configuration List - Default | List scoped configs. | +| SCR-CONFIG-002 - Create Configuration | Create config set. | +| SCR-CONFIG-004 - Configuration Detail | Config summary and assignments. | +| SCR-CONFIG-006 - Assign Configuration | Assign config to nodes/devices. | +| SCR-CONFIG-007 - Effective Configuration Preview | Show inherited/assigned/overridden values. | +| SCR-CONFIG-008 - Validation Errors | Invalid configuration state. | + +--- + +## 8.8 Customers + +| Frame | Purpose | +|---|---| +| SCR-CUSTOMER-001 - Customer List - Default | List permitted customers/sub-operators. | +| SCR-CUSTOMER-002 - Create Customer Wizard - Step 1 | Customer details. | +| SCR-CUSTOMER-002 - Create Customer Wizard - Step 2 | First admin user. | +| SCR-CUSTOMER-002 - Create Customer Wizard - Step 3 | Optional billing assignment. | +| SCR-CUSTOMER-002 - Create Customer Wizard - Review | Review and create. | +| SCR-CUSTOMER-003 - Customer Detail | Customer profile/status/scope. | +| SCR-CUSTOMER-007 - Customer Workspace | Customer contextual workspace. | +| SCR-CUSTOMER-008 - Customer Billing Tab | Customer billing summary/assignment. | +| SCR-CUSTOMER-005 - Suspend Confirmation | Suspend customer. | +| SCR-CUSTOMER-006 - Delete Confirmation | Delete customer. | + +--- + +## 8.9 Billing + +| Frame | Purpose | +|---|---| +| SCR-BILLING-001 - Billing Overview - Operator Admin | Billing management overview. | +| SCR-BILLING-002 - Billing Plan List | List plans. | +| SCR-BILLING-003 - Create Billing Plan - Step 1 | Select plan type. | +| SCR-BILLING-003 - Create Billing Plan - Step 2 | Plan details. | +| SCR-BILLING-003 - Create Billing Plan - Step 3 | Pricing and limits. | +| SCR-BILLING-007 - Assign Plan to Customer | Assign to direct child. | +| SCR-BILLING-008 - Available Plans - Customer Admin | Customer views eligible plans. | +| SCR-BILLING-009 - Select Plan Confirmation | Confirm selection. | +| SCR-BILLING-010 - Replace Existing Plan Confirmation | Existing subscription conflict. | +| SCR-BILLING-011 - Current Subscription Detail | Current plan/subscription. | +| SCR-BILLING-015 - No Available Plans | Empty state. | +| SCR-BILLING-017 - Billing Conflict State | 409/single-active-plan conflict. | + +Billing rules: + +```text +Parent operator manages plans. +Customer views eligible parent-offered active plans. +Customer cannot edit parent-created plans. +Only one active subscription is allowed. +Sibling subscriptions are never visible. +``` + +--- + +## 8.10 Users + +| Frame | Purpose | +|---|---| +| SCR-USER-001 - User List - Default | List scoped users. | +| SCR-USER-002 - Create User | Create user and assign role/profile/scope. | +| SCR-USER-003 - User Detail | User profile/status/roles/scope. | +| SCR-USER-005 - Assign Role Profile | Role/profile assignment. | +| SCR-USER-006 - Reset Password Confirmation | Trigger password reset. | +| SCR-USER-007 - Suspend User Confirmation | Suspend user. | +| SCR-USER-009 - User Scope Assignment Summary | Show assigned scope. | + +--- + +## 8.11 Administration + +| Frame | Purpose | +|---|---| +| SCR-ADMIN-001 - Administration Overview | Entry admin screen. | +| SCR-ADMIN-004 - Roles and Policies | Role/policy profiles. | +| SCR-ADMIN-005 - Edit Role Policy | Edit permitted role/policy. | +| SCR-ADMIN-006 - Audit Logs | Scoped audit logs. | +| SCR-ADMIN-007 - Audit Event Detail | Selected audit event. | +| SCR-ADMIN-009 - Permission Change Impact Warning | RBAC change confirmation. | +| SCR-ADMIN-001 - No Permission | No admin access state. | + +--- + +## 9. Required Workflow Wireframes + +## 9.1 FLOW-001 - Login and Dashboard + +```text +Login +-> Submit credentials +-> Backend bootstrap +-> Global / scoped dashboard +-> User menu +-> Logout +-> Login +``` + +Required frames: + +```text +SCR-AUTH-001 +SCR-AUTH-007 +SCR-DASHBOARD-001 +SCR-DASHBOARD-002 +SCR-SHELL-005 +SCR-AUTH-006 +``` + +--- + +## 9.2 FLOW-002 - Scope Switching + +```text +Dashboard +-> Open Scope Breadcrumb Bar +-> Select Customer/Site/Floor +-> Scope updates +-> Dashboard refreshes +``` + +Required frames: + +```text +SCR-DASHBOARD-002 +SCR-SHELL-002 +SCR-HIERARCHY-002 +SCR-HIERARCHY-003 +``` + +Show these states: + +```text +Scope loading +Scope changed +No permission for selected scope +Backend unavailable +``` + +--- + +## 9.3 FLOW-003 - Hierarchy to Topology + +```text +Dashboard +-> Hierarchy +-> Expand tree +-> Select Floor +-> Node Workspace +-> Topology Tab +-> Toggle overlays +-> Select device +-> Device Detail Drawer +``` + +Required frames: + +```text +SCR-HIERARCHY-001 +SCR-HIERARCHY-002 +SCR-HIERARCHY-003 +SCR-HIERARCHY-005 +SCR-TOPOLOGY-007 +SCR-TOPOLOGY-008 +``` + +--- + +## 9.4 FLOW-004 - Device Diagnostics + +```text +Devices +-> Device Inventory +-> Select AP +-> Device Detail +-> Diagnostics +-> Device action confirmation +``` + +Required frames: + +```text +SCR-DEVICE-001 +SCR-DEVICE-005 +SCR-DEVICE-006 +SCR-DEVICE-007 +``` + +Show role variants: + +```text +NOC/Support +Customer Admin +Read-only +Installer +``` + +--- + +## 9.5 FLOW-005 - Create Customer + +```text +Customers +-> Customer List +-> Create Customer +-> Customer details +-> First admin user +-> Optional billing assignment +-> Review +-> Success +-> Customer Workspace +``` + +Required frames: + +```text +SCR-CUSTOMER-001 +SCR-CUSTOMER-002 +SCR-CUSTOMER-007 +SCR-CUSTOMER-008 +``` + +--- + +## 9.6 FLOW-006 - Billing Plan Selection + +```text +Billing +-> Available Plans +-> Select Plan +-> Existing subscription check +-> Confirm selection +-> Current Subscription +``` + +Required frames: + +```text +SCR-BILLING-008 +SCR-BILLING-009 +SCR-BILLING-010 +SCR-BILLING-011 +SCR-BILLING-017 +``` + +--- + +## 9.7 FLOW-007 - Create Billing Plan + +```text +Billing +-> Billing Plan List +-> Create Billing Plan +-> Select plan type +-> Enter details +-> Pricing and limits +-> Review +-> Save +-> Billing Plan Detail +``` + +Required frames: + +```text +SCR-BILLING-002 +SCR-BILLING-003 +SCR-BILLING-005 +``` + +--- + +## 9.8 FLOW-008 - Create User + +```text +Users +-> User List +-> Create User +-> Assign role/profile +-> Assign scope +-> Save +-> User Detail +``` + +Required frames: + +```text +SCR-USER-001 +SCR-USER-002 +SCR-USER-003 +SCR-USER-005 +SCR-USER-009 +``` + +--- + +## 9.9 FLOW-009 - Administration Role Change + +```text +Administration +-> Roles and Policies +-> Edit Role / Policy +-> Review impact warning +-> Save +-> Audit Logs +``` + +Required frames: + +```text +SCR-ADMIN-004 +SCR-ADMIN-005 +SCR-ADMIN-009 +SCR-ADMIN-006 +``` + +--- + +## 9.10 FLOW-010 - Backend Unavailable + +```text +Any scoped screen +-> Backend unavailable +-> Retry +-> Recovered or remains unavailable +``` + +Required frames: + +```text +SCR-SHELL-007 +SCR-AUTH-007 +SCR-DASHBOARD-002 - Backend Unavailable +SCR-DEVICE-001 - Backend Unavailable +SCR-BILLING-001 - Backend Unavailable +``` + +--- + +## 10. RBAC Variants to Wireframe + +Create RBAC variants for high-risk screens. + +| Screen | Required role variants | +|---|---| +| Main App Shell | Operator Admin, Customer Admin, NOC/Support, Installer, Billing/Admin, Read-only | +| Dashboard | Operator Admin, Customer Admin, NOC/Support, Billing/Admin, Read-only | +| Hierarchy Workspace | Operator Admin, Customer Admin, Installer, Read-only | +| Node Topology Tab | NOC/Support, Customer Admin, Installer, Read-only | +| Device Detail | NOC/Support, Customer Admin, Installer, Read-only | +| Billing Available Plans | Customer Admin, Billing/Admin, Read-only | +| Create Billing Plan | Operator Admin, Billing/Admin, No Permission | +| User List | Operator Admin, Customer Admin, Read-only | +| Roles and Policies | Root/Operator Admin, No Permission | + +--- + +## 11. System State Wireframes + +Create reusable state frames first, then reuse them in modules. + +## 11.1 Required global state frames + +```text +State - Loading +State - Empty +State - Error +State - No Permission +State - Backend Unavailable +State - Partial Data +State - Not Found +State - Confirmation Required +State - Success +``` + +## 11.2 Module-specific states + +| Module | Required states | +|---|---| +| Dashboard | Loading, partial data, backend unavailable. | +| Hierarchy | Empty hierarchy, node unavailable, no permission. | +| Topology | No topology data, no map available, partial data. | +| Devices | Empty inventory, device offline, action failed. | +| Configuration | Validation errors, no eligible targets. | +| Customers | Duplicate customer, delete blocked, permission denied. | +| Billing | No available plans, no active subscription, billing conflict. | +| Users | Duplicate email, invalid role, no permission. | +| Administration | No admin permission, impact warning, audit logs empty. | + +--- + +## 12. Prototype Paths + +The clickable prototype should include these minimum paths: + +```text +1. Login -> Dashboard +2. Dashboard -> Scope Breadcrumb Bar -> Change Scope +3. Dashboard -> Hierarchy -> Select Floor -> Topology Tab +4. Topology Tab -> Overlay Controls -> Device Detail Drawer +5. Devices -> Device Detail -> Diagnostics +6. Customers -> Create Customer -> Customer Workspace +7. Billing -> Available Plans -> Select Plan -> Current Subscription +8. Billing -> Create Billing Plan -> Plan Detail +9. Users -> Create User -> User Detail +10. Administration -> Roles and Policies -> Impact Warning +11. Any screen -> No Permission +12. Any screen -> Backend Unavailable -> Retry +``` + +Prototype interactions should be documented in Figma using frame links and flow labels. + +--- + +## 13. Mobile Wireframes + +Create mobile variants only for the most important flows. + +## 13.1 Required mobile frames + +```text +Mobile - App Shell - Drawer Closed +Mobile - App Shell - Drawer Open +Mobile - Scope Selector +Mobile - Dashboard +Mobile - Hierarchy Tree Picker +Mobile - Hierarchy Workspace +Mobile - Device Inventory +Mobile - Device Detail +Mobile - Billing Available Plans +Mobile - No Permission +Mobile - Backend Unavailable +``` + +## 13.2 Mobile behavior + +```text +Sidebar becomes drawer +Scope Breadcrumb Bar becomes compact selector +Tables become cards +Detail drawers become full-screen panels +Topology controls become bottom sheet +Workspace tabs scroll horizontally +``` + +--- + +## 14. Figma Component Priorities + +Create these components before full screen wireframes. + +## 14.1 Shell components + +```text +Shell/TopAppHeader +Shell/Sidebar +Shell/SidebarItem +Shell/ScopeBreadcrumbBar +Shell/GlobalSearchOverlay +Shell/UserProfileMenu +``` + +## 14.2 Content components + +```text +Content/PageHeader +Content/KPICard +Content/SummaryCard +Content/StatusBadge +Content/WorkspaceTabs +``` + +## 14.3 Table and form components + +```text +Table/DataTable +Table/FilterBar +Table/RowActions +Form/TextInput +Form/Select +Form/ScopeSelector +Form/StepIndicator +Form/ValidationMessage +Modal/Confirmation +``` + +## 14.4 Topology components + +```text +Topology/Canvas +Topology/OverlayControls +Topology/DeviceMarker +Topology/Link +Topology/DetailDrawer +``` + +## 14.5 State components + +```text +State/Loading +State/Empty +State/NoPermission +State/BackendUnavailable +State/Error +State/PartialData +State/Confirmation +State/SuccessToast +``` + +--- + +## 15. Wireframe Acceptance Checklist + +The wireframe plan is complete when: + +- All first-phase modules have at least one required wireframe. +- The Top App Header and Scope Breadcrumb Bar are represented correctly. +- Scope switching is shown as a core prototype flow. +- Hierarchy workspace and topology flow are represented. +- Topology is not a root sidebar module. +- Device connectivity topology remains under Devices. +- Billing parent-child scope isolation is represented. +- High-risk RBAC variants are included. +- Loading, empty, error, no-permission, backend-unavailable, partial-data, and confirmation states are included. +- Mobile variants are defined for important flows. +- Prototype paths are listed and ready to build in Figma. +- Deferred modules are not expanded in this phase. + +--- + +## 16. Final Output of This Phase + +The output of this phase is: + +```text +wireframe-plan.md +``` + +After this document is approved, create in Figma: + +```text +Low-fidelity wireframe frames +Reusable components +Workflow wireframe sequences +Clickable prototype paths +RBAC and system-state variants +``` + +--- + +## 17. Next Step + +After `wireframe-plan.md`, proceed to: + +```text +Figma low-fidelity wireframes +Figma clickable prototype +``` + +Recommended prototype build order: + +```text +1. App Shell +2. Dashboard +3. Scope switching +4. Hierarchy workspace +5. Topology tab +6. Device detail and diagnostics +7. Billing plan selection +8. Customer creation +9. User creation +10. Administration role change +11. System states +12. Mobile variants +``` + +--- + +## 18. Final Summary + +This wireframe plan converts all previous MDU UI design documents into an execution-ready Figma plan. + +It defines: + +```text +required wireframes +workflow sequences +RBAC variants +system-state frames +prototype paths +mobile variants +component priorities +``` + +This is the final Markdown planning phase before creating the Figma low-fidelity prototype. + diff --git a/ui-docs/plan-phases/workflows.md b/ui-docs/plan-phases/workflows.md new file mode 100644 index 0000000..df2c9de --- /dev/null +++ b/ui-docs/plan-phases/workflows.md @@ -0,0 +1,1696 @@ +# MDU UI - Operational Workflows + +# 1. Purpose + +This document defines the major operational workflows in the MDU UI platform. + +It answers: + +```text +WHO performs WHAT action in WHICH scope +``` + +This document is used as the foundation for: + +* screen design +* wireframing +* RBAC behavior +* navigation flows +* frontend implementation +* workflow-to-screen mapping + +--- + +# 2. Workflow Model + +Each workflow is defined using: + +```text +Workflow ID +Actor +Action +Scope +Entry Point +Flow +Outcome +RBAC Constraints +Failure/Edge Cases +``` + +Workflow IDs are used to connect this document with screen inventory, screen definitions, wireframes, and acceptance checks. + +--- + +# 3. Actor Definitions + +| Actor | Description | +| ----- | ----------- | +| Root Operator | Platform-level administrator with global platform access. | +| Operator Admin | Manages direct child customers/sub-operators and resources within the operator subtree. | +| Customer Admin | Manages its own customer/sub-operator subtree. | +| NOC/Support | Monitors health, investigates issues, and performs diagnostics. | +| Installer | Performs deployment, setup, map placement, and device installation workflows. | +| Billing/Admin | Manages billing plans, subscriptions, and billing visibility according to scope. | +| AI Assistant | Scope-aware system assistant that supports diagnostics, recommendations, workflow guidance, and operational insights. | + +--- + +# 4. Core Workflows + +--- + +# 4.1 Authentication Workflows + +## 4.1.1 Login + +* Workflow ID: WF-AUTH-001 +* Actor: All users +* Scope: Global + +Entry Point: + +```text +Login Screen +``` + +Flow: + +```text +Login Screen +-> Enter Credentials +-> OWSEC Auth +-> Token Issued +-> Backend Bootstrap +-> Redirect Dashboard +``` + +Outcome: + +* User session is created. +* Access token is stored in memory. +* Refresh token is stored in secure cookie. +* User lands on the appropriate dashboard based on role and scope. + +Failure/Edge Cases: + +* Invalid credentials +* Account locked +* OWSEC unavailable +* Backend bootstrap unavailable +* Token validation failed + +--- + +## 4.1.2 Session Refresh + +* Workflow ID: WF-AUTH-002 +* Actor: All users +* Scope: Current user session + +Flow: + +```text +Token nearing expiry +-> Silent refresh through OWSEC +-> New access token issued +-> Continue session +``` + +Outcome: + +* User remains logged in without disruption. + +Failure/Edge Cases: + +```text +Refresh failed +-> Clear session +-> Logout user +-> Redirect login +``` + +--- + +## 4.1.3 Logout + +* Workflow ID: WF-AUTH-003 +* Actor: All users +* Scope: Current user session + +Flow: + +```text +User selects Logout +-> Clear local session state +-> Call OWSEC logout +-> Synchronize logout across tabs +-> Redirect login +``` + +Outcome: + +* User session ends safely. +* All open browser tabs are logged out. + +Failure/Edge Cases: + +* OWSEC logout unavailable +* Local session cleanup still succeeds +* Other tabs must still receive logout event + +--- + +# 4.2 Customer/Sub-Operator Management Workflows + +## 4.2.1 Create Customer/Sub-Operator + +* Workflow ID: WF-CUSTOMER-001 +* Actor: Operator Admin +* Scope: Operator subtree + +Entry Point: + +```text +Sidebar -> Customers -> Create Customer +``` + +Flow: + +```text +Open Create Customer Form +-> Enter customer/sub-operator details +-> Enter first admin user details +-> Optional billing plan assignment +-> Submit +-> Backend orchestration +-> Success +-> Redirect to Customer Workspace +``` + +Outcome: + +* Customer/sub-operator is created. +* First admin user is created. +* RBAC role/policy is configured. +* Customer receives its own subtree scope. + +RBAC Constraints: + +* Only authorized operator-level users can create child customers/sub-operators. +* Customer must be created only inside the actor's allowed subtree. + +Failure/Edge Cases: + +* Duplicate customer name +* Invalid admin user details +* Permission denied +* Backend orchestration failure +* Billing plan assignment failure + +--- + +## 4.2.2 View Customer Workspace + +* Workflow ID: WF-CUSTOMER-002 +* Actor: Operator Admin / Customer Admin +* Scope: Selected customer/sub-operator subtree + +Entry Point: + +```text +Sidebar -> Customers -> Select Customer +``` + +Flow: + +```text +Select Customer +-> Load Customer Workspace +-> Show contextual tabs +-> Overview | Devices | Clients | Topology | Billing | Users | Metrics +``` + +Outcome: + +* User views the customer workspace according to role and scope. + +RBAC Constraints: + +* Users can only view customers inside their allowed subtree. +* Sibling customer/sub-operator workspaces must not be visible. + +Failure/Edge Cases: + +* Customer not found +* Permission denied +* Backend unavailable + +--- + +## 4.2.3 Suspend or Delete Customer/Sub-Operator + +* Workflow ID: WF-CUSTOMER-003 +* Actor: Operator Admin +* Scope: Direct child customer/sub-operator + +Entry Point: + +```text +Customers -> Customer Detail -> Actions +``` + +Flow: + +```text +Open Customer Detail +-> Select Suspend or Delete +-> Review impact warning +-> Confirm action +-> Backend validates scope and permission +-> Status updated +``` + +Outcome: + +* Customer/sub-operator status is updated according to the selected action. + +RBAC Constraints: + +* Actor can only manage allowed direct or scoped child customers/sub-operators. +* Destructive actions must be permission-gated. + +Failure/Edge Cases: + +* Active dependencies prevent deletion +* Permission denied +* Customer has active subscription or devices +* Backend unavailable + +--- + +# 4.3 Billing and Subscription Workflows + +## 4.3.1 Create Billing Plan + +* Workflow ID: WF-BILLING-001 +* Actor: Operator Admin / Billing Admin +* Scope: Operator billing scope + +Entry Point: + +```text +Sidebar -> Billing -> Plans -> Create Plan +``` + +Flow: + +```text +Open Create Plan Form +-> Select plan type: connection-based or fixed-device +-> Enter plan name, description, limits, features, and pricing +-> For connection-based plan, configure monthly charge per connected device +-> For fixed-device plan, configure fixed device limit and billing cycle: monthly, yearly, or free +-> Set plan status +-> Save +``` + +Outcome: + +* Billing plan is created inside the operator scope. +* Plan is created as either a connection-based plan or a fixed-device plan. + +RBAC Constraints: + +* Parent operator can create billing plans for its own billing scope. +* Child customers/sub-operators cannot create or modify parent-created billing plans. + +Failure/Edge Cases: + +* Duplicate plan name +* Invalid plan type +* Invalid plan limits +* Invalid billing cycle +* Invalid connection-based device charge +* Permission denied +* Backend unavailable + +--- + +## 4.3.2 Assign Plan to Customer/Sub-Operator + +* Workflow ID: WF-BILLING-002 +* Actor: Operator Admin / Billing Admin +* Scope: Direct child customer/sub-operator + +Entry Point: + +```text +Customers -> Customer Detail -> Billing -> Assign Plan +``` + +Flow: + +```text +Open Customer Billing View +-> Select eligible active plan +-> Review assignment, plan type, pricing, and device limits +-> Confirm +-> Backend validates direct child scope +-> Plan assigned +``` + +Outcome: + +* Billing plan is assigned to an eligible direct child customer/sub-operator. + +RBAC Constraints: + +* Operator Admin can assign plans only to direct child customers/sub-operators within its allowed subtree. +* Actor cannot assign plans to sibling, parent, or unrelated customers. +* Actor cannot assign inactive or unauthorized plans. + +Failure/Edge Cases: + +* Selected customer is outside scope +* Selected plan is inactive +* Customer is not eligible for the plan +* Fixed-device plan limit is not valid for the customer +* Permission denied + +--- + +## 4.3.3 Select Billing Plan as Customer/Sub-Operator + +* Workflow ID: WF-BILLING-003 +* Actor: Customer Admin +* Scope: Own customer/sub-operator subtree + +Entry Point: + +```text +Sidebar -> Billing -> Available Plans +``` + +Flow: + +```text +Open Available Plans +-> Review plans offered by parent operator +-> Review plan type, pricing, billing cycle, and device limits +-> Select eligible active plan +-> Confirm Subscription +-> Backend validates eligibility +-> Backend enforces single active subscription +-> Subscription updated +``` + +Outcome: + +* Customer/sub-operator has one active billing subscription. +* Selected subscription follows either connection-based billing or fixed-device billing. + +RBAC Constraints: + +* Customer Admin can only view plans offered by its parent operator. +* Customer Admin can select only one eligible active plan. +* Customer Admin cannot modify parent-created billing plans. +* Customer Admin cannot view sibling billing plans or subscriptions. + +Failure/Edge Cases: + +* Plan inactive +* Plan not eligible +* Existing subscription conflict +* Fixed-device limit exceeded +* Permission denied +* Billing API unavailable + +--- + +## 4.3.4 View Subscription + +* Workflow ID: WF-BILLING-004 +* Actor: Customer Admin / Billing Admin / Operator Admin +* Scope: Own subtree or permitted child scope + +Entry Point: + +```text +Sidebar -> Billing -> Subscription +``` + +Flow: + +```text +Open Subscription View +-> View current plan +-> View plan type +-> View subscription state +-> View limits and billing status +-> For connection-based plan, view connected-device billing details +-> For fixed-device plan, view fixed device allowance and billing cycle +``` + +Outcome: + +* User can view permitted subscription details. +* User can understand whether the current subscription is connection-based or fixed-device based. + +RBAC Constraints: + +* Customer Admin can view only own subscription. +* Operator Admin can view permitted direct child customer/sub-operator subscriptions. +* Sibling subscriptions must not be visible. + +Failure/Edge Cases: + +* No active subscription +* Subscription suspended or expired +* Fixed-device limit exceeded +* Permission denied +* Backend unavailable + +--- + +# 4.4 Hierarchy Navigation Workflows + +All workflows that operate on scoped resources must resolve the current hierarchy scope from the Top Context Bar before execution. + +```text +Sidebar = WHAT the user wants to do +Top Context Bar = WHERE the user is working + +## 4.4.1 Switch Hierarchy Scope + +* Workflow ID: WF-HIERARCHY-001 +* Actor: All users +* Scope: Allowed subtree + +Entry Point: + +```text +Top Context Bar +``` + +Flow: + +```text +Open Top Context Bar +-> Select Customer/Site/Node/Venue +-> Load selected subtree +-> Update route context +-> Update breadcrumbs +-> Update workspace +``` + +Outcome: + +* Selected hierarchy scope changes. +* Operational modules render data for the selected scope. + +RBAC Constraints: + +* Context selector must only show allowed subtree items. +* Unauthorized hierarchy nodes must never appear. + +Failure/Edge Cases: + +* Selected node unavailable +* Permission changed during session +* Backend unavailable + +--- + +## 4.4.2 Browse Hierarchy Tree + +* Workflow ID: WF-HIERARCHY-002 +* Actor: All users +* Scope: Allowed subtree + +Entry Point: + +```text +Sidebar -> Hierarchy +``` + +Flow: + +```text +Open Hierarchy Module +-> Expand hierarchy nodes +-> Select node +-> Open hierarchy workspace +-> Show contextual workspace tabs +``` + +Outcome: + +* User lands in the selected hierarchy node workspace. + +RBAC Constraints: + +* User can only browse nodes inside the allowed subtree. + +Failure/Edge Cases: + +* Empty hierarchy +* Node load failure +* Permission denied + +--- + +## 4.4.3 Use Hierarchy Workspace Tabs + +* Workflow ID: WF-HIERARCHY-003 +* Actor: All users +* Scope: Selected hierarchy node + +Entry Point: + +```text +Hierarchy -> Select Node -> Workspace Tabs +``` + +Flow: + +```text +Select hierarchy node +-> Open node workspace +-> Choose tab +-> Overview | Topology | Devices | Clients | Maps | Configurations | Metrics | AI Insights +``` + +Outcome: + +* User performs contextual operations inside the selected hierarchy node. + +RBAC Constraints: + +* Workspace tabs must adapt to role, node type, enabled capabilities, and permissions. + +Failure/Edge Cases: + +* Tab hidden because of RBAC +* Tab disabled because data is unavailable +* Selected node has no compatible workspace data + +--- +## 4.4.4 Create Node + +* Workflow ID: WF-HIERARCHY-004 +* Actor: Operator Admin / Customer Admin +* Scope: Selected hierarchy subtree + +Entry Point: + +```text +Hierarchy -> Create Node +``` + +Flow: +Resolve current hierarchy scope +-> Select parent node +-> Select node type +-> Site | Building | Tower | Floor | Venue +-> Enter node details +-> Save +-> Backend validates scope +-> Node created + +Outcome: + +* New node is added to hierarchy. + +RBAC Constraints: + +* User can create nodes only inside permitted subtree. + +Failure/Edge Cases: + +* Invalid parent node +* Duplicate node name +* Permission denied +* Backend unavailable + +--- + +```md +## 4.4.5 Edit Node + +* Workflow ID: WF-HIERARCHY-005 + +Flow: + +```text +Select Node +-> Edit Details +-> Save + +--- + +```md +## 4.4.6 Move Node + +* Workflow ID: WF-HIERARCHY-006 + +Flow: + +```text +Select Node +-> Select New Parent +-> Validate Scope +-> Save + +--- + +```md +## 4.4.7 Delete Node + +* Workflow ID: WF-HIERARCHY-007 + +Flow: + +```text +Select Node +-> Review Impact +-> Confirm Delete +-> Backend Validation +-> Delete + +--- + +# 4.5 Device Management Workflows + +## 4.5.1 View Devices + +* Workflow ID: WF-DEVICE-001 +* Actor: Customer Admin / NOC/Support / Installer +* Scope: Selected subtree or selected hierarchy node + +Entry Point: + +```text +Sidebar -> Devices +``` + +Flow: + +```text +Open Devices Module +-> Resolve current hierarchy scope +-> Load devices inside scope +-> Filter devices +-> Select device +-> Open device detail +``` + +Outcome: + +* User can view infrastructure devices within permitted scope. + +RBAC Constraints: + +* Devices outside the user's subtree must not be visible. + +Failure/Edge Cases: + +* Empty device inventory +* Device offline +* Permission denied +* Backend unavailable + +--- + +## 4.5.2 Device Diagnostics + +* Workflow ID: WF-DEVICE-002 +* Actor: NOC/Support / Customer Admin +* Scope: Selected device inside allowed subtree + +Entry Point: + +```text +Devices -> Device Detail -> Diagnostics +``` + +Flow: + +```text +Select Device +-> Open Diagnostics +-> View status, logs, metrics, uplink state +-> Optional AI Assistant diagnosis +-> Review suggested fix +``` + +Outcome: + +* User understands device health and possible remediation steps. + +RBAC Constraints: + +* Diagnostic depth depends on role. +* Read-only users may only view summary diagnostics. + +Failure/Edge Cases: + +* Device offline +* Logs unavailable +* Metrics unavailable +* Permission denied + +--- + +## 4.5.3 Device Action + +* Workflow ID: WF-DEVICE-003 +* Actor: Customer Admin / NOC/Support / Installer +* Scope: Selected device inside allowed subtree + +Entry Point: + +```text +Devices -> Device Detail -> Actions +``` + +Flow: + +```text +Select Device +-> Choose action +-> Reboot | Upgrade | Blink | Factory Reset +-> Confirm action +-> Backend validates permission +-> Action submitted +-> Track result +``` + +Outcome: + +* Device action is executed or queued. + +RBAC Constraints: + +* Dangerous actions must be hidden or disabled unless permitted. +* Backend must enforce authorization even if UI shows action. + +Failure/Edge Cases: + +* Action not supported for device type +* Device offline +* Permission denied +* Action failed + +--- + +## 4.5.4 Add Device + +* Workflow ID: WF-DEVICE-004 + +Flow: + +```text +Devices +-> Add Device +-> Resolve current hierarchy scope +-> Enter serial number +-> Select device type +-> Save + +--- + +## 4.5.5 Assign Device + +* Workflow ID: WF-DEVICE-005 + +Flow: + +```text +Select Device +-> Assign Device +-> Select Node/Venue +-> Save Assignment + +--- + +## 4.5.6 Move Device + +* Workflow ID: WF-DEVICE-006 + +Flow: + +```text +Select Device +-> Move Device +-> Select New Node/Venue +-> Save + +--- + +# 4.6 Client Management Workflows + +## 4.6.1 View Active Clients + +* Workflow ID: WF-CLIENT-001 +* Actor: NOC/Support / Customer Admin +* Scope: Selected subtree or selected hierarchy node + +Entry Point: + +```text +Sidebar -> Clients -> Active Clients +``` + +Flow: + +```text +Open Active Clients +-> Filter by node/venue/AP/status +-> Select client +-> View client detail +``` + +Outcome: + +* User can monitor active clients inside permitted scope. + +RBAC Constraints: + +* Clients outside the selected/allowed subtree must not be visible. + +Failure/Edge Cases: + +* No active clients +* Client disconnected +* Permission denied +* Backend unavailable + +--- + +## 4.6.2 View Client Experience + +* Workflow ID: WF-CLIENT-002 +* Actor: NOC/Support / Customer Admin +* Scope: Selected client inside allowed subtree + +Entry Point: + +```text +Clients -> Client Detail -> Wireless Experience +``` + +Flow: + +```text +Select Client +-> Open Wireless Experience +-> View signal, roaming, AP association, session history +-> Optional AI Assistant analysis +``` + +Outcome: + +* User can troubleshoot client experience issues. + +RBAC Constraints: + +* Client identity/details may be limited by role. + +Failure/Edge Cases: + +* Historical data unavailable +* Client session ended +* Permission denied + +--- + +# 4.7 Configuration and Rollout Workflows + +## 4.7.1 Create Configuration + +* Workflow ID: WF-CONFIG-001 +* Actor: Customer Admin / Operator Admin +* Scope: Selected subtree + +Entry Point: + +```text +Sidebar -> Configurations -> Create +``` + +Flow: + +```text +Open Create Configuration +-> Resolve current hierarchy scope +-> Define settings +-> Validate configuration +-> Save +``` + +Outcome: + +* Configuration set is created. + +RBAC Constraints: + +* User can create configurations only inside permitted scope. + +Failure/Edge Cases: + +* Invalid configuration +* Duplicate configuration name +* Permission denied +* Backend unavailable + +--- +## 4.7.2 Edit Configuration + +* Workflow ID: WF-CONFIG-002 + +Flow: + +```text +Select Configuration +-> Edit Settings +-> Validate +-> Save +``` +--- +## 4.7.3 Assign Configuration + +* Workflow ID: WF-CONFIG-003 + +Flow: + +```text +Select Configuration +-> Select Target Nodes/Devices +-> Assign +``` +--- + +## 4.7.4 Preview Effective Configuration + +* Workflow ID: WF-CONFIG-004 + +Flow: + +```text +Select Node or Device +-> View Effective Configuration +-> Compare Overrides +-> Review Result +``` +--- +## 4.7.5 Rollout Configuration + +* Workflow ID: WF-ROLLOUT-005 +* Actor: Customer Admin / Operator Admin +* Scope: Selected nodes/devices inside allowed subtree + +Entry Point: + +```text +Configurations -> Select Config -> Rollout +``` + +Flow: + +```text +Select Configuration +-> Choose target nodes/devices +-> Select rollout type +-> Immediate | Scheduled | Staged +-> Review rollout plan +-> Execute +-> Track progress +``` + +Outcome: + +* Rollout is started and tracked. + +States: + +```text +pending -> successful / failed +``` + +RBAC Constraints: + +* Rollout targets must be inside allowed subtree. +* User must have rollout permission. + +Failure/Edge Cases: + +* Invalid rollout target +* Device incompatible +* Rollout failed +* Permission denied + +--- + +## 4.7.8 Analyze Failed Rollout + +* Workflow ID: WF-ROLLOUT-006 +* Actor: Customer Admin / NOC/Support +* Scope: Selected rollout inside allowed subtree + +Entry Point: + +```text +Rollouts -> Failed Rollout -> Analyze +``` + +Flow: + +```text +Open Failed Rollout +-> Review failed targets +-> View failure reasons +-> Optional AI Assistant explanation +-> Retry or rollback +``` + +Outcome: + +* User can understand and act on rollout failure. + +RBAC Constraints: + +* Retry and rollback actions require permission. + +Failure/Edge Cases: + +* Rollout logs unavailable +* Retry not supported +* Rollback not available +* Permission denied + +--- + +# 4.8 Maps and Topology Workflows + +## 4.8.1 Upload Map + +* Workflow ID: WF-MAP-001 +* Actor: Installer / Customer Admin +* Scope: Selected node/venue/floor inside allowed subtree + +Entry Point: + +```text +Sidebar -> Maps -> Upload Map +``` + +Flow: + +```text +Open Maps Module +-> Upload map asset +-> Select node/venue/floor association +-> Add metadata +-> Save +``` + +Outcome: + +* Map asset is uploaded and associated with a permitted hierarchy scope. + +RBAC Constraints: + +* User can only associate maps with nodes/venues/floors inside allowed subtree. + +Failure/Edge Cases: + +* Unsupported map format +* Upload failed +* Invalid association +* Permission denied + +--- + +## 4.8.2 Place Devices on Map + +* Workflow ID: WF-MAP-002 +* Actor: Installer / Customer Admin +* Scope: Selected venue/floor inside allowed subtree + +Entry Point: + +```text +Hierarchy -> Select Venue/Floor -> Maps Tab -> Open Map Editor +``` + +Flow: + +```text +Select Venue/Floor in Hierarchy +-> Open Maps Tab +-> Open Map Editor +-> Drag device onto map +-> Set position and rotation +-> Save position +``` + +Outcome: + +* Device placement coordinates are saved for map/topology visualization. + +RBAC Constraints: + +* User can place only permitted devices on maps inside allowed subtree. +* Device and map must belong to compatible scope. + +Failure/Edge Cases: + +* Device not assignable to map scope +* Map missing +* Invalid coordinates +* Permission denied + +--- + +## 4.8.3 View Topology + +* Workflow ID: WF-TOPOLOGY-001 +* Actor: All users +* Scope: Selected hierarchy node + +Entry Point: + +```text +Hierarchy -> Select Node -> Topology Tab +``` + +Flow: + +```text +Select hierarchy node +-> Open Topology Tab +-> View contextual topology +-> Toggle overlays +-> APs | Switches | Gateways | Clients | Health | Wireless Quality +``` + +Outcome: + +* User views contextual topology for the selected node. + +RBAC Constraints: + +* Topology overlays must only show resources inside permitted scope. +* Topology is not a standalone root sidebar module. + +Failure/Edge Cases: + +* No map available +* Topology data unavailable +* Partial data +* Permission denied + +--- + +## 4.8.4 View Device Connectivity Topology + +* Workflow ID: WF-TOPOLOGY-002 +* Actor: NOC/Support / Customer Admin +* Scope: Selected subtree or selected device group + +Entry Point: + +```text +Sidebar -> Devices -> Connectivity View +``` + +Flow: + +```text +Open Devices Module +-> Open Connectivity View +-> View gateways, switches, AP uplinks, mesh links, and port relationships +-> Select device or link +-> Inspect connectivity detail +``` + +Outcome: + +* User views engineering-focused device connectivity topology. + +RBAC Constraints: + +* Connectivity graph must only show authorized devices and links. + +Failure/Edge Cases: + +* Topology graph unavailable +* Link data unavailable +* Permission denied + +--- + +# 4.9 User Management Workflows + +## 4.9.1 Create User + +* Workflow ID: WF-USER-001 +* Actor: Operator Admin / Customer Admin +* Scope: Own subtree or permitted child subtree + +Entry Point: + +```text +Sidebar -> Users -> Create User +``` + +Flow: + +```text +Open Create User Form +-> Enter user details +-> Select role/profile +-> Select scope if applicable +-> Save +-> Backend creates user through OWSEC +-> Backend applies role/policy through OWPROV +``` + +Outcome: + +* User account is created and assigned to the correct scope and role/profile. + +RBAC Constraints: + +* Actor can create users only inside permitted scope. +* Actor cannot grant permissions higher than their own allowed authority. + +Failure/Edge Cases: + +* Duplicate email +* Invalid role assignment +* Scope not allowed +* OWSEC user creation failed +* OWPROV role/policy attachment failed + +--- + +## 4.9.2 Reset Password + +* Workflow ID: WF-USER-002 +* Actor: Operator Admin / Customer Admin +* Scope: User inside permitted subtree + +Entry Point: + +```text +Users -> User Detail -> Reset Password +``` + +Flow: + +```text +Open User Detail +-> Select Reset Password +-> Confirm +-> Backend triggers OWSEC password reset flow +-> Show success state +``` + +Outcome: + +* Password reset is triggered for the selected user. + +RBAC Constraints: + +* Actor can reset password only for users inside permitted scope. + +Failure/Edge Cases: + +* User outside scope +* OWSEC unavailable +* Permission denied + +--- + +## 4.9.3 Suspend User + +* Workflow ID: WF-USER-003 +* Actor: Operator Admin / Customer Admin +* Scope: User inside permitted subtree + +Entry Point: + +```text +Users -> User Detail -> Suspend User +``` + +Flow: + +```text +Open User Detail +-> Select Suspend User +-> Confirm +-> Backend updates user status +-> Active sessions revoked if required +``` + +Outcome: + +* User is suspended and access is blocked. + +RBAC Constraints: + +* Actor can suspend users only inside permitted scope. +* Actor cannot suspend users with higher authority unless explicitly allowed. + +Failure/Edge Cases: + +* User outside scope +* Permission denied +* Active session revocation failed + +--- + +# 4.10 AI Assistant Workflows + +## 4.10.1 Ask AI + +* Workflow ID: WF-AI-001 +* Actor: All users +* Scope: Current selected scope + +Entry Point: + +```text +Sidebar -> AI Agent -> Ask Anything +``` + +Flow: + +```text +Open AI Agent +-> Ask question +-> AI Assistant resolves current user scope and permissions +-> AI Assistant responds using authorized data only +``` + +Outcome: + +* User receives scope-aware operational guidance. + +RBAC Constraints: + +* AI Assistant must obey RBAC and subtree isolation. +* AI Assistant must not expose sibling, parent, or unauthorized data. + +Failure/Edge Cases: + +* Question requires unauthorized data +* AI context unavailable +* Backend unavailable + +--- + +## 4.10.2 AI Diagnostics + +* Workflow ID: WF-AI-002 +* Actor: NOC/Support / Customer Admin +* Scope: Selected device or hierarchy node + +Entry Point: + +```text +Device Detail -> Ask AI +``` + +Flow: + +```text +Select Device +-> Ask AI Assistant to diagnose issue +-> AI Assistant analyzes permitted device data +-> Suggests possible cause and next steps +-> User reviews recommendation +``` + +Outcome: + +* User receives a diagnostic explanation and recommended next actions. + +RBAC Constraints: + +* AI Assistant can only analyze data the user is authorized to view. +* AI-generated actions require user approval before execution. + +Failure/Edge Cases: + +* Insufficient data +* Unauthorized data requested +* Recommendation cannot be executed + +--- + +## 4.10.3 AI Recommendations + +* Workflow ID: WF-AI-003 +* Actor: Customer Admin / Operator Admin / NOC/Support +* Scope: Current selected scope + +Entry Point: + +```text +Dashboard -> AI Recommendations +``` + +Flow: + +```text +Open AI Recommendations +-> Review suggested actions +-> Open recommendation detail +-> Review plan +-> Approve, edit, or dismiss +``` + +Outcome: + +* User can act on AI-supported recommendations after review. + +RBAC Constraints: + +* AI recommendations must be scoped to authorized resources. +* Execution of AI-suggested actions must use normal RBAC validation. + +Failure/Edge Cases: + +* Recommendation stale +* Required permission missing +* Suggested action conflicts with policy + +--- + +# 4.11 Administration Workflows + +## 4.11.1 Manage Roles and Policies + +* Workflow ID: WF-ADMIN-001 +* Actor: Root Operator / Operator Admin +* Scope: Platform scope or operator subtree + +Entry Point: + +```text +Sidebar -> Administration -> Roles/Policies +``` + +Flow: + +```text +Open Administration +-> Open Roles/Policies +-> View existing role/policy profiles +-> Edit allowed settings +-> Save changes +-> Backend validates authority +``` + +Outcome: + +* Role/policy settings are viewed or updated according to authority. + +RBAC Constraints: + +* Root Operator can manage platform-level administration. +* Operator Admin can manage only permitted operator-scope settings. +* Users cannot grant permissions outside their authority. + +Failure/Edge Cases: + +* Permission denied +* Invalid policy configuration +* Change would break required admin access +* Backend unavailable + +--- + +## 4.11.2 View Audit Logs + +* Workflow ID: WF-ADMIN-002 +* Actor: Root Operator / Operator Admin / NOC/Support +* Scope: Platform or permitted subtree + +Entry Point: + +```text +Sidebar -> Administration -> Audit Logs +``` + +Flow: + +```text +Open Audit Logs +-> Filter by user, action, resource, scope, or date +-> View event detail +``` + +Outcome: + +* User can review permitted audit activity. + +RBAC Constraints: + +* Audit logs must be scoped. +* Users must not see audit events for unauthorized subtrees. + +Failure/Edge Cases: + +* No logs available +* Permission denied +* Backend unavailable + +--- + +# 5. Cross-Cutting Behaviors + +## 5.1 RBAC Enforcement + +All workflows must follow RBAC behavior: + +* Actions are hidden if not permitted. +* Read-only users see read-only states where appropriate. +* Backend APIs enforce authorization. +* Unauthorized resources are never shown in responses. +* UI permissions are convenience only; backend remains the enforcement layer. + +--- + +## 5.2 Scope Isolation + +All workflows must follow subtree isolation: + +* Users only see resources in their allowed subtree. +* Sibling subtree data is never visible. +* Parent resources are hidden unless explicitly allowed. +* Dropdowns, searches, filters, topology views, billing views, and AI responses must be scope-filtered. + +--- + +## 5.3 Backend Outage Behavior + +Authentication should continue when the MDU backend is unavailable. + +UI behavior: + +* UI shell loads. +* Navigation can render from existing session context. +* Business data screens show service unavailable state. +* Retry option is available. +* No stale or unauthorized cached business data is shown. + +Display state: + +```text +Service Unavailable +Retry +``` + +--- + +## 5.4 System States + +All workflows must define and handle: + +```text +Loading +Empty +Error +No Permission +Backend Down +Partial Data +Success +``` + +These states are especially important for: + +* topology +* billing +* metrics +* rollouts +* AI workflows +* maps +* hierarchy workspaces + +--- + +## 5.5 Confirmation and Safety States + +Destructive or sensitive actions must include explicit confirmation. + +Examples: + +* Delete customer/sub-operator +* Suspend user +* Factory reset device +* Rollback rollout +* Change billing plan +* Modify role/policy + +--- + +# 6. Workflow Coverage Summary + +This document covers: + +* Authentication +* Customer/sub-operator lifecycle +* Billing and subscription management +* Hierarchy navigation and workspace behavior +* Device management and diagnostics +* Client management and wireless experience +* Configuration and rollout workflows +* Maps and contextual topology +* User management +* AI Assistant workflows +* Administration workflows +* RBAC behavior +* Scope isolation +* Backend outage behavior +* System states + +--- + +# 7. Next Design Documents + +This workflows document should feed into: + +```text +screen-inventory.md +screen-definitions.md +layout-system.md +wireframe-plan.md +figma-navigation-model.md +``` + +The next step is to map each workflow ID to the screens required to support it. +