docs: consolidate exploration & audit reports under docs/ (TEC-3094)
- 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>
This commit is contained in:
Ho Ngoc Hai
319
docs/explorations/from-desktop/README_EXPLORATION.txt
Normal file
319
docs/explorations/from-desktop/README_EXPLORATION.txt
Normal file
@@ -0,0 +1,319 @@
|
||||
╔══════════════════════════════════════════════════════════════════════════════╗
|
||||
║ 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
|
||||
═══════════════════════════════════════════════════════════════════════════════
|
||||
Reference in New Issue
Block a user