# 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
```typescript
const data = await apiClient.get<Type>('/endpoint');
```

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

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

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

---

## 🚀 Commands

```bash
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`