Development Guidelines

Code Organization

Plings-Lovable-Frontend/
├── src/
│   ├── components/
│   │   ├── auth/
│   │   └── ui/
│   ├── contexts/
│   ├── hooks/
│   ├── integrations/
│   │   └── supabase/
│   ├── lib/
│   ├── pages/
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── public/
│   └── static/
│       ├── icons/
│       └── logos/
├── docs/               # Project documentation (this folder)
├── brand/              # Brand assets and design system docs
├── shared/             # Shared configuration or helper scripts
└── … (config files, test setup, etc.)

Component Development

Component Guidelines

  • Keep components small and focused (under 150 lines)
  • Use TypeScript for all components
  • Implement proper error boundaries
  • Follow React hooks best practices

GraphQL Integration

import { useQuery, useMutation, gql } from '@apollo/client';
const GET_OBJECTS = gql`query GetObjects($filter:ObjectFilter){objects(filter:$filter){id name description}}`;
export const ObjectList=({filter}:{filter?:ObjectFilter})=>{
  const {data,loading,error}=useQuery(GET_OBJECTS,{variables:{filter},fetchPolicy:'cache-first'});
  if(loading)return <Spinner/>;
  if(error)return <ErrorMessage error={error}/>;
  return <div>{data?.objects.map(o=>(<ObjectCard key={o.id} object={o}/>))}</div>;
};

Testing Strategy

Unit Tests

  • Vitest + React Testing Library, 80% coverage

    Integration Tests

  • Apollo MockedProvider, focus on workflows

    E2E Tests

  • Playwright for auth, drag/drop, real-time

    Performance Tests

  • Lighthouse, React Profiler

Performance Guidelines

  • Use React.memo, list virtualization, optimized queries
  • Code-splitting & lazy loading

Code Quality

  • ESLint, Prettier, Husky hooks, TS strict mode

Backend Integration Issues

Critical Import Errors Prevention

The most common cause of “Load failed” errors is backend import failures:

# ❌ WRONG - Causes entire backend to crash with 500 errors
from .db_postgres import create_async_engine  # Doesn't exist
from .db_neo4j import AsyncGraphDatabase       # Doesn't exist

# ✅ CORRECT - Use actual package imports
from sqlalchemy.ext.asyncio import create_async_engine
from neo4j import AsyncGraphDatabase

Frontend Symptoms: CORS preflight failures, “Load failed” in Apollo Client, no GraphQL access

GraphQL Debugging & Testing

The GraphQLDebugger component (/src/components/debug/GraphQLDebugger.tsx) provides comprehensive testing capabilities for backend connection issues:

Basic Tests

  • myObjects Query: Tests basic GraphQL connectivity and object retrieval
  • Simple Object Query: Tests lightweight object details (getObjectDetailsSimple)
  • Complex Object Query: Tests full spatial relationships (getObjectDetailsComplete)

Sync Pattern Stress Tests

These tests specifically validate the backend Neo4j sync pattern fixes:

// Concurrent requests test (5 simultaneous)
🔥 Test Concurrent Requests (5x)

// Rapid sequential test (3 rapid requests)  
⚡ Test Rapid Sequential (3x)

What to Look For:

  • ✅ No “Load failed” errors
  • ✅ No “Task got Future attached to a different loop” messages
  • ✅ Consistent response times under load
  • ✅ All requests complete successfully

Recent Fixes Applied

  • Bug Fix: Simple query now correctly accesses data.getObjectDetailsSimple.name
  • Backend Sync Pattern: All Neo4j operations converted to asyncio.to_thread() pattern
  • Event Loop Resolution: Resolved serverless environment async conflicts

Deployment & Environment

  • Strict builds, size analysis, CI security scans
  • Separate .env files, feature flags, monitoring hooks