Dashboard Overview

The Plings Dashboard is the primary interface for users to manage and interact with their objects within their organization. It provides a comprehensive view of object inventory, quick actions, and activity monitoring.

Dashboard Purpose

The dashboard serves as the central hub for object management, providing:

  • Object Discovery: View and explore all objects within the user’s organization
  • Quick Actions: Rapid access to common operations (add, search, scan)
  • Activity Monitoring: Track recent changes and interactions
  • Spatial Organization: Visual representation of object relationships and containment

Current Dashboard Components

1. Header Section

  • Logo: Plings branding with fallback text
  • User Context: Welcome message showing authenticated user email
  • User Profile: Profile dropdown with authentication controls

2. Page Title & Description

  • Main Title: “Dashboard”
  • Subtitle: “Manage your objects and collections”
  • Provides clear context for the user’s current location

3. Quick Actions Grid

A responsive grid (1-4 columns based on screen size) providing instant access to key functions:

Available Actions:

  • Search Objects: Find and explore objects within the organization
  • Add Object: Register new physical objects to the system
  • Collections: Manage object collections and groupings
  • Analytics: View usage statistics and insights

Interaction Pattern:

  • Hover effects for visual feedback
  • Click handlers for navigation (currently logging to console)
  • Consistent card-based design with icons and descriptions

4. Spatial Dashboard (Main Content)

The primary object visualization component showing:

Object Display Features:

  • Grid Layout: Responsive grid adapting to screen size (1-3 columns)
  • Object Cards: Rich cards showing object details
  • Image Handling: Optimized image transformations (400×300, contain mode)
  • Object Metadata: Name, description, location, last seen date
  • Status Indicators: Visual status badges with color coding
  • Loading States: Skeleton placeholders during data fetching
  • Error Handling: User-friendly error messages with context

Data Integration:

  • GraphQL Integration: Uses useMyObjects hook for real-time data
  • Organization Filtering: Shows only objects from user’s organization
  • Optimistic Updates: Immediate UI feedback with server reconciliation

5. Recent Activity Feed

Currently shows placeholder content with plans for:

  • Object interaction history
  • Movement tracking
  • Status change notifications
  • User action audit trail

Object Details Modal - Overview Tab Specifications

Overview Tab Purpose

The Overview tab provides the most essential information at a glance, serving as the primary summary view that gives users immediate context about an object. It should contain the most important information users need to understand and work with an object.

Current Implementation Status

1. Object Main Image

  • Status: ❌ MISSING - Needs to be implemented
  • Purpose: Large main image of the object at top of overview
  • Fallback: Placeholder if no image available
  • Interaction: Click to open full image viewer modal
  • Layout: Prominent position at top of overview

2. Basic Object Information ✅ IMPLEMENTED

  • Name: Editable object name with inline edit functionality
  • Description: Brief description with inline edit capability
  • Type: Object class/category display
  • Edit Pattern: Click edit icon → inline input → save/cancel buttons

3. Essential Spatial Context ✅ IMPLEMENTED

  • Spatial Hierarchy Breadcrumb: Clickable navigation showing “Home → Building → Floor 2 → Kitchen”
    • Each container in the breadcrumb should be clickable to navigate directly to that container
    • Compact, single-line display for space efficiency
    • Uses existing SpatialBreadcrumb component
    • Navigation Status: ❌ Handlers currently log to console - needs real navigation
  • Current Placement: Simple text showing where the object currently is
  • Normal Placement: Simple text showing where the object normally belongs

4. Related Objects (Functional Relationships) ✅ IMPLEMENTED

  • Visual Display: Shows related objects in icon format with small text labels
  • Relationship Types: Display objects connected via functional predicates:
    • Manual (“MANUAL_FOR” relationship)
    • Receipt (“RECEIPT_FOR” relationship)
    • Works with (“WORKS_WITH” relationship)
    • Powers/Powered by (“POWERS”/”POWERED_BY” relationship)
    • Other functional relationships from predicate catalogue
  • Data Source: Uses functionalRelationships array from GraphQL query
  • Layout: Grid view of related object cards with icons and names
  • Interaction: ❌ Click handlers currently log to console - needs real navigation
  • Empty State: Shows “No related objects” when array is empty

