╔══════════════════════════════════════════════════════════════════════════════╗
║                    FRONTEND EXPLORATION SUMMARY                             ║
║                     GoodGo Platform AI - Next.js                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

EXPLORATION COMPLETED: April 21, 2026
BASE PATH: /Users/velikho/Desktop/WORKING/goodgo-platform-ai/apps/web

📋 REPORTS GENERATED:
────────────────────────────────────────────────────────────────────────────

1. FRONTEND_EXPLORATION_REPORT.md (16 KB)
   └─ Comprehensive 12-section technical deep-dive
      • Project structure (directory layout)
      • Core technologies & dependencies
      • App Router structure & route organization
      • Component directory (23 domains)
      • Neighborhood components detail
      • Mapbox GL integration patterns
      • API client setup & domain-specific modules
      • React Query hooks & caching strategy
      • Chart components (Recharts)
      • Listing detail page structure (39 KB client component)
      • State management layers (React Query, Zustand, Context)
      • Key file patterns & conventions
      • Performance & SEO optimizations

2. FRONTEND_QUICK_REFERENCE.txt (19 KB)
   └─ 15-section quick lookup guide
      • Project structure overview
      • Core tech stack
      • Neighborhood features & types
      • Mapbox GL usage patterns
      • Chart components
      • API client patterns
      • React Query hooks
      • Listing detail page flow
      • State management layers
      • Design system components
      • Internationalization setup
      • Performance optimizations
      • Key file paths reference
      • Coding patterns examples
      • Debugging tips

3. ARCHITECTURE_OVERVIEW.txt (16 KB)
   └─ Visual ASCII diagrams & data flows
      • Routing & layout hierarchy
      • Listing detail page component flow
      • API & state management data flow
      • Neighborhood components detail
      • Chart components stack
      • Component import patterns (static/dynamic)
      • Mapbox GL initialization flow
      • i18n flow
      • SEO & metadata generation

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏗️  KEY FINDINGS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. DIRECTORY STRUCTURE
   ✓ Domain-based organization (listings/, neighborhood/, map/, charts/)
   ✓ Shared utilities in /lib (API clients, hooks, stores)
   ✓ Design system components in /components/design-system/
   ✓ Next.js 15 App Router with locale prefix [locale]
   ✓ Multi-level layout hierarchy: root → locale → group → feature

2. NEIGHBORHOOD FEATURES (FULLY IMPLEMENTED)
   ✓ NeighborhoodPOIMap (11 KB) - Mapbox GL with 6 POI categories
   ✓ NeighborhoodRadarChart (2 KB) - Recharts radar with 0-10 scores
   ✓ NeighborhoodScore (2 KB) - Compact score display
   ✓ Rich type definitions (NeighborhoodScoreData, POIItem, NeighborhoodCategory)
   ✓ Integration point: Dynamically loaded in listing-detail-client.tsx

3. MAPBOX GL INTEGRATION
   ✓ 3 map components: listing-map, location-picker, neighborhood-poi-map
   ✓ Theme-aware styling (light/dark) via useMapboxStyle() hook
   ✓ CSS imported per component: 'mapbox-gl/dist/mapbox-gl.css'
   ✓ SVG marker icons for POI categories (school, hospital, transit, shopping, restaurant, park)
   ✓ Client-only rendering (no SSR)

4. CHART COMPONENTS (RECHARTS)
   ✓ 6 chart types: price area, price trend, district bar, heatmap, performance, radar
   ✓ Vietnamese number formatting (tr/k notation for millions)
   ✓ Signal colors (green/red) via CSS variables
   ✓ Responsive containers with theme-aware tooltips
   ✓ Dynamic imports for performance

5. API ARCHITECTURE
   ✓ Base client: lib/api-client.ts (127 lines)
     • CSRF token handling
     • Automatic 401 refresh-and-retry
     • Concurrent refresh coalescing
     • Type-safe generics
   ✓ 12+ domain-specific API modules (listings, analytics, valuation, agents, etc.)
   ✓ Both client-side and server-side implementations

