goodgo-platform/AGENTS.md

GoodGo Platform

Vietnamese real estate platform — monorepo powered by pnpm workspaces + Turborepo.

Quick Start

pnpm install
pnpm db:generate        # Generate Prisma client
pnpm db:migrate:dev     # Run migrations (needs PostgreSQL 16 + PostGIS)
pnpm db:seed            # Seed sample data (users, listings, districts)
pnpm dev                # Start all apps (API :3001, Web :3000)

Architecture

• apps/api — NestJS backend (CQRS, DDD, clean architecture)
• apps/web — Next.js 15 frontend (App Router, Tailwind, Zustand)
• libs/ai-services — Python FastAPI AI/ML services (AVM, content moderation, NLP)
• libs/mcp-servers — MCP tool server library (property search, analytics, valuation)
• prisma/ — Schema, migrations, seed scripts
• e2e/ — Playwright E2E tests (API + Web projects)

Key Commands

Command	Description
pnpm lint	ESLint (auto-fixable with --fix)
pnpm typecheck	TypeScript type checking
pnpm test	Unit tests via Vitest (API only)
pnpm build	Production build (all packages)
pnpm test:e2e	Playwright E2E tests
pnpm db:studio	Prisma Studio GUI

Tech Stack

• Runtime: Node.js >= 22, pnpm 10
• Backend: NestJS, Prisma ORM, PostgreSQL 16 + PostGIS, Redis
• Frontend: Next.js 15, React 18, Tailwind CSS 3, Zustand, Mapbox GL
• Testing: Vitest (unit), Playwright (E2E)
• CI: GitHub Actions (lint → typecheck → test → build)

Project Structure (API)

apps/api/src/modules/
  auth/          — Authentication (JWT, OAuth, refresh tokens, CSRF)
  listings/      — Property listings CRUD
  payments/      — VNPay, MoMo, ZaloPay payment integration
  subscriptions/ — Plans, quotas, usage tracking
  admin/         — Moderation, KYC, user management, audit logs
  analytics/     — Market data, heatmaps, price trends, AVM
  search/        — Geo search, full-text search (Typesense), saved searches
  notifications/ — Email, in-app notifications
  agents/        — Agent profiles, quality scores
  inquiries/     — Property inquiry management
  leads/         — Lead tracking and conversion
  reviews/       — Property reviews and ratings
  health/        — Liveness and readiness probes
  metrics/       — Prometheus metrics, web vitals
  mcp/           — MCP tool server endpoints
  shared/        — Domain primitives, guards, pipes, logging

Each module follows DDD layers: domain/ → application/ → infrastructure/ → presentation/.

Project Structure (Libs)

libs/
  ai-services/     — Python FastAPI AI/ML services (AVM, content moderation, NLP)
  mcp-servers/     — MCP tool server library (property search, analytics, valuation)

Database

• PostgreSQL 16 with PostGIS extension for geospatial queries
• 22 models (User, Property, Listing, Payment, Subscription, etc.)
• Migrations in prisma/migrations/
• Seed data covers: users, agents, Ho Chi Minh City districts/wards, sample properties, subscription plans

Environment Variables

Required in .env:

• DATABASE_URL — PostgreSQL connection string
• JWT_SECRET, JWT_REFRESH_SECRET — Auth tokens
• VNPAY_* — Payment gateway config
• MAPBOX_TOKEN — Map rendering (frontend)
• REDIS_URL — Cache layer (optional for dev)

Conventions

• Import order enforced by eslint-plugin-import-x (external → internal → relative)
• Path aliases: @modules/* in API, @/* in Web
• Vietnamese UI text throughout (property types, districts, currency in VND)
• All handlers return typed Result<T> or throw DomainException
• Commit messages follow conventional commits