link,[object Object]
ACQM Docs

Appearance

Developer Guide ​

Quick Start for Developers ​

Repository Setup ​

bash
git clone <repository-url>
cd acqmarketplace
pnpm install
cp .env.example .env
pnpm dev

Essential File Locations ​

  • Routes: src/components/routing/AppRoutes.tsx - Complete route map
  • Auth: src/contexts/AuthContext.tsx - User authentication
  • API Client: src/integrations/supabase/client.ts - Database connection
  • Types: src/integrations/supabase/types.ts - Auto-generated from DB

Development Workflow ​

1. Adding a New Feature ​

bash
# 1. Create feature branch
git checkout -b feature/new-listing-filters

# 2. Add route in AppRoutes.tsx
# 3. Create page component in src/pages/
# 4. Add any required database changes via Supabase migrations
# 5. Create UI components in src/components/
# 6. Add TanStack Query hooks for data fetching

2. Database Changes ​

bash
# Link to Supabase project
pnpm supabase:link

# Create migration
supabase migration new add_listing_filters

# Apply locally
supabase db reset

# Deploy to staging/production via Supabase dashboard

3. Component Development ​

typescript
// Use shadcn/ui components
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"

// Follow semantic token pattern
<div className="bg-background text-foreground border border-border">

Code Conventions ​

File Naming ​

  • Components: PascalCase (e.g., UserProfile.tsx)
  • Hooks: camelCase with use prefix (e.g., useListings.ts)
  • Pages: PascalCase (e.g., ListingDetail.tsx)
  • Types: PascalCase (e.g., Listing.ts)

Import Organization ​

typescript
// 1. React imports
import { useState, useEffect } from 'react'

// 2. Third-party libraries
import { useQuery } from '@tanstack/react-query'

// 3. Internal components/hooks
import { Button } from '@/components/ui/button'
import { useAuth } from '@/contexts/AuthContext'

// 4. Types
import type { Listing } from '@/types/database'

State Management Patterns ​

typescript
// Server state: Use TanStack Query
const { data: listings, isLoading } = useQuery({
  queryKey: ['listings', filters],
  queryFn: () => fetchListings(filters)
})

// Form state: Use react-hook-form
const form = useForm({
  resolver: zodResolver(schema),
  defaultValues: { title: '', price: 0 }
})

// Global state: Use React Context
const { user } = useAuth()

Common Tasks ​

Adding a New Route ​

  1. Add to AppRoutes.tsx:
typescript
<Route 
  path="/new-feature" 
  element={
    <AppLayout>
      <ProtectedRoute>
        <NewFeaturePage />
      </ProtectedRoute>
    </AppLayout>
  } 
/>
  1. Create page component:
typescript
// src/pages/NewFeaturePage.tsx
export default function NewFeaturePage() {
  return (
    <div className="container mx-auto p-6">
      <h1>New Feature</h1>
    </div>
  )
}

Creating API Hooks ​

typescript
// src/hooks/useListings.ts
export function useListings(filters = {}) {
  return useQuery({
    queryKey: ['listings', filters],
    queryFn: async () => {
      const { data, error } = await supabase
        .from('listings')
        .select('*')
        .eq('status', 'active')
      
      if (error) throw error
      return data
    }
  })
}

Debugging ​

React DevTools ​

  • Install React DevTools browser extension
  • Use Profiler for performance analysis
  • Inspect TanStack Query cache

Console Debugging ​

typescript
// Use structured logging
console.log('🔍 User data:', { user, role, subscription })

// Debug queries
const query = useQuery({
  queryKey: ['debug-data'],
  queryFn: fetchData,
  onSuccess: (data) => console.log('✅ Query success:', data),
  onError: (error) => console.error('❌ Query error:', error)
})

Network Monitoring ​

  • Use browser DevTools Network tab
  • Monitor Supabase requests in Console
  • Check Edge Function logs in Supabase dashboard

Essential Documentation: