# Nền tảng GoodGo — Tổng quan toàn diện về Codebase

**Được tạo:** Ngày 12 tháng 4 năm 2026  
**Trạng thái dự án:** MVP hoàn thành — Phase 7 Wave 14 ✅ Build Green

---

## 1. CẤU TRÚC THƯ MỤC CẤP CAO NHẤT

```
goodgo-platform-ai/
├── apps/                          # Monorepo applications
│   ├── api/                       # NestJS backend
│   └── web/                       # Next.js frontend
├── libs/                          # Shared libraries
│   ├── mcp-servers/              # MCP server implementations
│   └── ai-services/              # AI/ML services (Python FastAPI)
├── prisma/                        # Database schema & migrations
│   ├── schema.prisma             # Complete data model
│   └── migrations/               # 7+ migration files
├── docs/                          # Technical documentation
├── e2e/                          # End-to-end tests (Playwright)
├── monitoring/                    # Observability stack
│   ├── grafana/                  # Dashboards
│   ├── loki/                     # Log aggregation
│   ├── alertmanager/             # Alerts
│   └── promtail/                 # Log forwarding
├── load-tests/                   # K6 performance tests
├── scripts/                      # DevOps & automation
├── infra/                        # Infrastructure config
│   └── pgbouncer/               # DB connection pooling
├── .github/workflows/            # CI/CD pipelines
├── docker-compose.yml            # Local development
├── docker-compose.prod.yml       # Production stack
├── PROJECT_TRACKER.md            # Issue & phase tracking
├── IMPLEMENTATION_PLAN.md        # Feature roadmap
└── package.json                  # Monorepo config (pnpm workspaces)
```

---

## 2. CÁC MODULE API (`apps/api/src/modules/`) — 18 MODULE

