Plings – Lovable Knowledge File

Purpose: Provide Lovable.dev with a single source of truth about the Plings frontend so that generated React components align with domain rules, backend expectations, and design conventions. Purpose: This file is the central, authoritative knowledge base that Lovable.dev reads every time it generates or updates our React code.
• Single Source of Truth – Captures the domain rules, backend contracts, design-system tokens, and architectural constraints that guide code generation.
• Change Control – Any change that can influence the production frontend (GraphQL schema, database columns, design-system updates, feature flags, etc.) must be documented here before or alongside the code change; otherwise Lovable will work off stale assumptions.
• Linking Policy – Feel free to link out for detail, but only to Markdown files under ./docs/** because that folder is the only documentation bundle surfaced to the Lovable generator. Use relative links (e.g. [Image Handling](../docs/use-cases/upload-image.md)).

🚨 CRITICAL DEVELOPMENT RESOURCE

When in doubt about the GraphQL API, use: https://plings-backend.vercel.app/graphql/

This live GraphiQL interface is the authoritative source for:

  • Current schema structure and field names
  • Available queries, mutations, and subscriptions
  • Field types, arguments, and return values
  • Real-time API testing without authentication

Always verify API contracts here before writing frontend code.

📋 DOCUMENTATION-FIRST DEVELOPMENT WORKFLOW

CRITICAL PRINCIPLE: Documentation is the single source of truth.

🚨 MANDATORY: API Requirements Documentation

BEFORE implementing ANY new GraphQL operations (queries, mutations, subscriptions), you MUST update docs/api/api-requirements.md.

Zero Tolerance Policy: No Code Without API Documentation

❌ FORBIDDEN: Writing frontend code that assumes backend operations exist without documenting them first.

✅ REQUIRED: Every new GraphQL operation must be documented in api-requirements.md with:

  • Proposed schema
  • Frontend use case
  • Backend complexity estimate
  • Implementation priority

Before Implementing Any New Function or Change:

  1. 📖 Consult Current Documentation First
    • Check this knowledge file and the docs/ directory
    • CRITICAL: Check docs/api/api-endpoints.md for existing operations
    • Verify if the requested functionality is already documented
    • Review existing patterns and architectural decisions
  2. 🔍 For ANY New GraphQL Operations:
    • STOP - Do not implement frontend code first
    • Document in docs/api/api-requirements.md under “🔴 Critical Operations”
    • Include complete schema proposal with fields, arguments, and return types
    • Explain frontend impact and user story
    • Wait for backend acknowledgment before proceeding with frontend implementation
  3. ✅ If Request Uses Existing Documented Operations:
    • Verify operations exist in docs/api/api-endpoints.md with status ✅ Implemented
    • Proceed with implementation according to documented patterns
    • Inform the user: “This request uses existing operations documented in [specific reference].”
  4. ⚠️ If Request Conflicts or Requires New Operations:
    • STOP IMPLEMENTATION - Do not start coding frontend
    • Update docs/api/api-requirements.md FIRST with new operation requirements
    • Engage in discussion with the user to clarify:
      • How the new functionality fits with existing architecture
      • Backend complexity and implementation timeline
      • Any implications for the overall system design
    • Wait for Documentation Review and Backend Acknowledgment before starting implementation

🔄 API Documentation Update Process:

For ANY new GraphQL operations, follow this MANDATORY process:

  1. Document the Requirement in docs/api/api-requirements.md: ```markdown

    X. operationName query/mutation

    • Status: ❌ Not Started
    • Frontend Blocker: [What frontend feature is blocked]
    • User Story: “[User story requiring this operation]”
    • Backend Complexity: [Low/Medium/High]
    • Schema Draft: 
      [Complete GraphQL schema]
  2. Reference in Frontend Code: 
    // TODO: Requires backend implementation
// Documented in: docs/api/api-requirements.md section X
const PLACEHOLDER_QUERY = gql`
  # This query is not yet implemented
  # See api-requirements.md for specification
`;
  3. Track Implementation Status:
    • Monitor api-requirements.md for backend team updates
    • Move completed operations to api-endpoints.md when implemented
    • Update frontend code to use real operations when available

📋 Example: Organization Management (Your Recent Frontend Changes)

❌ What Happened: Frontend implemented organization features without documenting requirements:

  • Added GET_MY_ORGANIZATIONS query to queries.ts
  • Added CREATE_ORGANIZATION mutation to mutations.ts
  • Built complete UI in OrganizationsSection.tsx
  • Backend has no idea these operations are needed!

✅ What Should Have Happened:

  1. Document in api-requirements.md first: 
    #### 5. `getMyOrganizations` query
- **Status**: ❌ Not Started
- **Frontend Blocker**: Dashboard organization listing
- **User Story**: "As a user, I want to see all organizations I belong to"
- **Schema Draft**:
```graphql
query getMyOrganizations {
  myOrganizations {
 id
 name
 description
 type
 created_at
 memberCount
 role
  }
}

6. createOrganization mutation

  • Status: ❌ Not Started
  • Frontend Blocker: Organization creation dialog
  • User Story: “As a user, I want to create new organizations”
  • Schema Draft: 
    mutation createOrganization($input: CreateOrganizationInput!) {
createOrganization(input: $input) {
  id
  name
  description
  type
}
}
  1. Build frontend with placeholders referencing the documentation
  2. Wait for backend implementation before removing placeholders

Documentation Update Requirements:

When adding new functionality, update IN THIS ORDER:

  1. FIRST: docs/api/api-requirements.md for any new GraphQL operations
  2. SECOND: This knowledge file for high-level architectural changes
  3. THIRD: Relevant files in docs/frontend/ for UI patterns
  4. FOURTH: Database schema docs for data model changes
  5. LAST: Use case documentation for new user workflows

🔗 Critical API Documentation Files:

  • 📋 docs/api/api-requirements.md - MUST update for any new operations
  • 📄 docs/api/api-endpoints.md - Current implementation status
  • 🔍 GraphiQL Interface - Live schema truth

🚨 Enforcement:

Code reviews must check:

  1. ✅ All new GraphQL operations documented in api-requirements.md
  2. ✅ Frontend doesn’t assume backend operations exist without documentation
  3. ✅ Proper placeholders used until backend implementation complete

Remember: Code without API documentation breaks the frontend-backend coordination. API operations without documentation leave the backend team blind to requirements.

Product Vision (PRD Summary)

The world needs a global, decentralised solution for object identification. Plings answers this need by establishing a Global Decentralised Support System for Physical Objects that delivers:

  • Identification – tamper-proof identifiers (QR/NFC) that bind the digital twin to the real-world object.
  • Information – rich, open graph of metadata, relationships and lifecycle history accessible to stakeholders.
  • Value – services (resale, rental, repair, recycling) built atop the object graph, incentivising circular-economy behaviours.

Plings provides universal IDs and digital twins for physical objects—a generic solution usable from personal households to large-scale industry and enterprise. By acting as a border-less, universal support system, Plings enables every participant in the network to:

  • Utilise products longer and preserve value
  • Save time by accessing trustworthy lifecycle information
  • Facilitate repairs, refurbishment, resale or rental
  • Build new services atop the same IDs and open framework

In doing so, Plings offers an essential tool for reducing over-consumption, maximising resource reuse, and accelerating the world’s shift toward a sustainable, global circular economy.

Main Goals

  1. Conserve Earth’s Resources – Extend product lifespans and boost material recycling.
  2. Global Addressing for Physical Objects – Provide a generic, secure ID scheme usable anywhere.
  3. Enrich Objects with Trusted Information – Attach verifiable data that adds value and transparency.
  4. Host a Universal Service Platform – Become the leading hub where services related to physical objects reside (repair, resale, rental, compliance, etc.).
  5. Streamline Object-Related Processes – Cover the entire lifecycle from creation through ownership transfers to end-of-life recycling.

To achieve these goals, Plings exposes open GraphQL APIs, client SDKs, and webhooks so that any service provider can build interoperable extensions on the shared object graph—adding trust, lowering costs, and amplifying reuse/recycling at global scale.

1. Project Overview

Plings is a platform for tracking, organising, and managing physical objects across organisations. A unified GraphQL API backed by Neo4j (graph) and Supabase (Postgres + Storage) exposes object data, relationships, audit logs, and user management. The web front-end—built with React 18 and managed through Lovable.dev—offers:

  • Spatial dashboard for drag-and-drop containment & positional relationships
  • Object detail views (lifecycle, ownership, functional & spatial relations)
  • Class browser & creation wizards
  • Organisation admin panel and Super-admin console
  • Real-time updates via GraphQL Subscriptions

Goals:

  1. Deliver a highly interactive, mobile-first web experience.
  2. Keep API, database, and UI in strict sync via typed GraphQL schema.
  3. Provide a foundation for future React Native apps with shared types.

2. User Personas

Persona Description Key Needs
Org User Staff member of an organisation managing its inventory • Quick object lookup • Mobile drag-drop moves • Bulk actions
Org Admin Manages users & billing for a single organisation • Invite users • Set roles & quotas • View audit logs
Super Admin Plings operator with global oversight • Tenant, user & billing control • System KPI dashboards • Ops tooling
Public Viewer External user scanning a QR/NFC identifier • Read-only object detail • Purchase / rent CTA if applicable

3. Feature Specifications

3.1 Top-Level Epics & Stories (sample)

Epic User Story Acceptance Criteria
Spatial Explorer As an Org User, I reorganise objects by dragging them into containers. • Drag source & drop target highlight • Optimistic UI move within 150 ms • Server confirms via objectMoved subscription
Object Creation As an Org User, I create a new object with photos in one step. • Form validates required fields • Multipart GraphQL mutation uploads images • New object appears in grid instantly
Audit Log Viewer As a Super Admin, I filter logs by org & date. • Table paginates 100 rows • Filters combine (AND) • CSV export respects filters

Full feature matrix lives in frontend_views_and_permissions.md, spatial_dashboard_requirements.md, and related docs.

4. Design Assets

Asset Location
Figma File <add share link here>
Colour Palette See brand/design-system.md (CSS custom-property table)
Typography Inter / SF Pro via @fontsource – scale set in Tailwind config
Icon Set Tabler Icons (SVG) loaded as React components

Components generated by Lovable must use Tailwind utility classes and adhere to spacing/colour tokens defined in the design system.

5. API Documentation (GraphQL)

5.1 Production Endpoints

  • Backend API: https://plings-backend.vercel.app/graphql (WS on same path)
  • Auth: JWT from Supabase; send via Authorization: Bearer <token> (HTTP) or connectionParams (WS)

5.2 🔍 GraphiQL Interface - SOURCE OF TRUTH

URL: https://plings-backend.vercel.app/graphql/

CRITICAL: This is the live, authoritative source for the GraphQL schema. When in doubt about API structure, field names, or available operations, always check this URL first.

How to Use:

  1. Open in browser: Navigate to https://plings-backend.vercel.app/graphql/
  2. Explore schema: Click “Docs” panel on the right to browse all types and operations
  3. Test queries: Write and execute GraphQL operations in the left panel
  4. Auto-complete: Press Ctrl+Space for field suggestions
  5. Copy queries: Use tested queries directly in your React components

When to Use:

  • ✅ Before writing GraphQL queries - Verify field names and structure
  • ✅ When API documentation seems outdated - GraphiQL shows current reality
  • ✅ For debugging - Test queries without authentication to isolate issues
  • ✅ During development - Explore available fields and nested relationships

5.3 📚 API Documentation System

Plings uses a frontend-driven API development approach with two key documentation files:

For Implementation Status & Available Operations

📄 Use: docs/api/api-endpoints.md

This file contains:

  • ✅ Complete catalogue of all GraphQL operations (queries, mutations, subscriptions)
  • ✅ Implementation status (✅ Implemented, ❌ Not implemented, 🚧 External)
  • ✅ Frontend usage patterns and integration examples
  • ✅ Priority classification (🔴 Critical, 🟡 Medium, 🟢 Low)

Check this file when:

  • Building a component that needs backend data
  • Verifying what operations are available
  • Understanding frontend impact of missing operations
  • Looking for GraphQL query examples

For Development Coordination & New Requirements

📋 Use: docs/api/api-requirements.md

This file contains:

  • 🔴 Current sprint focus and critical blocking operations
  • 📋 Detailed requirements with proposed GraphQL schemas
  • 📈 Implementation timeline and development phases
  • 🤝 Frontend-backend coordination process

Update this file when:

  • You discover a missing backend operation that blocks frontend development
  • Backend implementation status changes (❌ → ✅)
  • New critical operations are needed for upcoming features
  • Coordinating implementation priorities with backend team

5.4 🚨 Frontend Development Action Protocols

When a New Backend Operation is Needed

  1. Check Current Status: Look in docs/api/api-endpoints.md to confirm the operation doesn’t exist
  2. Document the Need: Add to docs/api/api-requirements.md under “🔴 Critical Operations” with:
    • User story and frontend impact
    • Proposed GraphQL schema
    • Required fields and expected response
    • Frontend usage context
  3. Continue Development: Build UI components with mock data or loading states while waiting for backend
  4. Track Progress: Monitor api-requirements.md for backend implementation updates

Example:

#### 5. `deleteObject` mutation
- **Status**: ❌ Not Started
- **Frontend Blocker**: Cannot remove objects from inventory
- **User Story**: "As a user, I want to delete objects I no longer need"
- **Required Fields**: `objectId: ID!`, `confirmationCode?: String`
- **Expected Response**: `{ success: boolean, message: string }`
- **Frontend Usage**: Delete confirmation modals, bulk delete operations

When Backend Operation Becomes Available

  1. Update Status: Change status in docs/api/api-endpoints.md from ❌ to ✅ Implemented
  2. Move from Requirements: Remove detailed spec from api-requirements.md (it’s now in the main catalogue)
  3. Integrate & Test: Replace mock data with real GraphQL queries
  4. Verify Implementation: Test the operation matches the documented schema

When Backend Code Has Problems

  1. Document the Issue: Add to docs/api/api-endpoints.md in the “Important Notes” section: 
    ## Known Issues
   
### `moveObject` mutation (❌ Backend Error)
- **Problem**: Returns 500 error with message "Task got Future attached to a different loop"
- **Cause**: Async Neo4j operations in serverless environment  
- **Workaround**: Use PostgreSQL-only moves, avoid spatial relationship updates
- **Status**: Backend team investigating
- **Tracked in**: GitHub Issue #123
  2. Implement Workarounds: Build graceful fallbacks in frontend: 
    // Example: Graceful fallback for broken moveObject
const handleMoveObject = async (objectId: string, containerId: string) => {
  try {
    await moveObject({ variables: { objectId, containerId } });
  } catch (error) {
    // Fallback: Update UI optimistically, sync later
    updateObjectLocationLocally(objectId, containerId);
    showToast("Move queued - will sync when backend is fixed");
  }
};
  3. Communicate Impact: Update api-requirements.md to reflect how the issue affects development priorities

When GraphiQL Schema Differs from Documentation

  1. Stop Development: Don’t write code based on possibly incorrect documentation
  2. Document Discrepancy: Note the difference in docs/api/api-endpoints.md: 
    ## Schema Discrepancies
   
- **Field**: `ObjectInstance.spatialParent`
- **Documentation Says**: `spatialParent: ObjectInstance`
- **GraphiQL Shows**: `spatialParent: SpatialParent` 
- **Action Needed**: Clarify correct schema with backend team
  3. Ask for Clarification: Request user guidance on whether to update documentation or report a backend issue
  4. Wait for Resolution: Don’t proceed with implementation until schema is confirmed

5.5 Core Schema Overview

  • Core Types: ObjectInstance, ObjectClass, SpatialRelationship, Ownership, StatusEntry, Organisation, User
  • Key Operations
    • query myObjects, query object(id), query getObjectDetailsComplete(id)
    • mutation moveObject(objectId, newContainerId) (❌ Not implemented - see api-requirements.md)
    • mutation uploadObjectImages(objectId, images), mutation updateObjectStatuses(...)
    • subscription objectUpdated(id) (❌ Not implemented - see api-requirements.md)
  • Error Format: Standard GraphQL errors with code & message fields.
  • Documentation: Complete operation details in docs/api/api-endpoints.md

6. 📁 Frontend Documentation Access

6.1 Complete Frontend Documentation Location

All frontend-specific documentation is available in this repository under docs/:

🔗 API & Backend Integration

  • docs/api/api-requirements.md - API coordination hub and development tracking (SHARED FILE)
  • docs/api/api-endpoints.md - Complete GraphQL operations catalog (SHARED FILE)
  • docs/api/authentication.md - Auth patterns and Supabase integration
  • docs/api/data-models.md - GraphQL types and structures

🏗️ Frontend Architecture & Patterns

  • docs/frontend/development-guidelines.md - Frontend coding standards and patterns
  • docs/frontend/graphql-integration.md - Apollo Client setup and query patterns
  • docs/frontend/state-management.md - Local state and cache management
  • docs/frontend/real-time-updates.md - GraphQL subscriptions and live data
  • docs/frontend/spatial-dashboard-requirements.md - Spatial UI specifications

🎨 Design & Components

  • docs/brand/design-system.md - Complete design system tokens and guidelines
  • docs/brand/implementation-guide.md - Component implementation patterns
  • docs/frontend/dashboard-overview.md - UI layout and navigation patterns

⚙️ Core Business Logic & Models

  • docs/core-systems/ - Business domain models and validation rules
  • docs/use-cases/ - Feature specifications and user workflows
  • docs/admin/ - Administrative features and permission models

🛠️ Development & Deployment

  • docs/development/ - Development environment and team coordination
  • docs/deployment/ - Build and deployment procedures
  • docs/troubleshooting/ - Common issues and debugging guides

6.2 Documentation Update Policy

CRITICAL: This repository serves as the unified documentation hub for both frontend and backend teams:

  • Frontend developers: Edit documentation files directly in this repository
  • Backend developers: Access synchronized copy via their repository
  • Shared API files: Both teams collaborate on API coordination documents
  • Real-time sync: Backend documentation updates automatically

Always check documentation in docs/ before implementing new features.

7. 🏗️ Current Frontend Architecture

7.1 Technology Stack

Core Framework & Build:

  • React 18 with TypeScript
  • Vite for development and build
  • Tailwind CSS for styling
  • Vercel for deployment

GraphQL & State Management:

  • Apollo Client for GraphQL operations and caching
  • GraphQL Code Generator for type-safe queries
  • Supabase Auth for authentication state

UI Components & Design:

  • shadcn/ui component library
  • Tabler Icons for iconography
  • Lucide Icons as fallback
  • Custom design system defined in docs/brand/design-system.md

7.2 Project Structure

src/
├── components/           # Reusable UI components
│   ├── ui/              # shadcn/ui base components
│   └── [feature]/       # Feature-specific components
├── contexts/            # React context providers
│   ├── AuthContext.tsx  # Supabase authentication
│   └── OrganizationContext.tsx # Organization state
├── graphql/            # GraphQL operations
│   ├── queries.ts      # Query definitions
│   ├── mutations.ts    # Mutation definitions
│   └── types.ts        # Generated TypeScript types
├── hooks/              # Custom React hooks
├── integrations/       # External service integrations
├── lib/                # Utility functions and configurations
│   ├── apollo.ts       # Apollo Client setup
│   ├── supabase.ts     # Supabase configuration
│   └── utils.ts        # General utilities
├── pages/              # Page components and routing
└── types/              # TypeScript type definitions

7.3 Key Architectural Patterns

GraphQL Integration Pattern

// Always use typed queries from graphql/queries.ts
import { GET_MY_OBJECTS } from '@/graphql/queries';
import { useQuery } from '@apollo/client';

const { data, loading, error } = useQuery(GET_MY_OBJECTS, {
  variables: { organizationId },
  fetchPolicy: 'cache-first'
});

Authentication Pattern

// Use AuthContext for authentication state
import { useAuth } from '@/contexts/AuthContext';

const { user, session, signOut } = useAuth();

Error Handling Pattern

// Consistent error handling with user feedback
const [error, setError] = useState<string | null>(null);

try {
  await mutation({ variables: input });
  toast.success('Operation completed successfully');
} catch (err) {
  const message = err instanceof Error ? err.message : 'An error occurred';
  setError(message);
  toast.error(message);
}

7.4 Current Implementation Status

✅ Fully Implemented Features

  • Authentication: Complete Supabase integration with JWT tokens
  • Organization Management: List, create, and manage organizations
  • Object Listing: Display user’s objects with images and metadata
  • Image Upload: Direct Supabase Storage integration with drag-and-drop
  • Responsive Design: Mobile-first responsive components
  • Real-time GraphQL: Apollo Client with production backend integration

🚧 In Development Features

  • Spatial Dashboard: Drag-and-drop object organization (UI built, backend integration in progress)
  • Object Creation: Complete creation flow (form built, backend API fixes in progress)
  • Object Detail Views: Comprehensive object information display

❌ Pending Implementation

  • Search Functionality: Object search and filtering
  • Bulk Operations: Batch object management
  • Advanced Spatial Features: Complex container relationships
  • Real-time Updates: Live data synchronization via subscriptions

8. 🔧 Development Guidelines for Lovable.dev

8.1 Code Generation Standards

Component Structure:

// Always use this component template structure
import React from 'react';
import { useQuery, useMutation } from '@apollo/client';
import { toast } from 'sonner';

interface ComponentProps {
  // Define clear TypeScript interfaces
}

const ComponentName: React.FC<ComponentProps> = ({ props }) => {
  // 1. Hooks first (useQuery, useMutation, useState, etc.)
  // 2. Event handlers
  // 3. Render logic with early returns for loading/error states
  
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div className="space-y-4">
      {/* Use Tailwind utility classes */}
    </div>
  );
};

