goodgo-platform/docs/audits/PROPERTY_DETAIL_INDEX.md

# Property Detail Page - Documentation Index

Created: 2026-04-11  
Project: GoodGo Platform (Vietnamese Real Estate)

---

## 📚 Documentation Files

### 1. **PROPERTY_DETAIL_PAGE_ANALYSIS.md** (17KB, 553 lines)
**Comprehensive Analysis** - Start here for complete understanding

Contains:
- ✅ Project overview (Next.js 15, Tailwind, Zustand)
- ✅ Full page structure & architecture
- ✅ Property images implementation
- ✅ Image-related components (gallery, upload)
- ✅ Project component structure & patterns
- ✅ Next.js Image usage patterns
- ✅ State management patterns (Zustand)
- ✅ Available third-party libraries
- ✅ Tailwind & design tokens
- ✅ API & data types (PropertyMedia, ListingDetail)
- ✅ Complete file structure
- ✅ Key insights & best practices
- ✅ Dependencies not present

**Use when:** You need a deep understanding of the architecture

---

### 2. **PROPERTY_DETAIL_QUICK_REFERENCE.md** (13KB, 583 lines)
**Code Snippets & Patterns** - Quick lookup guide

Contains:
- 🎯 Quick navigation (file paths, routes)
- 🖼️ Working with images (gallery, upload, data structure)
- 🎨 Styling patterns (aspect ratios, Tailwind classes)
- 🔄 State management patterns (Zustand, local state)
- 🧩 UI component patterns (Button, Badge, Card, Dialog)
- 📱 Responsive design patterns (breakpoints, grid)
- 🔗 Common imports (ready-to-copy imports)
- 📊 Data fetching examples
- 🌐 Internationalization
- 🔐 Security features
- 🧪 Testing considerations
- 🚀 Performance optimization tips
- 📋 Common tasks (add UI element, modify gallery)
- 🐛 Common issues & solutions

**Use when:** You need code snippets, patterns, or quick answers

---

### 3. **PROPERTY_DETAIL_COMPONENTS_MAP.md** (14KB, 601 lines)
**Component Hierarchy & Architecture** - Visual reference

Contains:
- 🎯 Page component hierarchy (visual tree)
- 🖼️ Image Gallery component details
- 📱 Image Upload component details
- 🧩 Related components (search results, property card)
- 🌐 Data flow & API mapping
- 🎨 Styling architecture
- 📊 State management patterns
- 🔗 Import map & file references
- 📈 Component complexity levels
- 🚀 Performance considerations
- 🔄 Navigation flows
- 📋 Component checklists
- 🛠️ Maintenance guide

**Use when:** You need to understand component relationships

---

## 🎯 Quick Start Guide

### For Understanding the Current Implementation:
1. Start with **PROPERTY_DETAIL_PAGE_ANALYSIS.md** sections:
   - Section 1: Property Detail Page Structure
   - Section 2: Property Images - Current Implementation
   - Section 3: Image-Related Components

### For Making Changes:
1. Check **PROPERTY_DETAIL_QUICK_REFERENCE.md**:
   - Find the relevant pattern or component
   - Copy the code snippet
   - Adapt to your needs

2. Reference **PROPERTY_DETAIL_COMPONENTS_MAP.md**:
   - Understand where component fits
   - Check data flow
   - Verify state management

### For Building New Image Features:
1. **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Section 5 (Next.js Image Usage)
2. **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Section "Working with Images"
3. **PROPERTY_DETAIL_COMPONENTS_MAP.md** - "Image Gallery Component Details"

---

## 📍 Key File Locations

### Main Files
- **Page**: `apps/web/app/[locale]/(public)/listings/[id]/page.tsx`
- **Detail Client**: `apps/web/components/listings/listing-detail-client.tsx`
- **Image Gallery**: `apps/web/components/listings/image-gallery.tsx`
- **Image Upload**: `apps/web/components/listings/image-upload.tsx`
- **Property Card**: `apps/web/components/search/property-card.tsx`

### Configuration
- **Tailwind Config**: `apps/web/tailwind.config.ts`
- **Next.js Config**: `apps/web/next.config.js`
- **Global Styles**: `apps/web/app/globals.css`

### API & State
- **Listings API**: `apps/web/lib/listings-api.ts`
- **Auth Store**: `apps/web/lib/auth-store.ts`
- **Comparison Store**: `apps/web/lib/comparison-store.ts`

### UI Components
- **Button**: `apps/web/components/ui/button.tsx`
- **Badge**: `apps/web/components/ui/badge.tsx`
- **Card**: `apps/web/components/ui/card.tsx`
- **Dialog**: `apps/web/components/ui/dialog.tsx`

