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

{
  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)

{
  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