# 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