chore: organize docs — move 37 files from root into docs/ subfolders

Root now contains only essential files: README.md, CLAUDE.md, CHANGELOG.md, CONTRIBUTING.md Reorganized into: docs/audits/ — all audit reports & checklists (71 files) docs/architecture/ — codebase overview, implementation plan docs/guides/ — auth guide, implementation checklist docs/load-testing/ — k6 load test guides & endpoints docs/security/ — payment & security reviews Also removed 5 untracked debug/investigation files and cleaned up playwright-report/ & test-results/ artifacts. Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
2026-04-13 12:09:14 +07:00
parent ccfc176e40
commit b93c28fa01
38 changed files with 252 additions and 412 deletions
--- a/docs/architecture/CODEBASE_OVERVIEW.md
+++ b/docs/architecture/CODEBASE_OVERVIEW.md
@@ -0,0 +1,412 @@
+# GoodGo Platform — Comprehensive Codebase Overview
+
+**Generated:** April 12, 2026  
+**Project Status:** MVP Complete — Phase 7 Wave 14 ✅ Build Green
+
+---
+
+## 1. TOP-LEVEL DIRECTORY STRUCTURE
+
+```
+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. API MODULES (`apps/api/src/modules/`) — 18 MODULES
+
+### Core Authentication & Authorization
+- **auth/** — JWT, OAuth (Google/Zalo), MFA, TOTP backup codes
+  - Subdirs: application, domain, infrastructure, presentation, __tests__
+  - Key: JWT guards, passport strategies, role-based access
+
+### Listings & Properties
+- **listings/** — CRUD, status management, media, AI price estimates
+  - Moderation scoring, featured listings, expiration logic
+  - Media upload with pre-signed URLs (AWS S3)
+
+### Search & Discovery
+- **search/** — Typesense integration (full-text), geospatial (PostGIS)
+  - Resilient repository with fallback to PostgreSQL
+  - Filters: location, price, property type, bedrooms
+
+### Transactions & Inquiries
+- **inquiries/** — Buyer-to-seller messages for specific listings
+- **leads/** — Agent CRM (lead scoring, status tracking, notes)
+
+### Monetization
+- **payments/** — VNPay, MoMo, ZaloPay, Bank Transfer
+  - Idempotency keys, webhook callbacks, refund handling
+  - 4 payment types: subscription, listing fee, deposit, featured
+
+- **subscriptions/** — Plans (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
+  - Usage tracking, quota management, billing cycles
+
+### Operations
+- **agents/** — Agent profiles, quality scores, service areas, verification
+- **admin/** — User bans, KYC approval, listing moderation, audit logs
+- **notifications/** — Email, SMS, Push (FCM), Zalo OA
+  - Preferences per user/channel, template system
+
+### Analytics & Intelligence
+- **analytics/** — Market reports, price index by district/city/type
+  - Valuation engine integration (AI/ML service)
+
+### Infrastructure & System
+- **health/** — Liveness/readiness probes, Kubernetes hooks
+- **metrics/** — Prometheus metrics, HTTP latency, error rates
+- **mcp/** — Model Context Protocol server for AI tools
+- **shared/** — Domain primitives, encryption, logging, error handling
+
+**Code Metrics:**
+- ~845 TypeScript files
+- Layered DDD architecture: presentation → application → domain → infrastructure
+- Uses NestJS modules, CQRS pattern for complex operations
+
+---
+
+## 3. FRONTEND STRUCTURE (`apps/web/`)
+
+### Root Layout
+- **app/layout.tsx** — Root wrapper
+- **app/[locale]/** — i18n routing (Vietnamese + English)
+
+### Page Groups (Route Groups with Shared Layouts)
+- **(public)/** — Landing, listings, search (no auth required)
+- **(auth)/** — Login, register, OAuth callbacks
+- **(dashboard)/** — Seller/agent dashboard
+- **(admin)/** — Admin moderation, KYC review, user management
+
+### 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/`)
+- Vietnamese & English message files
+- next-intl integration
+
+**Frontend Metrics:**
+- ~245 TypeScript/TSX files
+- Built on: Next.js 15, React 18, Tailwind CSS, Shadcn/ui
+- State: Zustand + React Query
+- Forms: React Hook Form + Zod validation
+
+---
+
+## 4. PRISMA SCHEMA — DATA MODEL
+
+**Database:** PostgreSQL 16 + PostGIS extension
+
+### Total Models: 31
+
+#### Authentication (5)
+| Model | Purpose |
+|-------|---------|
+| User | Main user profile + KYC status, MFA fields |
+| RefreshToken | JWT refresh token chain management |
+| OAuthAccount | Google/Zalo OAuth linkage |
+| Agent | Seller/Agent extended profile |
+| MfaChallenge | TOTP/backup code verification tracking |
+
+#### Listings & Properties (4)
+| Model | Purpose |
+|-------|---------|
+| Property | Physical property details + geolocation |
+| PropertyMedia | Images/videos per property |
+| Listing | Listing instance (sale/rent) + status |
+| SavedSearch | User's saved search preferences |
+
+#### Transactions (4)
+| Model | Purpose |
+|-------|---------|
+| Transaction | Buyer-seller transaction flow (inquiry → completed) |
+| Inquiry | Buyer questions on specific listings |
+| Lead | Agent CRM lead records |
+| Review | User reviews of agents/transactions |
+
+#### Payments (2)
+| Model | Purpose |
+|-------|---------|
+| Payment | Payment records (all providers) |
+| Plan | Subscription tier definitions |
+
+#### Orders & Escrow (3)
+| Model | Purpose |
+|-------|---------|
+| Order | Auction settlement order |
+| Escrow | Escrow holding for transactions |
+| Subscription | User's active subscription |
+
+#### Analytics (2)
+| Model | Purpose |
+|-------|---------|
+| Valuation | AI-generated property valuations |
+| MarketIndex | Market statistics per district/city |
+
+#### Operations (6)
+| Model | Purpose |
+|-------|---------|
+| NotificationLog | Sent notification records |
+| NotificationPreference | User notification opt-in/out |
+| AdminAuditLog | Admin action audit trail |
+| UsageRecord | Subscription usage tracking |
+
+**Index Strategy:**
+- Single-column indexes on foreign keys, status fields, dates
+- Compound indexes for common query patterns (e.g., `[role, isActive, createdAt DESC]`)
+- GIST index on PostGIS location geometry
+
+**Key Enums:**
+- 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. DOCUMENTATION & TRACKING
+
+### Root-Level Planning Docs
+- **PROJECT_TRACKER.md** — 7 phases, 40+ issues, current status (Phase 7 Wave 14)
+- **IMPLEMENTATION_PLAN.md** — Feature roadmap with priority/status
+- **COMPREHENSIVE_AUDIT_2026-04-12.md** — Full system audit with implementation notes
+
+### Technical Docs (`docs/`)
+- **architecture.md** — DDD layering, CQRS, module boundaries
+- **api-endpoints.md** — Swagger-generated endpoint reference
+- **api-error-codes.md** — Structured error code taxonomy
+- **deployment.md** — Docker, K8s, CI/CD pipeline steps
+- **RUNBOOK.md** — Operational procedures, troubleshooting
+- **PRODUCTION_READINESS.md** — Security, compliance, performance checklist
+
+### Audit Directory (`docs/audits/`)
+- 80+ audit files documenting feature implementations
+- Pricing audit, checkout flow, KYC, payment gateway testing
+
+---
+
+## 6. DEPENDENCIES & TOOLING
+
+### Monorepo Setup
+- **pnpm** v10.27.0 (workspace) — faster, strict peer deps
+- **Turbo** v2.9.4 — task orchestration & caching
+- **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 & Quality
+```
+Test: vitest ^4.1.3, @playwright/test ^1.59
+Lint: eslint ^9.39, prettier ^3.8, typescript-eslint
+Dependencies: dependency-cruiser (architecture validation)
+```
+
+---
+
+## 7. TEST COVERAGE & QUALITY
+
+### Test Files: 242 total
+
+#### API Tests
+- **Unit tests:** Payment gateways (VNPay, MoMo, ZaloPay), Money value objects, Platform fee logic
+- **Integration tests:** Auth flows, health checks, notifications
+- Located in `__tests__` subdirs within each module
+
+#### Frontend Tests
+- **Unit tests:** Auth store, comparison store, currency formatting, validations
+- **E2E tests (Playwright):** 15+ web tests, 16+ API tests
+
+#### E2E Test Coverage
+**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):**
+- Baseline benchmarks for search, listings, auth endpoints
+- Concurrency testing up to 1000 virtual users
+
+---
+
+## 8. IMPLEMENTATION STATUS
+
+### ✅ COMPLETE (Phase 7 MVP)
+1. **Foundation** — Monorepo, Docker, Prisma schema, CI/CD
+2. **Auth** — JWT, OAuth, MFA/TOTP, session management
+3. **Listings** — Full CRUD, media upload, status workflow
+4. **Search** — Typesense + PostGIS geo-search
+5. **Payments** — 3 VN payment gateways, webhook handling
+6. **Subscriptions** — 4 tiers, quota tracking
+7. **Notifications** — Email, SMS, Push, Zalo OA
+8. **Admin Panel** — Moderation, user management, audit logs
+9. **Agents** — Portal, inquiries, lead CRM, quality metrics
+10. **Analytics** — Market reports, AI valuation service
+11. **Security** — Rate limiting, CSRF, field encryption, PII masking
+12. **Monitoring** — Prometheus, Grafana, Sentry, log aggregation
+13. **Testing** — Unit tests, E2E tests (Playwright), load tests (K6)
+
+### 🔄 IN PROGRESS / REMAINING
+- Per Wave 14:
+  - TEC-1650: Listing detail non-existent ID error handling
+  - TEC-1652: Full E2E test suite validation
+  - TEC-1657: Comprehensive audit logging
+
+### Database Migrations
+- 7+ migrations applied
+- Connection pooling (PgBouncer)
+- PostGIS extension enabled
+
+---
+
+## 9. PROJECT MATURITY INDICATORS
+
+| Dimension | Status | Evidence |
+|-----------|--------|----------|
+| **Architecture** | Production-Ready | DDD, CQRS, layered modules, clear boundaries |
+| **Code Quality** | High | 242 tests, ESLint enforcement, module cruiser |
+| **Security** | Hardened | JWT, MFA, encryption, rate limiting, CSRF, PII masking |
+| **Documentation** | Comprehensive | 80+ audit files, runbooks, error codes, architecture |
+| **Performance** | Optimized | Redis caching, Typesense search, query optimization, load tests |
+| **Monitoring** | Complete | Prometheus, Grafana, Sentry, structured logging |
+| **DevOps** | Mature | Docker, Kubernetes config, CI/CD pipelines, smoke tests |
+| **Scaling** | Prepared | Connection pooling, caching layer, resilient services |
+
+---
+
+## 10. KEY STATISTICS
+
+```
+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. TECH STACK SUMMARY
+
+| Layer | Technology |
+|-------|-----------|
+| **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 (Vietnamese + English) |
+
+---
+
+## 12. NEXT STEPS FOR DEVELOPERS
+
+1. **Local Setup:** `docker-compose up` → database + API + frontend
+2. **Run Tests:** `pnpm test` (unit), `pnpm test:e2e` (E2E)
+3. **Check Status:** Review PROJECT_TRACKER.md for ongoing issues
+4. **Architecture:** Read docs/architecture.md for module boundaries
+5. **API:** Browse docs/api-endpoints.md (Swagger-generated)
+6. **Deploy:** Follow docs/deployment.md for production setup
+