GoodGo Platform AI

Vietnam's intelligent real estate platform — property search, AI-powered valuation, and end-to-end transaction management.

Tech Stack

Layer	Technology
Backend	NestJS 11, TypeScript, Prisma ORM, CQRS
Frontend	Next.js 15, React 18, Tailwind CSS, Zustand
Database	PostgreSQL 16 + PostGIS 3.4
Search	Typesense 27
Cache/Queue	Redis 7
AI/ML	FastAPI, XGBoost, Claude API, Underthesea
MCP	Model Context Protocol servers (property search, valuation, analytics)
Storage	MinIO (S3-compatible)
Monitoring	Prometheus, Grafana, Loki + Promtail
Payments	VNPay, MoMo, ZaloPay

Architecture Overview

┌─────────────┐     ┌──────────────┐     ┌──────────────────┐
│  Next.js 15 │────▶│  NestJS API  │────▶│  PostgreSQL +    │
│  (Web App)  │     │  (REST)      │     │  PostGIS         │
└─────────────┘     └──────┬───────┘     └──────────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────▼──┐  ┌──────▼───┐  ┌────▼─────┐
        │ Redis  │  │Typesense │  │  MinIO   │
        │ Cache  │  │ Search   │  │ Storage  │
        └────────┘  └──────────┘  └──────────┘
              │
        ┌─────▼──────────────────────────┐
        │  MCP Servers                   │
        │  ├─ Property Search            │
        │  ├─ Market Analytics           │
        │  └─ Valuation                  │
        └─────────────┬─────────────────┘
                      │
              ┌───────▼────────┐
              │  AI Services   │
              │  (FastAPI)     │
              │  ├─ AVM        │
              │  └─ Moderation │
              └────────────────┘

Monorepo Structure

goodgo-platform-ai/
├── apps/
│   ├── api/              # NestJS backend (port 3001)
│   └── web/              # Next.js frontend (port 3000)
├── libs/
│   ├── ai-services/      # Python FastAPI — AVM + content moderation
│   └── mcp-servers/      # MCP server implementations
├── prisma/               # Database schema & migrations
├── e2e/                  # Playwright E2E tests (API + Web)
├── monitoring/           # Prometheus, Grafana, Loki & Promtail configs
├── scripts/              # Backup, restore & utility scripts
└── docs/                 # Developer documentation

Quick Start

Prerequisites

• Docker Engine 24+ & Docker Compose v2
• Node.js 22 LTS
• pnpm 10.27+ (corepack enable && corepack prepare pnpm@latest --activate)

Setup

# 1. Clone the repository
git clone <repo-url> && cd goodgo-platform-ai

# 2. Copy environment file
cp .env.example .env

# 3. Start infrastructure services
docker compose up -d

# 4. Verify services are healthy
docker compose ps

# 5. Install dependencies
pnpm install

# 6. Generate Prisma client
pnpm db:generate

# 7. Run database migrations
pnpm db:migrate:dev

# 8. Seed the database (optional)
pnpm db:seed

# 9. Start all apps in dev mode
pnpm dev

The API will be available at http://localhost:3001/api/v1 and the web app at http://localhost:3000.

Swagger UI: Open http://localhost:3001/api/v1/docs for interactive API documentation.

Infrastructure Services

Service	Port(s)	Dashboard
PostgreSQL + PostGIS	5432	—
Redis	6379	—
Typesense	8108	http://localhost:8108/health
MinIO	9000 / 9001	http://localhost:9001 (console)
AI Services (FastAPI)	8000	http://localhost:8000/health
Loki (log aggregation)	3100	http://localhost:3100/ready
Prometheus	9090	http://localhost:9090
Grafana	3002	http://localhost:3002

Development

Common Commands

pnpm dev              # Start all apps (API + Web)
pnpm build            # Build all packages
pnpm lint             # Run ESLint
pnpm typecheck        # TypeScript type checking
pnpm format           # Format with Prettier
pnpm test             # Run unit/integration tests

Database

pnpm db:generate      # Regenerate Prisma client
pnpm db:migrate:dev   # Create and apply migrations
pnpm db:migrate:deploy # Apply migrations (CI/production)
pnpm db:seed          # Seed database
pnpm db:studio        # Open Prisma Studio (visual editor)
pnpm db:reset         # Reset database (destructive)

E2E Testing

pnpm test:e2e         # Run all E2E tests
pnpm test:e2e:api     # API tests only
pnpm test:e2e:web     # Web UI tests only
pnpm test:e2e:report  # Open HTML test report

API Modules

All API routes are prefixed with /api/v1/. Each module follows Domain-Driven Design with presentation/, application/, domain/, and infrastructure/ layers.

Module	Description
auth	Registration, login, JWT + refresh token rotation, OAuth (Google/Zalo), KYC, user data export/deletion
listings	Property listing CRUD, status workflow, media management
search	Typesense full-text search with geo-spatial filters, saved searches
payments	VNPay, MoMo, ZaloPay integration with callback verification
subscriptions	Plan management, usage tracking, quota enforcement
notifications	Email and in-app notification history & preferences
admin	Listing moderation, user management, audit logs
analytics	Market reports, price indices, AVM integration
agents	Real estate agent profiles and verification
inquiries	Property inquiry management
leads	Lead tracking and conversion
reviews	Property reviews and ratings
health	Liveness and readiness health checks
mcp	MCP server bridge (property search, valuation, analytics)
metrics	Prometheus metrics and web vitals collection
shared	Cross-cutting concerns: guards, pipes, filters, Prisma/Redis services

Documentation

Document	Description
Development Environment	Docker setup and local services
Architecture	System design, data flow, module structure
API Endpoints	REST API endpoint reference
API Error Codes	Error response format and all error codes
Deployment	Production deployment guide
Backup & Restore	Backup procedures and disaster recovery
Contributing	Error handling conventions and coding patterns

License

Proprietary — All rights reserved.