---

## 🔑 Key Technologies

| Technology | Version | Purpose |
|-----------|---------|---------|
| Next.js | 15.5.14 | Full-stack framework (App Router) |
| React | 18.3.0 | UI library |
| Tailwind CSS | 3.4.0 | Styling with CSS variables |
| Zustand | 5.0.12 | State management |
| next-intl | 4.9.0 | i18n (Vietnamese/English) |
| React Query | 5.96.2 | Server state management |
| Lucide React | 1.7.0 | Icons |
| Mapbox GL | 3.21.0 | Maps |
| CVA | 0.7.1 | Component variants |

---

## ✨ Current Features

### Image Display
- ✅ Responsive main image (16:9 aspect ratio)
- ✅ Previous/Next navigation buttons
- ✅ Image counter badge ("X / Total")
- ✅ Horizontal scrollable thumbnails (64x64px)
- ✅ Selected thumbnail highlighting
- ✅ Empty state fallback
- ✅ Next.js Image optimization (responsive sizes)
- ✅ Lazy loading for thumbnails
- ✅ Priority loading for first image

### Image Upload
- ✅ Drag & drop support
- ✅ Click to browse
- ✅ File type validation (JPEG, PNG, WebP)
- ✅ File size validation (10MB max)
- ✅ Max 20 files limit
- ✅ Preview grid
- ✅ Delete button on hover
- ✅ Cover photo indicator
- ✅ URL cleanup on unmount

### Page Features
- ✅ SEO metadata (Open Graph, Twitter Cards)
- ✅ JSON-LD structured data
- ✅ Breadcrumb navigation
- ✅ Property details cards
- ✅ Amenities list
- ✅ Map integration
- ✅ Contact sidebar (sticky)
- ✅ Statistics (views, saves, inquiries)
- ✅ Comparison feature integration

---

## 🚀 NOT Currently Implemented

- ❌ Image lightbox / modal zoom
- ❌ Keyboard navigation (← →)
- ❌ Touch gestures / swipe support
- ❌ Image carousel transitions
- ❌ Upload progress bar
- ❌ Multiple file upload progress
- ❌ Image cropping / editing
- ❌ Video playback
- ❌ 360° panorama viewer
- ❌ AI image analysis

---

## 📋 Data Structure Quick Reference

### PropertyMedia
```typescript
{
  id: string;
  url: string;              // HTTPS URL to image
  type: 'image' | 'video';  // Type filter
  order: number;            // Sort order (0, 1, 2...)
  caption: string | null;   // Optional caption
}
```

### ListingDetail (partial)
```typescript
{
  id: string;
  property: {
    media: PropertyMedia[];  // Array of images/videos
    // ... other property fields
  };
  // ... other listing fields
}
```

---

## 🎓 Learning Paths

### I want to understand how images work:
1. Read: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Section 2
2. Review: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Section "Working with Images"
3. Check: `image-gallery.tsx` source code
4. Check: `next.config.js` image configuration

### I want to modify the gallery:
1. Check: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - "Modify Image Gallery"
2. Edit: `apps/web/components/listings/image-gallery.tsx`
3. Test: Responsive behavior and state changes
4. Reference: **PROPERTY_DETAIL_COMPONENTS_MAP.md** - "Image Gallery Component Details"

### I want to add a new feature (like lightbox):
1. Choose library: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Section 7
2. Install: Use `pnpm add package-name -F @goodgo/web`
3. Create: New component wrapper
4. Integrate: With existing ImageGallery
5. Test: Multiple images, responsive, edge cases

### I want to understand state management:
1. Read: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Section 6
2. Review: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Section "State Management"
3. Check: `auth-store.ts` and `comparison-store.ts`

### I want to understand component patterns:
1. Read: **PROPERTY_DETAIL_PAGE_ANALYSIS.md** - Section 4
2. Check: **PROPERTY_DETAIL_COMPONENTS_MAP.md** - "Component Complexity Levels"
3. Review: **PROPERTY_DETAIL_QUICK_REFERENCE.md** - Section "UI Component Patterns"

---

## 🔗 Navigation Between Docs

```
PROPERTY_DETAIL_PAGE_ANALYSIS.md
├─ "Section 1" → Component structure → See PROPERTY_DETAIL_COMPONENTS_MAP.md
├─ "Section 2" → Image implementation → See PROPERTY_DETAIL_QUICK_REFERENCE.md "Working with Images"
├─ "Section 4" → Component patterns → See PROPERTY_DETAIL_QUICK_REFERENCE.md "UI Component Patterns"
├─ "Section 5" → Next.js patterns → See PROPERTY_DETAIL_QUICK_REFERENCE.md "Using Images in Components"
└─ "Section 6" → State management → See PROPERTY_DETAIL_QUICK_REFERENCE.md "State Management"

PROPERTY_DETAIL_QUICK_REFERENCE.md
├─ Quick navigation → See PROPERTY_DETAIL_COMPONENTS_MAP.md for full tree
├─ Working with images → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 2
└─ Common tasks → See PROPERTY_DETAIL_COMPONENTS_MAP.md "Maintenance Guide"

PROPERTY_DETAIL_COMPONENTS_MAP.md
├─ Page hierarchy → Overview → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 1
├─ Gallery details → Implementation → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 2
└─ Import map → File paths → See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 10
```

---

## 💡 Tips & Best Practices

### Image Optimization
- Always use `sizes` prop with Next.js Image
- Set `priority={true}` only for above-fold images
- Use aspect ratio containers to prevent layout shift
- Let Next.js handle format selection (WebP, AVIF)

### Component Design
- Keep components focused (single responsibility)
- Use CVA for variant management
- Use composition over inheritance
- Keep local state for UI, global for app state

### State Management
- Use Zustand for global state (auth, comparison)
- Use local React state for component UI (gallery index)
- Use React Query for server state
- Persist only essential data to localStorage

### Testing
- Mock Next.js Image component
- Test responsive behavior
- Test edge cases (empty state, many images)
- Mock Zustand stores

---

## 🤝 Contributing Changes

### To modify the image gallery:
1. Create a new branch
2. Edit `apps/web/components/listings/image-gallery.tsx`
3. Test responsive behavior
4. Update type definitions if needed
5. Submit PR with description

### To add a new image feature:
1. Check PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 12 (not present section)
2. Evaluate library options
3. Create component wrapper
4. Integrate without breaking existing features
5. Document changes

### To update documentation:
1. Edit corresponding `.md` file
2. Keep sections organized
3. Include code examples
4. Cross-reference other docs
5. Maintain consistent formatting

---

## 📞 Quick Answers

**Q: How do I display an image?**  
A: Use `next/image` with `fill` layout and aspect ratio container. See PROPERTY_DETAIL_QUICK_REFERENCE.md "Using Images in Components"

**Q: How do I add state management?**  
A: Use Zustand for global, React.useState for local. See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 6

**Q: How do I add a lightbox?**  
A: Install library, create wrapper, integrate with gallery. See PROPERTY_DETAIL_QUICK_REFERENCE.md "Add Image Lightbox"

**Q: Where are the UI components?**  
A: `apps/web/components/ui/`. See PROPERTY_DETAIL_PAGE_ANALYSIS.md Section 10

**Q: What image formats are allowed?**  
A: JPEG, PNG, WebP. See PROPERTY_DETAIL_QUICK_REFERENCE.md "File Upload Component"

**Q: Is there keyboard navigation?**  
A: Not currently. See PROPERTY_DETAIL_COMPONENTS_MAP.md "Component Checklist"

---

## 📊 Documentation Statistics

| Metric | Value |
|--------|-------|
| Total Lines | 1,737 |
| Analysis Document | 553 lines |
| Quick Reference | 583 lines |
| Components Map | 601 lines |
| Code Examples | 50+ snippets |
| Key Files Documented | 20+ |
| Technologies Covered | 10+ |

---

## ✅ Checklist for New Developers

- [ ] Read PROPERTY_DETAIL_PAGE_ANALYSIS.md (Sections 1-3)
- [ ] Review PROPERTY_DETAIL_COMPONENTS_MAP.md (Page hierarchy)
- [ ] Check key file locations (listed above)
- [ ] Understand data structure (PropertyMedia, ListingDetail)
- [ ] Review image gallery source code
- [ ] Understand Zustand store pattern
- [ ] Review UI component patterns
- [ ] Familiarize with Tailwind classes
- [ ] Test with local development environment
- [ ] Bookmark this index for quick reference

---

## 🎓 Next Steps

1. **Understand Current State**
   - Read comprehensive analysis
   - Review component hierarchy
   - Check existing components

2. **Plan Your Changes**
   - Reference quick guide
   - Check code patterns
   - Verify data structure

3. **Implement & Test**
   - Use provided snippets
   - Follow patterns
   - Test responsively

4. **Document Updates**
   - Update this index if needed
   - Add to relevant sections
   - Maintain consistency

---

**Last Updated:** 2026-04-11  
**Documentation Version:** 1.0  
**Status:** Complete & Comprehensive