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>
20 KiB
20 KiB
Next.js Frontend Architecture - Visual Flowchart
📊 Data Flow Architecture
┌─────────────────────────────────────────────────────────────────┐
│ USER'S BROWSER │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Client Component ('use client') │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ React Hooks: useState, useEffect, useContext │ │ │
│ │ │ React Query: useQuery, useMutation │ │ │
│ │ │ Local State: filters, viewMode, form data │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ API Client (apiClient.get/post/patch/delete) │ │ │
│ │ │ • Handles CSRF token │ │ │
│ │ │ • Auto-refresh on 401 │ │ │
│ │ │ • Credentials included │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ↓↑ │
│ HTTP Requests/Responses │
└─────────────────────────────────────────────────────────────────┘
↓↑
┌──────────────────────────────┐
│ Backend API (Node/Express)│
│ /projects /listings │
│ /projects/[slug] │
│ /projects/[id]/inquiries │
└──────────────────────────────┘
🏗️ Page Rendering Flow
Pattern 1: Public Browse Page (/du-an)
┌─────────────────────────────────┐
│ Server Component (SSR) │
│ ✓ Layouts applied │
│ ✓ Metadata generated │
│ ✓ i18n applied │
└──────────┬──────────────────────┘
↓
┌─────────────────────────────────┐
│ Client Component │
│ ✓ useState: filters, viewMode │
│ ✓ useProjectsSearch hook │
│ ✓ Render grid/list/map view │
│ ✓ Handle filter changes │
└──────────┬──────────────────────┘
↓
┌─────────────────────────────────┐
│ UI Components │
│ ├─ ProjectFilterBar │
│ ├─ ProjectCard (grid) │
│ ├─ ProjectListItem (list) │
│ └─ ProjectMap (Mapbox) │
└─────────────────────────────────┘
Pattern 2: Detail Page (/du-an/[slug])
REQUEST: /du-an/my-project-slug
│
↓
┌─────────────────────────────────┐
│ Server Component (generateMetadata)
│ • Fetch project by slug (ISR 5min)
│ • Generate metadata (title, description, OG)
│ • Return to page
└──────────┬──────────────────────┘
↓
┌─────────────────────────────────┐
│ Server Component (Page) │
│ • Fetch project again by slug │
│ • notFound() if not exists │
│ • Pass to client component │
└──────────┬──────────────────────┘
↓
┌─────────────────────────────────┐
│ Client Component (DuAnDetailClient)
│ • Tabs: amenities, location, price
│ • Live data fetch: POIs, scores
│ • Contact form handling │
└──────────┬──────────────────────┘
↓
┌─────────────────────────────────┐
│ Dynamic Components │
│ ├─ PriceTrendChart │
│ ├─ NeighborhoodRadarChart │
│ └─ NeighborhoodPOIMap │
└─────────────────────────────────┘
Pattern 3: Admin CRUD Page (/projects)
REQUEST: /projects (DEVELOPER only)
│
↓
┌─────────────────────────────────┐
│ Client Component (full) │
│ • Check auth: useAuthStore │
│ • Define filters state │
│ • Setup React Query │
└──────────┬──────────────────────┘
↓
┌─────────────────────────────────┐
│ useQuery { │
│ queryKey: ['projects', params] │
│ queryFn: duAnApi.searchMine() │
│ } │
└──────────┬──────────────────────┘
↓
┌─────────────────────────────────┐
│ Render List + Actions: │
│ ├─ New project button │
│ ├─ Filter inputs │
│ ├─ Project rows with actions │
│ ├─ Edit link → /projects/[id]/ │
│ └─ Delete → useMutation │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ useMutation { │
│ mutationFn: duAnApi.delete │
│ onSuccess: invalidateQueries │
│ } │
└─────────────────────────────────┘
📚 Component Hierarchy
(Root Layout)
├── Locale Selector [locale]
│ ├── Locale Provider
│ ├── Auth Provider
│ ├── Theme Provider
│ │
│ ├── Route Group: (public)
│ │ ├── Header/Footer
│ │ ├── Route: du-an/
│ │ │ ├── Server: DuAnPage (Server)
│ │ │ │ └── Client: DuAnPage (Client) ← Main browsing
│ │ │ │ ├── ProjectFilterBar
│ │ │ │ ├── ProjectCard[] (grid)
│ │ │ │ ├── ProjectListItem[] (list)
│ │ │ │ └── ProjectMap (Mapbox) [dynamic]
│ │ │ │
│ │ │ └── Route: [slug]/
│ │ │ ├── Server: generateMetadata() → fetch()
│ │ │ ├── Server: Page() → fetch()
│ │ │ └── Client: DuAnDetailClient
│ │ │ ├── Tabs
│ │ │ ├── PriceTrendChart [dynamic]
│ │ │ ├── NeighborhoodRadarChart [dynamic]
│ │ │ └── NeighborhoodPOIMap [dynamic]
│ │ │
│ │ └── Other routes: listings/, search/, etc.
│ │
│ ├── Route Group: (auth)
│ │ ├── Login
│ │ └── Register
│ │
│ └── Route Group: (dashboard)
│ ├── ProtectedLayout (auth check)
│ ├── Sidebar/Navbar
│ │
│ ├── Route: dashboard/ (main dashboard)
│ │
│ ├── Route: projects/ ← Project Management
│ │ ├── Page (CRUD list)
│ │ ├── new/Page (create form)
│ │ └── [id]/edit/Page (update form)
│ │
│ ├── Route: listings/ (list management)
│ ├── Route: leads/ (lead management)
│ ├── Route: analytics/ (analytics dashboard)
│ └── ...other dashboard routes
│
└── Route Group: (admin)
└── Route: admin/ (admin panel)
🔄 Data Fetching Timeline
User navigates to /du-an/my-project-slug
│
├─ [1] generateMetadata() in Server Component
│ └─ fetchProjectBySlug(slug) ← fetch() + normalization
│ └─ Returns Metadata { title, description, og }
│
├─ [2] Page() Server Component renders
│ └─ fetchProjectBySlug(slug) ← fetch() again (cached)
│ └─ Pass project to Client Component
│
├─ [3] DuAnDetailClient renders
│ ├─ useEffect: Fetch neighborhood scores
│ │ └─ analyticsApi.getNeighborhoodScore()
│ │
│ └─ useEffect: Fetch POIs
│ └─ analyticsApi.getNearbyPOIs()
│
└─ Browser receives complete HTML + JS
└─ Hydration → interactive
🧠 API Layer Organization
┌────────────────────────────────────────────────────────┐
│ API Client Layer │
│ │
│ apiClient = { │
│ get<T>(endpoint, headers) │
│ post<T>(endpoint, body, headers) │
│ patch<T>(endpoint, body, headers) │
│ delete<T>(endpoint, headers) │
│ } │
│ │
│ Features: │
│ • CSRF token extraction from cookies │
│ • Auto-refresh on 401 │
│ • Credentials included │
│ • Coalesced refresh (only once) │
└────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────┐
│ Domain APIs │
│ │
│ duAnApi = { │
│ search(params) → /projects?... │
│ searchMine(params) → /projects/mine/list │
│ getBySlug(slug) → /projects/[slug] │
│ getStats(id) → /projects/[id]/stats │
│ create(payload) → POST /projects │
│ update(id, payload) → PATCH /projects/[id] │
│ delete(id) → DELETE /projects/[id] │
│ } │
│ │
│ listingsApi = { ... } │
│ khuCongNghiepApi = { ... } │
│ inquiriesApi = { ... } │
│ analyticsApi = { ... } │
│ ... (other domains) │
└────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────┐
│ React Query Hooks │
│ │
│ useProjectsSearch(params) { │
│ return useQuery({ │
│ queryKey: ['projects', 'search', params], │
│ queryFn: () => duAnApi.search(params), │
│ }) │
│ } │
│ │
│ useProjectDetail(slug) { │
│ return useQuery({ │
│ queryKey: ['projects', 'detail', slug], │
│ queryFn: () => duAnApi.getBySlug(slug), │
│ enabled: !!slug, │
│ }) │
│ } │
│ │
│ ... (other hooks for each API) │
└────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────┐
│ Client Components │
│ │
│ export function MyComponent() { │
│ const { data, isLoading } = │
│ useProjectsSearch(filters); │
│ // Use data in UI │
│ } │
└────────────────────────────────────────────────────────┘
📍 Route Group Strategy
App Routes
│
├─ (public) ← No auth required, public layout
│ ├─ /du-an (browse)
│ ├─ /listings
│ ├─ /khu-cong-nghiep
│ ├─ /search
│ ├─ /agents
│ └─ ...other public pages
│
├─ (auth) ← Auth layout (login/register form)
│ ├─ /login
│ └─ /register
│
├─ (dashboard) ← Protected, dashboard layout
│ ├─ /dashboard (main)
│ ├─ /projects (CRUD)
│ ├─ /listings (CRUD)
│ ├─ /leads
│ ├─ /analytics
│ └─ ...other user pages
│
├─ (admin) ← Admin-only, admin layout
│ ├─ /admin
│ ├─ /admin/users
│ ├─ /admin/kyc
│ └─ ...other admin pages
│
└─ auth/callback/ ← Unprotected, OAuth callbacks
├─ /auth/callback/google
└─ /auth/callback/zalo
🎯 Type Flow
Backend Response
↓
┌──────────────────────────────┐
│ Raw JSON │
│ { │
│ "id": "...", │
│ "developer": { │
│ "logo": "url" ← might be missing
│ }, │
│ "media": [...], ← might be []
│ "amenities": [...] │
│ } │
└──────────────────────────────┘
↓
┌──────────────────────────────┐
│ normalizeProjectDetail() │
│ • Fill missing fields │
│ • Rename keys (logo→logoUrl) │
│ • Validate arrays │
│ • Ensure no null/undefined │
└──────────────────────────────┘
↓
┌──────────────────────────────┐
│ ProjectDetail Interface │
│ { │
│ id: string │
│ developer: { │
│ id, name, logoUrl │
│ } │
│ media: ProjectMedia[] │
│ amenities: ProjectAmenity[]│
│ } │
└──────────────────────────────┘
↓
┌──────────────────────────────┐
│ React Component │
│ Safe to use all fields │
│ TypeScript checks types │
└──────────────────────────────┘
🗺️ Mapbox Integration Flow
ProjectMap Component Mounts
│
├─ [1] Effect 1: Initialize map
│ ├─ Set accessToken
│ ├─ Create Map instance
│ ├─ Add controls (Navigation, Attribution)
│ └─ Store in ref
│
├─ [2] Effect 2: Change map style
│ └─ map.setStyle(newStyle)
│
└─ [3] Effect 3: Update markers (when projects change)
├─ Clear old markers
├─ For each project with lat/lng:
│ ├─ Create marker element
│ ├─ Create popup HTML
│ ├─ Add to map
│ └─ Extend bounds
├─ Fit bounds to all markers
│ └─ map.fitBounds(bounds, padding)
└─ Single marker? Fly to it
└─ map.flyTo(center, zoom)
🎨 Styling Cascade
Tailwind Config
├─ Design Tokens (CSS Variables)
│ ├─ --primary: 210 100% 50%
│ ├─ --secondary: 220 13% 91%
│ ├─ --muted: 210 10% 92%
│ └─ ... (full palette)
│
├─ Color System
│ ├─ primary: hsl(var(--primary))
│ ├─ secondary: hsl(var(--secondary))
│ ├─ background: { DEFAULT, elevated, surface }
│ ├─ foreground: { DEFAULT, muted, dim }
│ └─ ... (semantic colors)
│
├─ Spacing System
│ ├─ cell: 0.5rem
│ ├─ row: 2.25rem
│ ├─ sidebar: 15rem
│ └─ ... (spacing utilities)
│
├─ Typography
│ ├─ heading-sm: 0.875rem / 1.25rem
│ ├─ heading-md: 1.125rem / 1.5rem
│ └─ ... (font sizes)
│
└─ Components Use Classes
└─ className="text-primary bg-muted px-4 py-2 rounded-lg"
└─ Resolved at build time