5. Sub-Objects Display ✅ IMPLEMENTED

  • Container Contents: If this object contains other objects, shows them visually
  • Format: Icon format with small text showing the name of each contained object
  • Data Source: Uses spatialChildren data from the GraphQL query
  • Interaction: ❌ Click handlers currently log to console - needs real navigation
  • Layout: Grid of small object cards with thumbnail and name
  • Empty State: Hide section if no sub-objects exist

6. Current Status Display ✅ IMPLEMENTED

  • Status Badges: Show current object statuses with color coding
  • Data Source: Uses statuses array with status definitions for proper colors
  • Categories: Display statuses from different categories (operational, commerce, problem, etc.)
  • Visual Priority: Highlight important statuses (broken, lost, for sale) with distinct colors
  • Layout: Horizontal badge layout with proper spacing

7. Quick Actions Area 🚧 PARTIALLY IMPLEMENTED

  • Purpose: Provide immediate access to common object operations
  • Current Implementation Status: BUTTONS EXIST BUT DISABLED
Currently Implemented Quick Actions (All Disabled):
  • Set for Sale (ShoppingCart icon) - Commerce status action
  • Set for Rent (Car icon) - Commerce status action
  • Mark as Lost (AlertTriangle icon) - Problem status action
  • Mark as Broken (AlertTriangle icon) - Problem status action
  • Move Object (MapPin icon) - Spatial action
  • Add Relationship (Link2 icon) - Relationship action
Missing Quick Actions (Need Implementation):
  • Mark as Found - Remove lost status (context-dependent)
  • Set Normal Location - Define where object normally belongs
  • Add to Collection - Group with other objects
  • Create New Collection - Start a new grouping
Implementation Requirements:
  • Enable Existing Buttons: Connect to backend status management system
  • Contextual Display: Show/hide actions based on current object state
  • Success/Error Handling: Toast notifications for action results
  • Status Integration: Use useUpdateObjectStatuses hook for status changes
  • Layout: Button grid design with consistent iconography
  • Current State: Placeholder message “Quick actions will be implemented as the status management system is integrated”

8. Essential Metadata ✅ IMPLEMENTED

  • Last Seen: Timestamp of last confirmed location/interaction
  • Owner Organization: Which organization owns the object
  • Created By: User who registered the object
  • Format: Simple key-value pairs in a metadata card

Missing Functionality Summary

High Priority (Missing Core Features):

  1. Object Main Image Display - Primary visual missing from overview
  2. Navigation Handlers - Breadcrumb, related objects, sub-objects need real navigation
  3. Quick Actions Functionality - Enable existing disabled buttons

Medium Priority (Enhanced Actions):

  1. Additional Quick Actions - Mark as Found, Set Normal Location, Collection actions
  2. Contextual Action Display - Smart showing/hiding based on object state

Design Principles for Overview Tab

Information Hierarchy

  1. Primary: Main image, name, current location breadcrumb
  2. Secondary: Related objects, sub-objects, current status
  3. Tertiary: Quick actions area, metadata

Interaction Philosophy

  • Everything should be clickable: Breadcrumb containers, related objects, sub-objects
  • Inline editing: Name and description editable directly in overview
  • Navigation ready: Quick actions area reserved for common operations

Space Management

  • Concise Display: Overview should NOT duplicate detailed information from other tabs
  • Smart Grouping: Related information grouped visually in cards
  • Progressive Disclosure: Show summary in overview, link to detailed views in other tabs
  • Responsive: All sections adapt to different screen sizes

Technical Implementation Requirements

Data Sources

  • Main Query: getObjectDetailsComplete provides all necessary data
  • Spatial Hierarchy: Use spatialHierarchy for breadcrumb navigation with onNavigate handlers
  • Related Objects: Use functionalRelationships array from object data
  • Sub-Objects: Use spatialChildren array from object data
  • Status Information: Use statuses array with proper status definitions for styling

Component Integration

  • SpatialBreadcrumb: Reuse existing component with navigation capability
  • Image Display: Integrate with existing image viewer modal
  • Status Badges: Use existing Badge component with proper status colors
  • Edit Functions: Integrate with existing useUpdateObjectBasicInfo hook

