Related Entity Navigation

Standard for cross-linking related entities so users can move between panels, rows, and relationships without friction.

Overview

The platform should make it easy to move between related entities.

If the UI shows a meaningful relationship such as:

location -> franchisee organization
deal -> lead or franchisee organization
task -> linked entity
entity -> parent or child organization

then the user should usually be able to navigate directly to that related entity from the current surface

Core Rule

When a related entity is shown in a list, table, panel, card, or detail view, prefer making that relationship directly navigable instead of rendering it as dead text.

In the brand dashboard, the default target is usually the related entity's Panel if one exists.

If no panel exists, navigate to the entity's canonical page or workspace.

Why This Matters

This pattern:

reduces hunting and repeated search
helps users understand relationships between entities
supports investigation workflows across panels
keeps related context close together

It is closely related to the Stay In Context Workflows pattern, but the focus here is navigation between existing entities rather than creating or editing them inline.

Choose The Right Surface

Use a compact badge-like affordance when the related entity is secondary metadata on a dense surface such as a panel header or tight list row.

Typical examples:

owning organization on a location panel
territory badge on a location panel
lead or franchisee badge in a deal header

Use a button or row-style reference when the related entity needs more context than a small badge can provide.

Typical examples:

avatar + name rows in tables
linked entity blocks in a task detail view
richer cards in relationship sections

Relationship Collection

Use a dedicated list or card pattern when the user is navigating among multiple related entities, especially hierarchical relationships.

This is the right fit for:

parent and child organizations
repeated linked stakeholders
relationship management sections

Prefer this order:

Open the related entity's Panel when the dashboard already has one.
Navigate to the entity's dedicated page when no panel exists.
Only omit navigation when the relationship is not actually inspectable or the user lacks access.

Do not force the user to manually search for the related entity if the UI already knows exactly which entity it is.

Interaction Conventions

Include an entity cue such as an Avatar, icon, or recognizable badge treatment.
Stop row propagation when the cross-link sits inside a clickable row or table.
Keep labels short and scannable.
If the reference is compact and secondary, a clickable Badge is acceptable.
If the reference is important enough to be a primary action, use a real button, row, or card surface instead of relying on a badge.
If navigation is unavailable, render the relationship as non-interactive and make that intentional.

Brand Dashboard Usage Patterns

Representative usages:

Pattern	Path	Notes
Panel header related badges	`fsai/apps/brand-dashboard/src/modules/locations/components/LocationPanel/LocationPanel.tsx`	Strong example: display ID, owning organization badge, and territory badge in header metadata, with related-entity navigation on the latter two.
Deal header cross-link	`fsai/apps/brand-dashboard/src/pages/Deals/Deals.components.tsx`	Uses a compact badge in a panel header to open either the franchisee organization or the lead panel.
Table linked entity cell	`fsai/apps/brand-dashboard/src/pages/Home/Tasks/TasksTab.tsx`	Good example of a row-safe clickable linked entity with avatar, display name, and `stopPropagation()`.
Detail-view linked entity block	`fsai/apps/brand-dashboard/src/modules/tasks/components/TaskPanel/TaskPanelDetails/TaskPanelDetails.tsx`	Uses a larger button-style entity reference because the relationship is important and deserves more context than a small badge.
Relationship card list	`fsai/apps/brand-dashboard/src/modules/franchisees/components/FranchiseeGroupPanel/FranchiseeGroupPanelRelationships.tsx`	Best current example of navigating among multiple related entities with dedicated relationship cards.

Relationship To Other Patterns

See Stay In Context Workflows for inline creation and local task completion without leaving the current workflow.
See Data Display for table, list, badge, and detail-view display conventions.
See Badge for compact metadata pills and secondary clickable badge usage.
See Panel for the standard brand-dashboard destination when the target entity has a panel.

Guidelines

Do make known related entities directly navigable from the surface where they are shown
Do prefer opening the related entity panel when one exists
Do use compact badges for secondary relationship metadata and richer buttons/cards for more important references
Do stop event propagation when a cross-link lives inside a clickable row
Don't render important entity relationships as dead text if the target is known and accessible
Don't force users to re-search for an entity the current UI already knows about