export default ComponentName;

GraphQL Operations:

// Define all GraphQL operations in dedicated files
// Always include proper TypeScript types

// graphql/queries.ts
export const GET_OBJECTS = gql`
  query GetObjects($organizationId: ID!) {
    myObjects {
      id
      name
      description
      mainImageUrl
      imageUrls
      owner_organization_id
    }
  }
`;

// graphql/mutations.ts  
export const CREATE_OBJECT = gql`
  mutation CreateObject($input: CreateObjectInput!) {
    createObject(input: $input) {
      object {
        id
        name
        description
      }
      warnings
      generatedName
    }
  }
`;

8.2 Design System Integration

Use Design Tokens:

// Always use Tailwind classes that align with design system
// Primary colors: blue-600, blue-500, blue-400
// Secondary: gray-900, gray-600, gray-400
// Success: green-600, Warning: yellow-500, Error: red-600

<button className="bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded-md">
  Primary Action
</button>

<div className="bg-gray-50 border border-gray-200 rounded-lg p-6">
  Content Container
</div>

Typography Scale:

// Use consistent typography classes
<h1 className="text-3xl font-bold text-gray-900">Page Title</h1>
<h2 className="text-xl font-semibold text-gray-800">Section Header</h2>
<p className="text-base text-gray-600">Body text</p>
<span className="text-sm text-gray-500">Caption text</span>