Future Integration Points

  • Status Actions: Will integrate with status management system when implemented
  • Navigation: Breadcrumb and related object clicks will open appropriate modals/views
  • Real-time Updates: Changes reflected immediately via GraphQL subscriptions
  • Quick Actions: Area reserved for rapid object operations (set for sale, rent, lost, etc.)

Dashboard State Management

Authentication

  • Session Validation: Automatic session checking with redirect on invalid sessions
  • Loading States: Proper handling of authentication loading states
  • User Context: Integration with AuthContext for user state

Data Flow

  • Primary Data: Organization objects via GraphQL
  • Real-time Updates: Subscription-based updates (planned)
  • Error Recovery: Retry logic for backend connectivity issues
  • Performance: Image optimization and lazy loading

Responsive Design Strategy

Breakpoints

  • Mobile (< 768px): Single column layout, simplified actions
  • Tablet (768px - 1024px): Two-column grid, medium density
  • Desktop (> 1024px): Three-column grid, full feature set

Mobile Optimizations

  • Touch-friendly action buttons (44px minimum)
  • Simplified object cards with essential information
  • Progressive disclosure of complex features
  • Optimized image loading for mobile bandwidth

Performance Considerations

Image Optimization

  • Transformation Pipeline: Supabase Storage transformations
  • Responsive Sizing: Appropriate dimensions for context
  • Lazy Loading: Images load as they enter viewport
  • Error Fallbacks: Graceful degradation for failed images

Data Loading

  • Cache Strategy: Apollo cache-first with network fallback
  • Loading States: Skeleton UI during initial load
  • Error Boundaries: Graceful error handling with retry options
  • Pagination: Ready for large object collections (future)

Future Enhancements

Short Term (Next Sprint)

  • Real Navigation: Replace console.log with actual routing
  • Activity Feed: Real data integration for recent activities
  • Search Integration: Global search functionality
  • Analytics Dashboard: Basic usage statistics

Medium Term

  • Drag & Drop: Interactive spatial manipulation
  • Bulk Operations: Multi-select and batch actions
  • Advanced Filtering: Search and filter by multiple criteria
  • Notifications: Real-time alerts for object changes
  • Quick Actions Implementation: Implement the reserved quick actions area with status management

Long Term

  • 3D Visualization: Optional 3D spatial view
  • AR Integration: Mobile augmented reality features
  • Collaborative Features: Multi-user object management
  • Advanced Analytics: Comprehensive usage insights

Organization-Based Access Model

Key Principles

  • Objects belong to organizations, not individual users
  • Users access objects through organization membership
  • All dashboard data is filtered by user’s organization(s)
  • Audit trail tracks individual user actions for accountability

Permission Implications

  • Dashboard shows objects from user’s organization(s) only
  • Actions are organization-scoped (create, edit, move)
  • User permissions are role-based within organizations
  • Cross-organization operations require special permissions

Integration with Spatial Dashboard

The dashboard incorporates the Spatial Dashboard as its primary content area, providing:

  • Visual representation of object containment relationships
  • Interactive object manipulation (future)
  • Real-time updates via GraphQL subscriptions
  • Optimized rendering for large object collections

For detailed spatial functionality specifications, see:

Error Handling & User Experience

Backend Connectivity

  • Asyncio Error Detection: Specific handling for backend async issues
  • Retry Logic: Exponential backoff for temporary failures
  • User Communication: Clear, non-technical error messages
  • Graceful Degradation: Functional UI even with partial data failures

User Feedback

  • Loading Indicators: Visual feedback during operations
  • Success Confirmations: Clear feedback for completed actions
  • Error Recovery: Actionable suggestions for error resolution
  • Progressive Enhancement: Core functionality works without advanced features

Technical Dependencies

Required Hooks

  • useSessionValidation: Authentication and session management
  • useMyObjects: Organization object data fetching
  • useTransformedImage: Performance-optimized image handling
  • useAuth: Authentication context and operations

UI Components

  • shadcn/ui: Card, Button, Badge components
  • Lucide Icons: Consistent iconography
  • Tailwind CSS: Responsive styling and design system
  • Loading States: Skeleton and spinner components

GraphQL Operations

  • GET_MY_OBJECTS: Primary object data query
  • Future: Subscriptions for real-time updates
  • Future: Mutations for object manipulation

This dashboard serves as the foundation for all user interactions within the Plings system, providing a scalable and intuitive interface for object management.