goodgo-platform/docs/architecture/CODEBASE_OVERVIEW.md

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