8.3 Integration with Backend

API Communication:

  • Production Backend: https://plings-backend.vercel.app/graphql/
  • Always verify operations in GraphiQL before implementing
  • Use proper error handling for network and GraphQL errors
  • Implement loading states for all async operations

Authentication Flow:

// Include JWT token in Apollo Client headers
const token = session?.access_token;
if (token) {
  headers = {
    authorization: `Bearer ${token}`,
  };
}

8.4 Performance Guidelines

Optimization Patterns:

  • Use React.memo for components that receive stable props
  • Implement proper Apollo Client caching with cache policies
  • Lazy load images using proper loading states
  • Debounce search inputs to reduce API calls
  • Use React.Suspense for code splitting where appropriate

Bundle Size Management:

  • Import only needed functions from utility libraries
  • Use dynamic imports for large dependencies
  • Optimize images through Vercel’s image optimization
  • Monitor bundle size and avoid large third-party libraries

9. 🚨 Critical Current Issues & Workarounds

9.1 Known Backend Issues

createObject Mutation Query Mismatch ⚠️

Problem: Frontend expects createObject to return ObjectInstance directly, but backend returns CreateObjectResult wrapper.

Current Status: Backend working correctly, frontend needs query update.

Required Fix:

// ❌ Current frontend query (WRONG)
mutation CreateObject($input: CreateObjectInput!) {
  createObject(input: $input) {
    id                    # Error: Field doesn't exist
    name                  # Error: Field doesn't exist
  }
}

