Navigator JSON Documentation

Overview

Navigator is a JSON-based linguistic syntax designed for implementing role-based navigation systems in web interfaces. It provides a structured approach to define user permissions, navigation flows, and interface elements through interconnected JSON objects.

The system enables developers to create complex navigation hierarchies where different user roles have access to specific navigation flows, each composed of sequential steps that guide users through interface elements between navigation points.

Navigator.json is primarily used in the Tribe Framework, which has Junction as the primary admin dashboard and CMS. So, by default, do not cater to admin roles. Create flows and navs for admin roles only if specified in the brief.

Core Concepts

Role-Based Access: User roles determine which navigation flows are accessible, providing granular permission control.

Navigation Flows: Defined pathways that connect navigation elements through a series of steps, with clear starting and ending points.

Modular Architecture: Interconnected components (roles, flows, steps, navs, nav_items) that reference each other through slug identifiers.

Interface Abstraction: Steps represent any interface element (routes, buttons, forms, modals, etc.) that users interact with.

JSON Schema

Roles

Defines user roles and their permitted navigation flows.

{
  "slug": "string",
  "title": "string",
  "description": "string",
  "flows": ["string"]
}

Properties:

• slug (string, required): Unique identifier for the role
• title (string, required): Human-readable role name
• description (string, required): Role short description or purpose
• flows (array of strings, required): Array of flow slugs this role can access

Flows

Defines navigation pathways between interface elements.

{
  "slug": "string",
  "title": "string",
  "description": "string",
  "steps": ["string"],
  "starting_nav_item": "string",
  "ending_nav_item": "string"
}

Properties:

• slug (string, required): Unique identifier for the flow
• title (string, required): Human-readable flow name
• description (string, required): Flow short description or purpose
• steps (array of strings, required): Ordered array of step slugs in this flow
• starting_nav_item (string, required): Slug of the nav item where flow begins
• ending_nav_item (string, required): Slug of the nav item where flow ends

Steps

Defines individual interface elements within navigation flows.

{
  "slug": "string",
  "title": "string",
  "description": "string",
  "flow": "string"
}

Properties:

• slug (string, required): Unique identifier for the step
• title (string, required): Human-readable step name
• description (string, required): Step short description and interaction details
• flow (string, required): Slug of the flow this step belongs to

Navs

Defines navigation containers that hold navigation items.

{
  "slug": "string",
  "title": "string",
  "description": "string",
  "nav_items": ["string"]
}

Properties:

• slug (string, required): Unique identifier for the navigation
• title (string, required): Human-readable navigation name
• description (string, required): Navigation short description or purpose
• nav_items (array of strings, required): Ordered array of nav item slugs contained in this navigation

Nav Items

Defines individual navigation elements within navigation containers.

{
  "slug": "string",
  "title": "string",
  "description": "string",
  "navs": ["string"]
}

Properties:

• slug (string, required): Unique identifier for the nav item
• title (string, required): Human-readable nav item name
• description (string, required): Nav item short description and functionality
• navs (array of strings, required): Array of nav slugs this item can appear in

Complete Example

{
  "roles": [
    {
      "slug": "admin",
      "title": "Administrator",
      "description": "Full system access with user management capabilities. To be created only if specified that admin roles must be served.",
      "flows": ["user-creation-flow", "dashboard-overview-flow"]
    },
    {
      "slug": "user",
      "title": "Standard User",
      "description": "Basic access to core application features",
      "flows": ["dashboard-overview-flow"]
    }
  ],
  "flows": [
    {
      "slug": "user-creation-flow",
      "title": "User Creation Process",
      "description": "Complete workflow for creating new user accounts",
      "steps": ["open-user-form", "fill-user-details", "submit-user-form"],
      "starting_nav_item": "users-menu",
      "ending_nav_item": "users-list"
    },
    {
      "slug": "dashboard-overview-flow",
      "title": "Dashboard Navigation",
      "description": "Basic navigation through main dashboard sections",
      "steps": ["view-statistics", "check-notifications"],
      "starting_nav_item": "dashboard-link",
      "ending_nav_item": "profile-menu"
    }
  ],
  "steps": [
    {
      "slug": "open-user-form",
      "title": "Open User Creation Form",
      "description": "Click the 'Add User' button to open the user creation modal",
      "flow": "user-creation-flow"
    },
    {
      "slug": "fill-user-details",
      "title": "Fill User Details",
      "description": "Complete required fields: name, email, role assignment",
      "flow": "user-creation-flow"
    },
    {
      "slug": "submit-user-form",
      "title": "Submit User Form",
      "description": "Click submit button to create the new user account",
      "flow": "user-creation-flow"
    },
    {
      "slug": "view-statistics",
      "title": "View Dashboard Statistics",
      "description": "Review key metrics and performance indicators on dashboard",
      "flow": "dashboard-overview-flow"
    },
    {
      "slug": "check-notifications",
      "title": "Check Notifications",
      "description": "Review recent notifications and system alerts",
      "flow": "dashboard-overview-flow"
    }
  ],
  "navs": [
    {
      "slug": "admin-sidebar",
      "title": "Administrator Sidebar",
      "description": "Left navigation panel with administrative functions. To be created only if specified that admin roles must be served.",
      "nav_items": ["users-menu", "users-list", "settings-menu"]
    },
    {
      "slug": "main-header",
      "title": "Main Header Navigation",
      "description": "Top navigation bar with primary application links",
      "nav_items": ["dashboard-link", "profile-menu"]
    },
    {
      "slug": "main-sidebar",
      "title": "Main Sidebar Navigation",
      "description": "Left navigation panel with core application sections",
      "nav_items": ["profile-menu", "dashboard-link"]
    }
  ],
  "nav_items": [
    {
      "slug": "users-menu",
      "title": "Users Menu",
      "description": "Navigation item for user management section. To be created only if specified that admin roles must be served.",
      "navs": ["admin-sidebar"]
    },
    {
      "slug": "users-list",
      "title": "Users List",
      "description": "Navigation item displaying all system users. To be created only if specified that admin roles must be served.",
      "navs": ["admin-sidebar"]
    },
    {
      "slug": "settings-menu",
      "title": "Settings Menu",
      "description": "Navigation item for system configuration. To be created only if specified that admin roles must be served.",
      "navs": ["admin-sidebar"]
    },
    {
      "slug": "dashboard-link",
      "title": "Dashboard Link",
      "description": "Navigation item linking to main dashboard view",
      "navs": ["main-header", "main-sidebar"]
    },
    {
      "slug": "profile-menu",
      "title": "Profile Menu",
      "description": "Navigation item for user profile and account settings",
      "navs": ["main-header", "main-sidebar"]
    }
  ]
}

Implementation Guidelines

Slug Naming: Use kebab-case for consistency and URL compatibility.

Referential Integrity: Ensure all slug references exist in their respective collections.

Flow Logic: Steps should be ordered logically within flows to represent actual user interaction sequences.

Role Permissions: Carefully design role-flow relationships to maintain proper access control.

Navigation Hierarchy: Structure navs and nav_items to reflect your application's interface organization.