6. STATE MANAGEMENT
   ✓ Layer 1: React Query (server state caching)
   ✓ Layer 2: Zustand (client UI state)
   ✓ Layer 3: React Context (global features: theme, notifications, auth)
   ✓ Query keys follow strict naming convention for cache invalidation

7. LISTING DETAIL PAGE
   ✓ Server component: /[locale]/(public)/listings/[id]/page.tsx
   ✓ generateMetadata() for SEO (OG, canonical, schema)
   ✓ Client component: 39 KB listing-detail-client.tsx
   ✓ 9 major sections with dynamic imports for heavy components
   ✓ Neighborhood section uses dynamic imports (SSR: false)

8. PERFORMANCE OPTIMIZATIONS
   ✓ Code splitting via dynamic imports (maps, charts)
   ✓ Lazy loading with loading fallbacks
   ✓ React Query automatic caching + deduplication
   ✓ Tailwind CSS + CVA for efficient styling
   ✓ Responsive containers for all visualizations

9. INTERNATIONALIZATION
   ✓ next-intl 4.9.0 for translations
   ✓ Locale prefix in routes: [locale]
   ✓ Two locales: vi (Vietnamese), en (English)
   ✓ Translations in /messages directory

10. DESIGN SYSTEM
    ✓ Financial components (KPI cards, stat cards, price delta, signal display)
    ✓ Data display (data table wrapper, empty states, skeletons)
    ✓ Layout components (dashboard layout, density provider)
    ✓ UI primitives from shadcn/ui (badge, button, card, dialog, etc.)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 DEPENDENCIES SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CORE FRAMEWORK:
  • Next.js 15.5.14 (App Router)
  • React 18.3.0

STATE & DATA:
  • @tanstack/react-query 5.96.2 (server state)
  • @tanstack/react-table 8.21.3 (table rendering)
  • zustand 5.0.12 (client state)

UI & STYLING:
  • Tailwind CSS 3.4.0
  • class-variance-authority 0.7.1
  • lucide-react 1.7.0 (icons)

FORMS & VALIDATION:
  • react-hook-form 7.72.1
  • @hookform/resolvers 5.2.2
  • zod 4.3.6

MAPPING & CHARTS:
  • mapbox-gl 3.21.0 ⭐
  • recharts 3.8.1 ⭐

UTILITIES:
  • next-intl 4.9.0 (i18n)
  • next-themes 0.4.6 (theme)
  • socket.io-client 4.8.3 (real-time)
  • html2canvas 1.4.1 + jspdf 4.2.1 (PDF export)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔗 COMPONENT IMPORT PATTERNS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Static imports (always in bundle):
  import { Badge } from '@/components/ui/badge';
  import { useMarketReport } from '@/lib/hooks/use-analytics';

Dynamic imports (code-split):
  const NeighborhoodMap = dynamic(
    () => import('@/components/neighborhood').then(m => m.NeighborhoodPOIMap),
    { ssr: false, loading: () => <Skeleton /> }
  );

Barrel exports (clean imports):
  // components/neighborhood/index.ts
  export { NeighborhoodRadarChart } from './neighborhood-radar-chart';
  export { NeighborhoodPOIMap } from './neighborhood-poi-map';
  
  // Usage:
  import { NeighborhoodRadarChart, NeighborhoodPOIMap } from '@/components/neighborhood';

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 QUICK START FOR DEVELOPMENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ENVIRONMENT VARIABLES:
  NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1
  NEXT_PUBLIC_SITE_URL=https://goodgo.vn
  MAPBOX_ACCESS_TOKEN=pk_... (from Mapbox)

COMMANDS:
  npm run dev           ← Start dev server (port 3000)
  npm run build         ← Production build
  npm run lint          ← ESLint check
  npm test              ← Vitest tests
  npm run typecheck     ← TypeScript check

KEY FILES TO KNOW:
  lib/api-client.ts                              ← Base HTTP client
  lib/listings-api.ts                            ← Listings endpoints
  lib/hooks/use-analytics.ts                     ← React Query pattern
  components/listings/listing-detail-client.tsx ← Main detail page
  components/neighborhood/                       ← Neighborhood features
  components/charts/                             ← Chart components
  lib/mapbox-style.ts                            ← Map styling

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 NOTABLE IMPLEMENTATION DETAILS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. CSRF PROTECTION
   └─ Token read from cookies on every request
   └─ Sent as X-CSRF-Token header for non-GET requests