// ✅ Correct frontend query (REQUIRED)
mutation CreateObject($input: CreateObjectInput!) {
  createObject(input: $input) {
    object {              # Wrapper field
      id                  # Now correct
      name                # Now correct
      description
      owner_organization_id
      spatialParent {
        id
        name
      }
    }
    warnings              # Additional metadata
    generatedName         # Auto-generated name
    spatialRelationshipCreated
    imagesUploaded
  }
}

Action Required: Update CreateObjectModal.tsx to use correct query structure.

9.2 Development Workflow Issues

API Documentation Synchronization

Problem: Frontend development sometimes proceeds without documenting required backend operations.

Solution: Always update docs/api/api-requirements.md BEFORE implementing frontend features that need new backend operations.

Real-time Update Missing

Problem: UI doesn’t update automatically when objects change.

Temporary Workaround: Use Apollo Client’s refetchQueries after mutations:

const [createObject] = useMutation(CREATE_OBJECT, {
  refetchQueries: [{ query: GET_MY_OBJECTS }],
});

Future Solution: Implement GraphQL subscriptions for real-time updates.

10. 🎯 Immediate Development Priorities

10.1 Critical Fixes Needed

  1. Fix createObject Query Structure - Update frontend query to match backend response format
  2. Implement Search Functionality - Add object search and filtering capabilities
  3. Complete Spatial Dashboard - Finish drag-and-drop container relationships
  4. Add Bulk Operations - Enable batch object management

10.2 Next Sprint Features

  1. Real-time Updates - Implement GraphQL subscriptions
  2. Advanced Object Details - Complete object information views
  3. Tag Management - QR/NFC tag scanning and assignment
  4. Performance Optimization - Image loading and caching improvements

10.3 Long-term Roadmap

  1. Mobile App - React Native implementation sharing types
  2. Offline Support - Progressive Web App capabilities
  3. Advanced Analytics - Usage tracking and insights
  4. Third-party Integrations - External service connections

11. 📱 Mobile & Responsive Design

11.1 Responsive Breakpoints

// Tailwind breakpoints used throughout the app
// sm: 640px and up
// md: 768px and up  
// lg: 1024px and up
// xl: 1280px and up

// Mobile-first responsive design
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
  {/* Responsive grid layout */}
</div>

11.2 Touch & Interaction Patterns

  • Minimum touch targets: 44px x 44px for mobile
  • Swipe gestures: Implemented for mobile navigation
  • Drag and drop: Touch-friendly spatial organization
  • Pull-to-refresh: For data updates on mobile

This knowledge file provides Lovable.dev with comprehensive context for generating React components that integrate properly with the Plings backend, follow established patterns, and align with the project’s architecture and design system.