goodgo-platform/docs/explorations/from-desktop/INDEX_frontend_exploration.md

GoodGo Frontend Exploration - Complete Documentation

📁 Generated Files

All files are saved to your Desktop. Read them in this order:

1. README_EXPLORATION.txt (16 KB) ⭐ START HERE

• Purpose: Overview & quick summary
• Contents:
  • Key findings (10 major insights)
  • Dependencies summary
  • Component import patterns
  • Quick start guide
  • Notable implementation details
  • Pro tips & file size reference
  • Next steps for development

2. ARCHITECTURE_OVERVIEW.txt (24 KB)

• Purpose: Visual diagrams & data flows
• Contents:
  • Routing & layout hierarchy (ASCII tree)
  • 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 diagram
  • SEO & metadata generation flow

3. FRONTEND_QUICK_REFERENCE.txt (19 KB)

• Purpose: Quick lookup reference
• Contents: 15 sections covering:
  • Project structure
  • Core tech stack
  • Neighborhood features detail
  • Mapbox GL patterns
  • Chart components
  • API client architecture
  • React Query hooks
  • Listing detail page flow
  • State management layers
  • Design system components
  • i18n setup
  • Performance optimizations
  • Key file paths
  • Coding patterns
  • Debugging tips

4. FRONTEND_EXPLORATION_REPORT.md (16 KB)

• Purpose: Deep technical dive
• Contents: 12 comprehensive sections:
  1. Overall directory structure
  2. App Router structure
  3. Components directory (23 domains)
  4. Existing neighborhood components
  5. Mapbox GL integration
  6. API client setup
  7. Hooks & React Query integration
  8. Chart components (Recharts)
  9. Listing detail page structure
  10. State management patterns
  11. Key file patterns & conventions
  12. Performance & SEO optimizations

---

🗺️ Quick Navigation

For different needs, use:

"I want a 5-minute overview" → Read: README_EXPLORATION.txt (Key Findings section)

"I need to understand the architecture" → Read: ARCHITECTURE_OVERVIEW.txt (start with the diagrams)

"I need to find a specific file or pattern" → Search: FRONTEND_QUICK_REFERENCE.txt (Use Ctrl+F)

"I need complete technical details" → Read: FRONTEND_EXPLORATION_REPORT.md (full reference)

---

📊 Project Stats

• Framework: Next.js 15.5.14 with App Router
• Components: 23 domains with 15+ major feature areas
• Mapping: Mapbox GL 3.21.0 (3 map components)
• Charts: Recharts 3.8.1 (6 chart types)
• Neighborhood Features: Fully implemented (3 components)
• API Modules: 12+ domain-specific clients
• React Query Hooks: 10+ custom hooks
• Routes: Public, Auth, Dashboard, Admin (all locale-aware)
• Listing Detail Page: 39 KB client component with 9 sections

---

🎯 Key Takeaways

Architecture

• ✅ Domain-based component organization
• ✅ Separated concerns (API, hooks, stores, components)
• ✅ Locale-aware routing with i18n
• ✅ Dynamic imports for performance
• ✅ Type-safe API client with CSRF protection

Features

• ✅ Neighborhood scoring (6 categories, 0-10 scale)
• ✅ POI mapping (6 categories with SVG icons)
• ✅ Price history charts
• ✅ Theme switching (light/dark) with Mapbox
• ✅ Multi-language support (Vietnamese/English)

Tech Stack

• ✅ React 18 + Next.js 15 App Router
• ✅ Tailwind CSS + CVA for styling
• ✅ React Query + Zustand for state
• ✅ Mapbox GL for mapping
• ✅ Recharts for data visualization
• ✅ next-intl for internationalization

---

🔍 Key Files

lib/
├── api-client.ts                 # Base HTTP client (CSRF, 401 refresh)
├── listings-api.ts               # Listing endpoints
├── analytics-api.ts              # Analytics/market data
├── mapbox-style.ts               # Theme-aware map styles
└── hooks/
    └── use-analytics.ts          # React Query pattern example

components/
├── listings/
│   └── listing-detail-client.tsx # Main detail page (39 KB)
├── neighborhood/
│   ├── neighborhood-poi-map.tsx  # Mapbox POI layer (11 KB)
│   ├── neighborhood-radar-chart.tsx # Recharts radar (2 KB)
│   └── types.ts                  # Neighborhood types
├── map/
│   ├── listing-map.tsx           # Listings on map
│   └── location-picker.tsx       # Location selection
├── charts/
│   ├── price-area-chart.tsx      # Area chart
│   ├── district-heatmap.tsx      # Heat visualization
│   └── ...
└── design-system/                # UI components & patterns

app/
└── [locale]/
    ├── (public)/listings/[id]/page.tsx  # Detail page (Server RSC)
    ├── (dashboard)/                     # Protected routes
    └── (admin)/                         # Admin routes

---

💡 Important Patterns

API Usage

const data = await apiClient.get<Type>('/endpoint');

React Query Hook

export function useData(param: string) {
  return useQuery({
    queryKey: ['key', param],
    queryFn: () => api.getData(param),
    enabled: !!param,
  });
}

Dynamic Component Import

const Component = dynamic(() => import('...'), {
  ssr: false,
  loading: () => <Skeleton />
});

Mapbox Integration

'use client'
const style = useMapboxStyle(); // light/dark
const map = new mapboxgl.Map({ style });

---

🚀 Commands

npm run dev         # Dev server (port 3000)
npm run build       # Production build
npm run lint        # ESLint check
npm test            # Vitest tests
npm run typecheck   # TypeScript check

---

📝 Notes

• All reports are self-contained - you can read any of them independently
• File paths are absolute from /apps/web
• Component sizes range from 2 KB (radar chart) to 39 KB (listing detail)
• Neighborhood features are already implemented and ready to use
• Mapbox GL requires 'use client' directive
• All charts use CSS variables for theming
• i18n uses [locale] route parameter (vi/en)

---

📞 Quick Reference

What does NeighborhoodPOIMap do? → Section 3 of README, or QUICK_REFERENCE section 3

How do I add a new chart? → QUICK_REFERENCE section 5 (Chart Components)

Where's the API client? → QUICK_REFERENCE section 6 (API Client Pattern)

How does state management work? → README section "State Management Layers" or QUICK_REFERENCE section 9

What about performance? → QUICK_REFERENCE section 12 (Performance Optimizations)

---

Generated: April 21, 2026 Base Path: /Users/velikho/Desktop/WORKING/goodgo-platform-ai/apps/web