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
241
docs/explorations/from-desktop/INDEX_frontend_exploration.md
Normal file
241
docs/explorations/from-desktop/INDEX_frontend_exploration.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user