08b96f9c2d
- Move 8 stray .md (+5 .txt) from ~/Desktop into docs/explorations/from-desktop/ - Reorganize 27 .md/.txt at workspace root: - audit reports -> docs/audits/ - exploration reports -> docs/explorations/ - design system -> docs/design-system/ - Keep only README/CHANGELOG/CONTRIBUTING/CLAUDE at repo root - Refresh docs/README.md as canonical index with links to all groups - Note: pre-existing docs/audits/AUDIT_INDEX.md and AUDIT_SUMMARY.md were overwritten by the newer root-level versions during the move Co-Authored-By: Paperclip <noreply@paperclip.ing>
320 lines
16 KiB
Plaintext
320 lines
16 KiB
Plaintext
╔══════════════════════════════════════════════════════════════════════════════╗
|
|
║ 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
|
|
═══════════════════════════════════════════════════════════════════════════════
|