a1a44ef8fb
Add comprehensive project documentation including changelog, QA tracker, code quality audit, implementation guide, K6 load testing guide, frontend exploration notes, and file mapping reference. Co-Authored-By: Paperclip <noreply@paperclip.ing>
535 lines
19 KiB
Markdown
535 lines
19 KiB
Markdown
# GoodGo Platform Frontend Exploration Report
|
|
## apps/web (Next.js 14 with App Router)
|
|
|
|
**Date:** April 9, 2026
|
|
**Status:** Pre-i18n (No existing i18n setup detected)
|
|
**Next.js Version:** 14.2.0 | **React:** 18.3.0
|
|
**Primary Language:** Vietnamese (vi_VN)
|
|
|
|
---
|
|
|
|
## 📁 Directory Structure Overview
|
|
|
|
```
|
|
apps/web/
|
|
├── app/ # Next.js App Router (main application)
|
|
│ ├── layout.tsx # Root layout with metadata & providers
|
|
│ ├── globals.css # Global Tailwind styles & theme variables
|
|
│ ├── middleware.ts # Already exists (auth routing middleware)
|
|
│ ├── loading.tsx # Root loading state
|
|
│ ├── error.tsx # Root error boundary
|
|
│ ├── not-found.tsx # 404 page
|
|
│ │
|
|
│ ├── (public)/ # Public route group
|
|
│ │ ├── layout.tsx # Public layout with header/footer
|
|
│ │ ├── page.tsx # Landing page (hero + featured listings)
|
|
│ │ ├── search/ # Search results page
|
|
│ │ │ ├── page.tsx
|
|
│ │ │ ├── layout.tsx
|
|
│ │ │ ├── error.tsx
|
|
│ │ │ ├── loading.tsx
|
|
│ │ │ └── __tests__/
|
|
│ │ └── listings/[id]/ # Listing detail page
|
|
│ │ └── page.tsx
|
|
│ │
|
|
│ ├── (auth)/ # Auth route group
|
|
│ │ ├── layout.tsx
|
|
│ │ ├── login/page.tsx # Login form
|
|
│ │ ├── register/page.tsx # Registration form
|
|
│ │ ├── error.tsx
|
|
│ │ ├── loading.tsx
|
|
│ │ └── __tests__/
|
|
│ │
|
|
│ ├── (dashboard)/ # Protected dashboard route group
|
|
│ │ ├── layout.tsx # Dashboard layout with sidebar nav
|
|
│ │ ├── dashboard/page.tsx # Main dashboard
|
|
│ │ ├── listings/
|
|
│ │ │ ├── page.tsx # User listings list
|
|
│ │ │ ├── new/page.tsx # Create listing (multi-step form)
|
|
│ │ │ └── [id]/edit/page.tsx
|
|
│ │ ├── analytics/page.tsx
|
|
│ │ ├── profile/page.tsx # User profile settings
|
|
│ │ ├── subscription/page.tsx # Subscription plans
|
|
│ │ ├── payments/page.tsx # Payment history
|
|
│ │ ├── valuation/page.tsx # AI property valuation
|
|
│ │ ├── error.tsx
|
|
│ │ ├── loading.tsx
|
|
│ │ └── __tests__/
|
|
│ │
|
|
│ ├── (admin)/ # Admin route group
|
|
│ │ ├── layout.tsx
|
|
│ │ ├── admin/page.tsx # Admin dashboard
|
|
│ │ ├── admin/users/page.tsx
|
|
│ │ ├── admin/kyc/page.tsx
|
|
│ │ ├── admin/moderation/page.tsx
|
|
│ │ ├── error.tsx
|
|
│ │ └── loading.tsx
|
|
│ │
|
|
│ ├── auth/ # Auth callbacks
|
|
│ │ └── callback/
|
|
│ │ ├── google/page.tsx
|
|
│ │ └── zalo/page.tsx
|
|
│ │
|
|
│ ├── api/ # API routes
|
|
│ │ └── health/route.ts
|
|
│ │
|
|
│ ├── robots.ts
|
|
│ └── sitemap.ts
|
|
│
|
|
├── components/ # Reusable React components
|
|
│ ├── providers/ # Context providers
|
|
│ │ ├── auth-provider.tsx # Auth context & store wrapper
|
|
│ │ ├── query-provider.tsx # TanStack React Query provider
|
|
│ │ └── theme-provider.tsx # Dark/light mode provider
|
|
│ │
|
|
│ ├── ui/ # Unstyled base UI components
|
|
│ │ ├── button.tsx # CVA-based button variants
|
|
│ │ ├── input.tsx
|
|
│ │ ├── label.tsx
|
|
│ │ ├── card.tsx
|
|
│ │ ├── dialog.tsx # Modal dialog
|
|
│ │ ├── tabs.tsx
|
|
│ │ ├── select.tsx # Custom select component
|
|
│ │ ├── badge.tsx
|
|
│ │ ├── textarea.tsx
|
|
│ │ ├── table.tsx
|
|
│ │ └── __tests__/ # Component tests
|
|
│ │
|
|
│ ├── auth/
|
|
│ │ └── oauth-buttons.tsx # Google & Zalo OAuth buttons
|
|
│ │
|
|
│ ├── search/
|
|
│ │ ├── filter-bar.tsx # Search filters (transaction, property, price range)
|
|
│ │ ├── property-card.tsx # Property listing card
|
|
│ │ └── search-results.tsx # Results container
|
|
│ │
|
|
│ ├── listings/
|
|
│ │ ├── listing-form-steps.tsx # Multi-step create/edit form
|
|
│ │ ├── image-upload.tsx # Image upload component
|
|
│ │ ├── image-gallery.tsx # Image gallery viewer
|
|
│ │ └── listing-status-badge.tsx # Status display badge
|
|
│ │
|
|
│ ├── map/
|
|
│ │ └── listing-map.tsx # Mapbox GL integration
|
|
│ │
|
|
│ ├── valuation/
|
|
│ │ ├── valuation-form.tsx
|
|
│ │ ├── valuation-results.tsx
|
|
│ │ ├── valuation-history.tsx
|
|
│ │ └── ai-estimate-button.tsx
|
|
│ │
|
|
│ └── charts/
|
|
│ ├── price-trend-chart.tsx
|
|
│ ├── agent-performance.tsx
|
|
│ └── district-heatmap.tsx
|
|
│
|
|
├── lib/ # Utilities and hooks
|
|
│ ├── utils.ts # cn() - clsx + tailwind-merge
|
|
│ ├── auth-store.ts # Zustand auth state management
|
|
│ ├── api-client.ts # Axios/fetch wrapper
|
|
│ ├── query-client.ts # TanStack React Query config
|
|
│ │
|
|
│ ├── hooks/
|
|
│ │ ├── use-listings.ts
|
|
│ │ ├── use-analytics.ts
|
|
│ │ ├── use-valuation.ts
|
|
│ │ ├── use-payments.ts
|
|
│ │ └── use-subscription.ts
|
|
│ │
|
|
│ ├── validations/ # Zod schemas
|
|
│ │ ├── auth.ts # Login/register schemas
|
|
│ │ ├── listings.ts # Multi-step listing schemas
|
|
│ │ └── valuation.ts
|
|
│ │
|
|
│ ├── *-api.ts # API clients
|
|
│ │ ├── auth-api.ts
|
|
│ │ ├── listings-api.ts
|
|
│ │ ├── profile-api.ts
|
|
│ │ ├── payment-api.ts
|
|
│ │ ├── subscription-api.ts
|
|
│ │ ├── analytics-api.ts
|
|
│ │ ├── valuation-api.ts
|
|
│ │ └── admin-api.ts
|
|
│ │
|
|
│ └── __tests__/ # Unit tests (Vitest + React Testing Library)
|
|
│ ├── auth-store.spec.ts
|
|
│ ├── auth-validations.spec.ts
|
|
│ ├── listing-validations.spec.ts
|
|
│ └── utils.spec.ts
|
|
│
|
|
├── public/ # Static assets
|
|
│ └── [images, icons, etc.]
|
|
│
|
|
├── .next/ # Build output (generated)
|
|
├── node_modules/
|
|
│
|
|
└── Configuration Files:
|
|
├── package.json # Dependencies & scripts
|
|
├── next.config.js # Next.js config (Sentry, CSP, headers)
|
|
├── tailwind.config.ts # Tailwind CSS config
|
|
├── postcss.config.js # PostCSS config (Tailwind + Autoprefixer)
|
|
├── tsconfig.json # TypeScript config (extends base)
|
|
├── vitest.config.ts # Testing framework config
|
|
├── vitest.setup.ts # Test setup
|
|
├── middleware.ts # Auth routing middleware
|
|
├── sentry.*.config.ts # Sentry error tracking (3 files)
|
|
├── instrumentation.ts # Server instrumentation
|
|
└── global.d.ts # Global TypeScript definitions
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 Package.json Dependencies
|
|
|
|
### Production Dependencies:
|
|
```json
|
|
{
|
|
"@hookform/resolvers": "^5.2.2", // Form validation resolver
|
|
"@sentry/nextjs": "^10.47.0", // Error tracking
|
|
"@tanstack/react-query": "^5.96.2", // Data fetching & caching
|
|
"class-variance-authority": "^0.7.1", // Component variant utilities
|
|
"clsx": "^2.1.1", // Class name utility
|
|
"lucide-react": "^1.7.0", // Icon library
|
|
"mapbox-gl": "^3.21.0", // Map library
|
|
"next": "^14.2.0", // Framework
|
|
"react": "^18.3.0",
|
|
"react-dom": "^18.3.0",
|
|
"react-hook-form": "^7.72.1", // Form state management
|
|
"recharts": "^3.8.1", // Chart library
|
|
"tailwind-merge": "^3.5.0", // Merge Tailwind conflicts
|
|
"zod": "^4.3.6", // Schema validation
|
|
"zustand": "^5.0.12" // Lightweight state management
|
|
}
|
|
```
|
|
|
|
### Dev Dependencies (including testing):
|
|
```json
|
|
{
|
|
"@testing-library/jest-dom": "^6.9.1",
|
|
"@testing-library/react": "^16.3.2",
|
|
"@testing-library/user-event": "^14.6.1",
|
|
"@vitejs/plugin-react": "^4.7.0",
|
|
"vitest": "^4.1.3",
|
|
"tailwindcss": "^3.4.0",
|
|
"tailwindcss-animate": "^1.0.7",
|
|
"msw": "^2.13.2", // Mock Service Worker
|
|
"typescript": "^6.0.2"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Root Layout (app/layout.tsx)
|
|
|
|
### Current Implementation:
|
|
- **HTML language:** `lang="vi"` (Vietnamese hardcoded)
|
|
- **Metadata structure:** Vietnamese title & description
|
|
- **OpenGraph:** Locale set to `vi_VN`
|
|
- **Providers stacked:** `ThemeProvider → QueryProvider → AuthProvider`
|
|
- **Accessibility:** Includes skip-to-main-content link (already A11y compliant)
|
|
- **Theme color:** `#15803d` (primary green)
|
|
|
|
### Current Metadata:
|
|
```javascript
|
|
title: 'GoodGo — Nền tảng Bất động sản Việt Nam'
|
|
description: 'GoodGo — nền tảng bất động sản thông minh tại Việt Nam...'
|
|
openGraph: { locale: 'vi_VN', ... }
|
|
```
|
|
|
|
---
|
|
|
|
## 🔐 Middleware (middleware.ts)
|
|
|
|
### Current Auth Routing:
|
|
```typescript
|
|
- Public paths: /login, /register, /search, /auth/callback, / (root)
|
|
- Protected paths: Anything else requires 'goodgo_authenticated' cookie
|
|
- Auth-only paths: /login, /register (redirects to /dashboard if authenticated)
|
|
- Redirect param: Adds ?redirect=[original-path] on unauthorized access
|
|
```
|
|
|
|
**Key Entry Points to Update for i18n:**
|
|
- Locale prefix detection needed (e.g., `/en/dashboard`, `/vi/dashboard`)
|
|
- Cookie/header locale detection
|
|
|
|
---
|
|
|
|
## 🎨 Tailwind Configuration
|
|
|
|
### Theme Setup (tailwind.config.ts):
|
|
```typescript
|
|
- Dark mode: 'class' based
|
|
- Content paths: ./app/**, ./components/**, ./lib/**
|
|
- Colors: HSL-based CSS variables (--primary, --secondary, etc.)
|
|
- Border radius: Customizable via --radius CSS variable
|
|
- Animation plugin: tailwindcss-animate
|
|
```
|
|
|
|
### Global Styles (app/globals.css):
|
|
- **CSS Variables:** Light mode + dark mode color schemes
|
|
- **Primary color:** HSL(142.1, 76.2%, 36.3%) — green
|
|
- **All components:** Use @apply border-border for consistency
|
|
- **Root background:** HSL variables applied
|
|
|
|
---
|
|
|
|
## 🗣️ Text Content & i18n Points
|
|
|
|
### Hardcoded Vietnamese Text Locations:
|
|
|
|
#### Layout & Navigation:
|
|
- `app/(public)/layout.tsx` — Header nav: "Trang chủ", "Tìm kiếm", "Đăng nhập", "Đăng ký"
|
|
- `app/(dashboard)/layout.tsx` — Dashboard nav items (8 items + theme toggle label)
|
|
- Footer in public layout — Section headings, links
|
|
|
|
#### Pages:
|
|
- `app/(public)/page.tsx` — Landing page (hero, search bar, districts, stats, CTA)
|
|
- `app/(auth)/login/page.tsx` — Form labels, error messages (OAUTH_ERROR_MESSAGES object)
|
|
- `app/(auth)/register/page.tsx` — Similar form structure
|
|
|
|
#### Components:
|
|
- `components/search/filter-bar.tsx` — Filter labels (PRICE_RANGES), city names
|
|
- `components/search/property-card.tsx` — Property info badges, direction labels
|
|
- `components/listings/listing-form-steps.tsx` — Form labels, validation messages
|
|
- `components/ui/label.tsx` — Form labels across app
|
|
|
|
#### API Error Messages & Zod Validation:
|
|
- `lib/validations/listings.ts` — Zod error messages (Vietnamese)
|
|
- `lib/validations/auth.ts` — Auth validation messages
|
|
- `components/auth/oauth-buttons.tsx` — Button text ("Google", "Zalo")
|
|
|
|
---
|
|
|
|
## 🧩 Key Components Requiring Translation
|
|
|
|
### Forms (Form validation + labels):
|
|
1. **Login Form** (`app/(auth)/login/page.tsx`)
|
|
- Phone input label, password label, errors
|
|
- OAuth button labels
|
|
- Link text: "Chưa có tài khoản? Đăng ký"
|
|
|
|
2. **Register Form** (`app/(auth)/register/page.tsx`)
|
|
- Similar structure to login
|
|
|
|
3. **Listing Creation** (`components/listings/listing-form-steps.tsx`)
|
|
- Multi-step form with labels for:
|
|
- Transaction type (Bán/Cho thuê)
|
|
- Property type (Căn hộ/Nhà riêng/etc)
|
|
- Location (address, ward, district, city)
|
|
- Details (area, bedrooms, bathrooms, direction)
|
|
- Pricing
|
|
|
|
4. **Search Filter** (`components/search/filter-bar.tsx`)
|
|
- Transaction/Property/Price/Area selects
|
|
- City options (13 Vietnamese cities)
|
|
|
|
### UI Components:
|
|
- **Buttons:** Text labels ("Đăng nhập", "Tìm kiếm", "Gửi", etc.)
|
|
- **Badge:** Labels for property types, statuses, directions
|
|
- **Input labels:** Across all forms
|
|
- **Error messages:** Alert text
|
|
|
|
### Navigation:
|
|
- **Public header:** 4 main nav items + user menu
|
|
- **Dashboard nav:** 8 main sections + theme toggle
|
|
- **Footer:** 4 columns of links + copyright
|
|
|
|
---
|
|
|
|
## ♿ Accessibility (Current State - WCAG 2.1 AA)
|
|
|
|
### Already Implemented ✅:
|
|
- Skip-to-main-content link (hidden, appears on focus)
|
|
- Semantic HTML: `<header>`, `<nav>`, `<main>`, `<footer>`
|
|
- `aria-label` on navigation items
|
|
- `aria-label` on property cards (for screen readers)
|
|
- `role="alert"` on error messages
|
|
- `aria-invalid` on form inputs
|
|
- Form labels linked with `htmlFor`
|
|
- Image alt text on property images
|
|
- `aria-hidden="true"` on decorative elements
|
|
|
|
### Accessibility Gaps to Fix 🔧:
|
|
1. **Color contrast:** Need to verify against WCAG AA standards
|
|
2. **Focus indicators:** Ensure visible focus states on all interactive elements
|
|
3. **Dialog/Modal:** Need proper focus management in dialogs
|
|
4. **Forms:** Ensure field grouping with `<fieldset>` where applicable
|
|
5. **Error handling:** Some error messages lack clear labels
|
|
6. **Loading states:** Spinner needs `aria-busy` or `aria-label`
|
|
7. **Tables:** Data tables need proper headers (`<th>`, `scope`)
|
|
8. **Links:** "Xem tất cả" links should have context or aria-labels
|
|
9. **Icon-only buttons:** Need proper `aria-label`
|
|
10. **Text alternatives:** Ensure all meaningful icons have descriptive labels
|
|
|
|
### ARIA Implementation Points:
|
|
- Dropdown navigation (if complex)
|
|
- Tab interfaces (recharts/charts)
|
|
- File upload components
|
|
- Date/time inputs (if added)
|
|
|
|
---
|
|
|
|
## 🔗 Current Locale Setup
|
|
|
|
### Status: **NO EXISTING i18n**
|
|
- No `next-intl` package
|
|
- No translation files (JSON/YAML)
|
|
- No locale routes (`/en/*`, `/vi/*`)
|
|
- No i18n middleware
|
|
- **Language is hardcoded to Vietnamese everywhere**
|
|
|
|
### Where i18n Will Be Integrated:
|
|
1. **Middleware:** Detect locale from URL, cookie, or `Accept-Language` header
|
|
2. **Layout wrapper:** `[locale]/layout.tsx` folder structure
|
|
3. **Message providers:** `next-intl` Provider in root layout
|
|
4. **API responses:** May need to internationalize error messages from backend
|
|
|
|
---
|
|
|
|
## 🔒 Security Configuration
|
|
|
|
### Next.js Config Security Headers:
|
|
- `X-Content-Type-Options: nosniff`
|
|
- `X-Frame-Options: DENY`
|
|
- `X-XSS-Protection: 1; mode=block`
|
|
- `Content-Security-Policy` with Mapbox domains whitelisted
|
|
- `Permissions-Policy` restricting camera/microphone/geolocation
|
|
|
|
### Auth Middleware:
|
|
- Cookie-based auth check (`goodgo_authenticated`)
|
|
- Protected routes redirect to `/login?redirect=...`
|
|
- Public route protection in middleware
|
|
|
|
---
|
|
|
|
## 📊 Key Data Structures & Enums
|
|
|
|
### Transaction Types:
|
|
```typescript
|
|
const TRANSACTION_TYPES = [
|
|
{ value: 'SALE', label: 'Bán' },
|
|
{ value: 'RENT', label: 'Cho thuê' },
|
|
];
|
|
```
|
|
|
|
### Property Types:
|
|
```typescript
|
|
const PROPERTY_TYPES = [
|
|
{ value: 'APARTMENT', label: 'Căn hộ' },
|
|
{ value: 'HOUSE', label: 'Nhà riêng' },
|
|
{ value: 'VILLA', label: 'Biệt thự' },
|
|
{ value: 'LAND', label: 'Đất nền' },
|
|
{ value: 'OFFICE', label: 'Văn phòng' },
|
|
{ value: 'SHOPHOUSE', label: 'Shophouse' },
|
|
];
|
|
```
|
|
|
|
### Listing Statuses:
|
|
```typescript
|
|
const LISTING_STATUSES = {
|
|
DRAFT, PENDING_REVIEW, ACTIVE, RESERVED, SOLD, RENTED, EXPIRED, REJECTED
|
|
};
|
|
```
|
|
|
|
### Directions:
|
|
```typescript
|
|
const DIRECTIONS = [
|
|
{ value: 'NORTH', label: 'Bắc' },
|
|
{ value: 'SOUTH', label: 'Nam' },
|
|
{ value: 'EAST', label: 'Đông' },
|
|
{ value: 'WEST', label: 'Tây' },
|
|
// ... and diagonal combinations
|
|
];
|
|
```
|
|
|
|
### Cities (13 total):
|
|
```typescript
|
|
Hồ Chí Minh, Hà Nội, Đà Nẵng, Nha Trang, Cần Thơ, Hải Phòng,
|
|
Bình Dương, Đồng Nai, Long An, Bà Rịa - Vũng Tàu, [+ more]
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Testing Setup
|
|
|
|
### Test Framework: Vitest + React Testing Library
|
|
- **Config file:** `vitest.config.ts`
|
|
- **Setup file:** `vitest.setup.ts`
|
|
- **Test files:** Located alongside source (`__tests__` folders)
|
|
|
|
### Current Test Coverage:
|
|
- Component tests for UI library
|
|
- Auth store tests
|
|
- Validation schema tests
|
|
- Utility function tests
|
|
|
|
### Testing Best Practices for i18n:
|
|
- Mock i18n provider in test setup
|
|
- Test both locale variants
|
|
- Verify translations render correctly
|
|
|
|
---
|
|
|
|
## 🚀 Implementation Readiness
|
|
|
|
### Ready for i18n Implementation:
|
|
✅ Centralized validation messages (Zod schemas)
|
|
✅ Enum/constant-based UI text (TRANSACTION_TYPES, PROPERTY_TYPES, etc.)
|
|
✅ Component library with consistent patterns
|
|
✅ TypeScript for type safety
|
|
✅ Middleware support for locale routing
|
|
|
|
### Minor Refactoring Needed:
|
|
⚠️ Extract some hardcoded strings from components
|
|
⚠️ Move form error messages to message files
|
|
⚠️ Centralize page metadata for i18n
|
|
|
|
---
|
|
|
|
## 📝 Summary: i18n & A11y Implementation Points
|
|
|
|
| Area | Current State | Needs Work |
|
|
|------|---------------|-----------|
|
|
| **Locale Support** | Hardcoded to Vietnamese | Implement next-intl with routing |
|
|
| **Translation Keys** | Scattered throughout code | Centralize in message files |
|
|
| **Validation Messages** | In Zod schemas (Vietnamese) | Extract to i18n messages |
|
|
| **Component Text** | Hardcoded strings | Use i18n hook |
|
|
| **Metadata/SEO** | Hardcoded Vietnamese | Generate for each locale |
|
|
| **Color Contrast** | Likely AA compliant | Audit and verify |
|
|
| **Focus Management** | Partial (buttons/links ok) | Add to modals & dropdowns |
|
|
| **ARIA Labels** | Good coverage | Complete missing labels |
|
|
| **Error Messages** | Most have aria-invalid | Add more context to some |
|
|
| **Loading States** | Spinner exists | Add aria-busy, better labels |
|
|
| **Tables** | Basic structure | Add proper header semantics |
|
|
|
|
---
|
|
|
|
## 🗂️ File Count Summary
|
|
|
|
- **App routes:** ~15 page files
|
|
- **Components:** ~35 component files
|
|
- **Lib utilities:** ~20 files (hooks, APIs, validations)
|
|
- **Tests:** ~15 test files
|
|
- **Config files:** ~8 configuration files
|
|
- **Total TypeScript/TSX files:** ~90+
|
|
|
|
---
|
|
|
|
## Next Steps for Implementation
|
|
|
|
1. **Install i18n:** Add `next-intl` to dependencies
|
|
2. **Create message files:** Set up `messages/en.json` and `messages/vi.json`
|
|
3. **Refactor middleware:** Add locale detection & routing
|
|
4. **Update root layout:** Wrap with i18n provider
|
|
5. **Update all components:** Replace hardcoded strings with `useTranslations()`
|
|
6. **Test both locales:** Ensure all pages render correctly
|
|
7. **A11y audit:** Use axe DevTools to identify remaining issues
|
|
8. **Focus management:** Add focus trapping in modals
|
|
9. **Testing:** Update test setup for i18n mocking
|
|
|
|
---
|
|
|
|
**Report Generated:** April 9, 2026
|
|
**Exploration Scope:** Thorough
|
|
**Confidence:** High
|