### Xác thực & Phân quyền cốt lõi
- **auth/** — JWT, OAuth (Google/Zalo), MFA, mã dự phòng TOTP
  - Thư mục con: application, domain, infrastructure, presentation, __tests__
  - Chính: JWT guards, passport strategies, phân quyền dựa trên vai trò

### Listings & Bất động sản
- **listings/** — CRUD, quản lý trạng thái, media, AI ước tính giá
  - Chấm điểm kiểm duyệt, listing nổi bật, logic hết hạn
  - Upload media với pre-signed URL (AWS S3)

### Search & Khám phá
- **search/** — Tích hợp Typesense (full-text), geospatial (PostGIS)
  - Repository có khả năng phục hồi với fallback về PostgreSQL
  - Bộ lọc: vị trí, giá, loại bất động sản, số phòng ngủ

### Giao dịch & Inquiry
- **inquiries/** — Tin nhắn người mua-người bán cho listing cụ thể
- **leads/** — CRM dành cho agent (chấm điểm lead, theo dõi trạng thái, ghi chú)

### Kiếm tiền
- **payments/** — VNPay, MoMo, ZaloPay, Chuyển khoản ngân hàng
  - Khóa idempotency, webhook callback, xử lý hoàn tiền
  - 4 loại thanh toán: subscription, phí listing, đặt cọc, nổi bật

- **subscriptions/** — Các gói (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
  - Theo dõi sử dụng, quản lý hạn ngạch, chu kỳ thanh toán

### Vận hành
- **agents/** — Hồ sơ agent, điểm chất lượng, khu vực phục vụ, xác minh
- **admin/** — Cấm người dùng, duyệt KYC, kiểm duyệt listing, audit log
- **notifications/** — Email, SMS, Push (FCM), Zalo OA
  - Tùy chọn theo người dùng/kênh, hệ thống template

### Analytics & Trí tuệ
- **analytics/** — Báo cáo thị trường, chỉ số giá theo quận/thành phố/loại
  - Tích hợp engine định giá (dịch vụ AI/ML)

### Hạ tầng & Hệ thống
- **health/** — Probe liveness/readiness, hook Kubernetes
- **metrics/** — Metrics Prometheus, độ trễ HTTP, tỷ lệ lỗi
- **mcp/** — Model Context Protocol server cho công cụ AI
- **shared/** — Domain primitives, mã hóa, logging, xử lý lỗi

**Số liệu code:**
- ~845 file TypeScript
- Kiến trúc DDD phân lớp: presentation → application → domain → infrastructure
- Sử dụng module NestJS, pattern CQRS cho các thao tác phức tạp

---

## 3. CẤU TRÚC FRONTEND (`apps/web/`)

### Root Layout
- **app/layout.tsx** — Root wrapper
- **app/[locale]/** — Định tuyến i18n (Tiếng Việt + Tiếng Anh)

### Nhóm trang (Route Groups với Layout dùng chung)
- **(public)/** — Landing, listings, search (không yêu cầu xác thực)
- **(auth)/** — Login, register, OAuth callback
- **(dashboard)/** — Dashboard người bán/agent
- **(admin)/** — Kiểm duyệt admin, duyệt KYC, quản lý người dùng

### Components (`components/`)
```
├── agents/           — Agent profiles, cards
├── auth/             — Login forms, OAuth buttons
├── charts/           — Market analytics, performance graphs (Recharts)
├── comparison/       — Property comparison tool
├── inquiries/        — Message threads
├── leads/            — Lead management UI
├── listings/         — List, create, edit, detail views
├── map/              — Mapbox integration
├── search/           — Filters, saved searches
├── subscription/     — Plan selection, billing
├── valuation/        — AI price estimates
├── ui/               — Shadcn/ui components (button, card, modal, etc.)
└── providers/        — Context providers (auth, query, etc.)
```

### Libraries (`lib/`)
```
├── *-api.ts          — React Query API clients (6 main ones)
├── *-store.ts        — Zustand state stores (auth, comparison)
├── hooks/            — Custom React hooks (8 hooks)
├── validations/      — Zod schemas (listing, auth, search)
├── currency.ts       — VND formatting & exchange rates
├── image-blur.ts     — Blur hash for image placeholders
└── web-vitals.ts     — Core Web Vitals tracking
```

### i18n (`i18n/`)
- File messages tiếng Việt & tiếng Anh
- Tích hợp next-intl

**Số liệu Frontend:**
- ~245 file TypeScript/TSX
- Xây dựng trên: Next.js 15, React 18, Tailwind CSS, Shadcn/ui
- State: Zustand + React Query
- Forms: React Hook Form + validation Zod

---

## 4. PRISMA SCHEMA — MÔ HÌNH DỮ LIỆU

**Database:** PostgreSQL 16 + extension PostGIS

### Tổng số Model: 31

#### Xác thực (5)
| Model | Mục đích |
|-------|---------|
| User | Hồ sơ người dùng chính + trạng thái KYC, các trường MFA |
| RefreshToken | Quản lý chuỗi JWT refresh token |
| OAuthAccount | Liên kết OAuth Google/Zalo |
| Agent | Hồ sơ mở rộng cho người bán/Agent |
| MfaChallenge | Theo dõi xác minh TOTP/mã dự phòng |

#### Listings & Bất động sản (4)
| Model | Mục đích |
|-------|---------|
| Property | Chi tiết bất động sản vật lý + định vị địa lý |
| PropertyMedia | Hình ảnh/video cho mỗi bất động sản |
| Listing | Phiên bản listing (bán/cho thuê) + trạng thái |
| SavedSearch | Tùy chọn tìm kiếm đã lưu của người dùng |

#### Giao dịch (4)
| Model | Mục đích |
|-------|---------|
| Transaction | Luồng giao dịch người mua-người bán (inquiry → hoàn thành) |
| Inquiry | Câu hỏi người mua về listing cụ thể |
| Lead | Bản ghi lead CRM của agent |
| Review | Đánh giá người dùng về agent/giao dịch |

#### Thanh toán (2)
| Model | Mục đích |
|-------|---------|
| Payment | Bản ghi thanh toán (tất cả nhà cung cấp) |
| Plan | Định nghĩa cấp subscription |

#### Đơn hàng & Escrow (3)
| Model | Mục đích |
|-------|---------|
| Order | Lệnh thanh toán đấu giá |
| Escrow | Giữ ký quỹ cho giao dịch |
| Subscription | Subscription đang hoạt động của người dùng |

#### Analytics (2)
| Model | Mục đích |
|-------|---------|
| Valuation | Định giá bất động sản do AI tạo |
| MarketIndex | Thống kê thị trường theo quận/thành phố |

#### Vận hành (6)
| Model | Mục đích |
|-------|---------|
| NotificationLog | Bản ghi thông báo đã gửi |
| NotificationPreference | Tùy chọn nhận thông báo của người dùng |
| AdminAuditLog | Audit trail hành động admin |
| UsageRecord | Theo dõi sử dụng subscription |

**Chiến lược Index:**
- Index một cột trên foreign key, các trường trạng thái, ngày tháng
- Index ghép cho các pattern truy vấn phổ biến (ví dụ: `[role, isActive, createdAt DESC]`)
- Index GIST trên hình học vị trí PostGIS

**Các Enum chính:**
- UserRole: BUYER, SELLER, AGENT, ADMIN
- PropertyType: APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE
- TransactionType: SALE, RENT
- PaymentProvider: VNPAY, MOMO, ZALOPAY, BANK_TRANSFER
- PaymentStatus: PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED

---

## 5. TÀI LIỆU & THEO DÕI

### Tài liệu lập kế hoạch ở cấp Root
- **PROJECT_TRACKER.md** — 7 phase, 40+ issue, trạng thái hiện tại (Phase 7 Wave 14)
- **IMPLEMENTATION_PLAN.md** — Lộ trình tính năng với ưu tiên/trạng thái
- **COMPREHENSIVE_AUDIT_2026-04-12.md** — Audit toàn hệ thống với ghi chú triển khai

### Tài liệu kỹ thuật (`docs/`)
- **architecture.md** — Phân lớp DDD, CQRS, ranh giới module
- **api-endpoints.md** — Tham chiếu endpoint do Swagger tạo
- **api-error-codes.md** — Phân loại mã lỗi có cấu trúc
- **deployment.md** — Docker, K8s, các bước CI/CD
- **RUNBOOK.md** — Quy trình vận hành, xử lý sự cố
- **PRODUCTION_READINESS.md** — Checklist bảo mật, tuân thủ, hiệu năng

### Thư mục Audit (`docs/audits/`)
- 80+ file audit tài liệu hóa các triển khai tính năng
- Audit pricing, luồng checkout, KYC, test cổng thanh toán

---

## 6. PHỤ THUỘC & CÔNG CỤ

### Thiết lập Monorepo
- **pnpm** v10.27.0 (workspace) — nhanh hơn, peer deps nghiêm ngặt
- **Turbo** v2.9.4 — điều phối tác vụ & cache
- **Node** ≥22.0.0

### Backend (NestJS)
```
Core: @nestjs/core ^11.0, @nestjs/common ^11.0
DB: @prisma/client ^7.7, pg ^8.20
Auth: @nestjs/jwt, @nestjs/passport, passport-jwt, passport-google-oauth20
Cache: ioredis ^5.4
Search: typesense ^3.0.5
File Upload: @aws-sdk/client-s3, @aws-sdk/s3-request-presigner
Payments: (custom integrations for VNPay, MoMo, ZaloPay)
Monitoring: @sentry/nestjs, pino, prom-client
Email: nodemailer
2FA: otplib, qrcode
```

### Frontend (Next.js)
```
Core: next ^15.5, react ^18.3, react-dom ^18.3
Forms: react-hook-form ^7.72, @hookform/resolvers
Validation: zod ^4.3
State: zustand ^5.0, @tanstack/react-query ^5.96
UI: tailwindcss ^3.4, lucide-react ^1.7, recharts ^3.8
i18n: next-intl ^4.9
Maps: mapbox-gl ^3.21
Monitoring: @sentry/nextjs
```

### Testing & Chất lượng
```
Test: vitest ^4.1.3, @playwright/test ^1.59
Lint: eslint ^9.39, prettier ^3.8, typescript-eslint
Dependencies: dependency-cruiser (architecture validation)
```

---

## 7. ĐỘ BAO PHỦ TEST & CHẤT LƯỢNG

### Tổng số file Test: 242

#### API Tests
- **Unit tests:** Cổng thanh toán (VNPay, MoMo, ZaloPay), Money value objects, logic phí nền tảng
- **Integration tests:** Luồng auth, health check, notifications
- Nằm trong các thư mục con `__tests__` trong từng module

#### Frontend Tests
- **Unit tests:** Auth store, comparison store, định dạng tiền tệ, validation
- **E2E tests (Playwright):** 15+ web test, 16+ API test

#### Độ bao phủ E2E Test
**Web Tests (15):**
- auth-login, auth-register, auth-oauth-callback
- homepage, navigation, responsive
- create-listing, listing-detail
- search, analytics
- admin dashboard, KYC, moderation, users
- dashboard

**API Tests (16):**
- auth (login, register, profile, refresh, KYC)
- listings, listing media, moderation
- search
- payments, payment callbacks
- subscriptions
- inquiries
- mcp, admin

**Load Tests (K6):**
- Benchmark cơ sở cho các endpoint search, listings, auth
- Test đồng thời lên đến 1000 virtual users

---

## 8. TRẠNG THÁI TRIỂN KHAI

### ✅ HOÀN THÀNH (Phase 7 MVP)
1. **Foundation** — Monorepo, Docker, schema Prisma, CI/CD
2. **Auth** — JWT, OAuth, MFA/TOTP, quản lý phiên
3. **Listings** — CRUD đầy đủ, upload media, workflow trạng thái
4. **Search** — Typesense + tìm kiếm địa lý PostGIS
5. **Payments** — 3 cổng thanh toán VN, xử lý webhook
6. **Subscriptions** — 4 cấp, theo dõi quota
7. **Notifications** — Email, SMS, Push, Zalo OA
8. **Admin Panel** — Kiểm duyệt, quản lý người dùng, audit log
9. **Agents** — Portal, inquiries, lead CRM, chỉ số chất lượng
10. **Analytics** — Báo cáo thị trường, dịch vụ định giá AI
11. **Security** — Rate limiting, CSRF, mã hóa trường, che PII
12. **Monitoring** — Prometheus, Grafana, Sentry, tổng hợp log
13. **Testing** — Unit test, E2E test (Playwright), load test (K6)

### 🔄 ĐANG TIẾN HÀNH / CÒN LẠI
- Theo Wave 14:
  - TEC-1650: Xử lý lỗi ID không tồn tại trên trang chi tiết listing
  - TEC-1652: Xác thực bộ test E2E đầy đủ
  - TEC-1657: Audit logging toàn diện

### Migration Database
- 7+ migration đã được áp dụng
- Connection pooling (PgBouncer)
- Đã bật extension PostGIS

---

## 9. CHỈ SỐ TRƯỞNG THÀNH DỰ ÁN

| Khía cạnh | Trạng thái | Bằng chứng |
|-----------|--------|----------|
| **Kiến trúc** | Sẵn sàng Production | DDD, CQRS, các module phân lớp, ranh giới rõ ràng |
| **Chất lượng code** | Cao | 242 test, ESLint thực thi, module cruiser |
| **Bảo mật** | Đã được củng cố | JWT, MFA, mã hóa, rate limiting, CSRF, che PII |
| **Tài liệu** | Toàn diện | 80+ file audit, runbook, mã lỗi, kiến trúc |
| **Hiệu năng** | Đã tối ưu | Cache Redis, tìm kiếm Typesense, tối ưu truy vấn, load test |
| **Monitoring** | Hoàn chỉnh | Prometheus, Grafana, Sentry, structured logging |
| **DevOps** | Trưởng thành | Docker, cấu hình Kubernetes, pipeline CI/CD, smoke test |
| **Khả năng mở rộng** | Đã chuẩn bị | Connection pooling, lớp cache, dịch vụ có khả năng phục hồi |

---

## 10. THỐNG KÊ CHÍNH

```
Backend Files:       ~845 TypeScript files
Frontend Files:      ~245 TypeScript/TSX files
Total Test Files:    242 (unit + E2E + load)
API Modules:         18 feature modules + 1 shared
Database Models:     31 (fully normalized)
Migrations:          7+ applied to PostgreSQL 16
API Endpoints:       100+ documented
E2E Test Cases:      31 (web + API)
Load Test Scenarios: 5+ K6 scripts
Documentation:       80+ audit files + runbooks
Lines of Code:       ~50,000+ (excluding node_modules)
```

---

## 11. TÓM TẮT TECH STACK

| Lớp | Công nghệ |
|-------|-----------|
| **Frontend** | Next.js 15, React 18, Tailwind CSS, Shadcn/ui |
| **Backend** | NestJS 11, TypeScript 6 |
| **Database** | PostgreSQL 16 + PostGIS |
| **Cache** | Redis (ioredis) |
| **Search** | Typesense 3.0 |
| **File Storage** | AWS S3 |
| **Payments** | VNPay, MoMo, ZaloPay |
| **Auth** | JWT + OAuth2 (Google, Zalo) |
| **Notifications** | Email (Nodemailer), SMS, FCM, Zalo OA |
| **Monitoring** | Prometheus, Grafana, Sentry |
| **Logs** | Pino + Loki |
| **Testing** | Playwright (E2E), Vitest (unit), K6 (load) |
| **Package Manager** | pnpm 10.27 |
| **Orchestration** | Turbo |
| **Containerization** | Docker + Docker Compose |
| **i18n** | next-intl (Tiếng Việt + Tiếng Anh) |

---

## 12. CÁC BƯỚC TIẾP THEO CHO LẬP TRÌNH VIÊN

1. **Thiết lập cục bộ:** `docker-compose up` → database + API + frontend
2. **Chạy Test:** `pnpm test` (unit), `pnpm test:e2e` (E2E)
3. **Kiểm tra trạng thái:** Xem PROJECT_TRACKER.md để biết các issue đang diễn ra
4. **Kiến trúc:** Đọc docs/architecture.md để biết ranh giới module
5. **API:** Duyệt docs/api-endpoints.md (do Swagger tạo)
6. **Deploy:** Theo dõi docs/deployment.md để thiết lập production