2. AUTH TOKEN REFRESH
   └─ Automatic 401 handling with silent refresh
   └─ Concurrent requests coalesced to single refresh call
   └─ Auth endpoints excluded from refresh-retry

3. POI CATEGORIES
   └─ 6 types: school, hospital, transit, shopping, restaurant, park
   └─ SVG icons embedded in marker creation
   └─ Color-coded by category in POI_CATEGORY_CONFIG

4. NEIGHBORHOOD SCORING
   └─ 6 categories on 0-10 scale: education, healthcare, transport, shopping, dining, environment
   └─ RadarChart displays all at once with badges below
   └─ POIMap shows actual locations with distance info

5. PRICE FORMATTING
   └─ Vietnamese currency (VND) with tr/k notation
   └─ 1 tỷ = 1 billion (1,000,000,000)
   └─ 1 tr = 1 million (1,000,000)
   └─ 1 k = 1 thousand (1,000)

6. THEME SWITCHING
   └─ next-themes manages light/dark mode
   └─ Mapbox styles update reactively
   └─ CSS variables for component theming

7. DYNAMIC COMPONENT LOADING
   └─ Heavy components (NeighborhoodMap, charts) code-split
   └─ SSR disabled for client-only components
   └─ Loading fallback UI shown during load

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 PRO TIPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Use barrel exports (index.ts) for cleaner component imports
✓ Always add 'enabled' condition to useQuery() for dependent queries
✓ CSS variables (--signal-up, --color-border) support light/dark themes
✓ React Query query keys are the foundation—get them right for caching
✓ Mapbox GL must be in client components ('use client') 
✓ Dynamic imports reduce initial bundle size significantly
✓ Design system provides trader-style financial components
✓ API responses are type-safe via domain-specific API modules
✓ SVG icons in POI markers avoid loading external font files
✓ Responsive containers automatically adjust chart/map sizing

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 FILE SIZE REFERENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

LARGE COMPONENTS (candidates for dynamic import):
  listing-detail-client.tsx      39 KB (main listing detail)
  listing-form-steps.tsx         14 KB (form wizard)
  neighborhood-poi-map.tsx       11 KB (Mapbox visualization)
  ai-advice-cards.tsx            9 KB (AI recommendations)
  district-heatmap.tsx           9 KB (heat visualization)
  location-picker.tsx            9 KB (map picker)

MEDIUM COMPONENTS:
  agent-performance.tsx          6 KB (agent metrics chart)
  price-history-chart.tsx        2 KB (inline price chart)

SMALL COMPONENTS:
  neighborhood-radar-chart.tsx   2 KB (radar chart)
  neighborhood-score.tsx         2 KB (score display)
  price-area-chart.tsx           2 KB (area chart)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 NEXT STEPS FOR DEVELOPMENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Study the three generated reports in this order:
   a) ARCHITECTURE_OVERVIEW.txt (visual understanding)
   b) FRONTEND_QUICK_REFERENCE.txt (quick lookups)
   c) FRONTEND_EXPLORATION_REPORT.md (deep dive)

2. Familiarize yourself with key files:
   - lib/api-client.ts (understanding HTTP patterns)
   - lib/listings-api.ts (domain API example)
   - components/listings/listing-detail-client.tsx (main page structure)
   - components/neighborhood/ (neighborhood features)

3. Run the dev server:
   npm run dev
   Open http://localhost:3000/vi/listings/[any-id]

4. Explore in browser:
   - Check Network tab to see API calls
   - Toggle theme to see Mapbox style change
   - Inspect React tree to understand component hierarchy
   - Check local storage for persisted state

5. Experiment with modifications:
   - Add console.log to understand data flow
   - Try modifying neighborhood scores to see chart update
   - Add new query hooks following existing patterns
   - Create a test component using existing patterns

═══════════════════════════════════════════════════════════════════════════════
Questions? Reference the reports or check key file paths in QUICK_REFERENCE.txt
═══════════════════════════════════════════════════════════════════════════════