# Dashboard, device search and fleet organization

## Portal navigation

The home route `/` is now a dashboard. It shows customer fleet totals, Online/Offline/Never-connected counts, shortcuts and recent commands. Cards link to the corresponding filtered terminal grid. Counts cover the full customer fleet rather than only the first page.

| Page | Purpose |
| --- | --- |
| Dashboard — `/` | Fleet summary and recent commands |
| Devices — `/Fleet/Devices` | Terminal grid, combined search/filtering and pagination |
| Groups and tags — `/Fleet/Groups` | Create, rename, move and remove groups/subgroups and tags |
| Device organization — `/Fleet/Organize/{id}` | Assign one group and up to 50 distinct tags to a terminal |
| Application library — `/Apps` | Package builds and immediate/scheduled delivery |
| Administration — `/Home/Administration` | Super-admin customer creation, terminal enrollment and model catalog access |

Device detail links back to Devices and shows its group path, tags and connection status. Its organization link opens the assignment form. The Administration page and mutations retain SuperAdmin authorization; customer administrators manage their own fleet organization without gaining device registration or customer creation permissions.

## Search behavior

Search runs in SQL through gRPC/Dapper. Filters combine with AND: literal serial substring, group/subgroup, tag, catalog model and status. Selecting a parent group includes every descendant. Ungrouped is an explicit filter. The model includes brand/model/OS. Results sort by serial and device identity, in pages of 24; links retain filters. Changing customer through the workspace selector resets filters.

Group and tag identifiers never grant access. Every query and mutation validates customer membership. Cross-customer group parents, devices and tags are rejected. The database also enforces customer-scoped foreign keys for assignments.

## Organization rules

- Groups have one optional parent and a maximum hierarchy depth of 32. Cyclic moves and self-parenting are rejected. Moving a group preserves terminal assignments.
- Sibling names are unique within a customer; tag names are unique within a customer. Names are trimmed and limited to 100 characters.
- A device belongs to zero or one group and may have several tags. Clearing assignments returns it to Ungrouped.
- Only empty groups without children and unused tags can be deleted. Assignment removal is an explicit separate action.
- Hierarchy and assignment mutations serialize per customer and write audit events.
- Group counts show directly assigned devices; filtering a group includes descendants.

Migration `004_FleetOrganization.sql` adds FleetGroup, FleetTag, DeviceGroup, DeviceTag and the connection lease column.

## Connection status

The MQTT broker renews a server-side connection lease every 15 seconds for authenticated connected devices. A lease lasts 45 seconds; normal disconnects expire it promptly. Broker failure or loss of the data-service connection therefore ages out rather than leaving a device permanently Online. This is a bounded freshness indication, not an instantaneous network guarantee.

Online requires an unexpired lease. Offline means a previous connection/report exists without a valid lease. Never connected means neither has been recorded. Disabled takes precedence. Last telemetry receipt remains a separate timestamp and does not determine Online status. Existing devices with older telemetry start as Offline until a broker renewal arrives.

## Verification

The .NET 8 solution builds with zero warnings/errors, and all 98 integration checks pass. Desktop and 390-pixel phone checks confirmed localized controls and no page-level horizontal overflow on Dashboard, Devices, Groups/Tags and Administration. The connected NEW9810 matched a combined serial/model/Online search in BANPAIS.

Automated checks cover hierarchy cycles, duplicate names, cross-customer boundaries, assignments, protected deletion, subgroup moves, combined filters, literal serial searches, status transitions, full-fleet counts and pagination. MVC checks verify that dashboard, Devices and Administration are separate, and that group creation submits through protected MVC forms to gRPC. Desktop and phone layouts retain English/Spanish localization.

Group/tag-based application deployment targeting remains a later extension; this implementation provides organization and device filtering. Existing application deployments continue to freeze explicitly selected device IDs.